a64l(3) - Linux manual page

man7.org > Linux > man-pages

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

A64L(3)                      Linux Programmer's Manual                     A64L(3)

NAME top

       a64l, l64a - convert between long and base-64

SYNOPSIS top

       #include <stdlib.h>

       long a64l(char *str64);

       char *l64a(long value);

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

       a64l(), l64a():
           _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       These functions provide a conversion between 32-bit long integers and
       little-endian base-64 ASCII strings (of length zero to six).  If the string
       used as argument for a64l() has length greater than six, only the first six
       bytes are used.  If the type long has more than 32 bits, then l64a() uses
       only the low order 32 bits of value, and a64l() sign-extends its 32-bit
       result.

       The 64 digits in the base-64 system are:

              '.'  represents a 0
              '/'  represents a 1
              0-9  represent  2-11
              A-Z  represent 12-37
              a-z  represent 38-63

       So 123 = 59*64^0 + 1*64^1 = "v/".

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The value returned by l64a() may be a pointer to a static buffer, possibly
       overwritten by later calls.

       The behavior of l64a() is undefined when value is negative.  If value is
       zero, it returns an empty string.

       These functions are broken in glibc before 2.2.5 (puts most significant
       digit first).

       This is not the encoding used by uuencode(1).

SEE ALSO top

       uuencode(1), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             A64L(3)

HTML rendering created 2012-12-20 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project


abort(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ABORT(3)                     Linux Programmer's Manual                    ABORT(3)

NAME top

       abort - cause abnormal process termination

SYNOPSIS top

       #include <stdlib.h>

       void abort(void);

DESCRIPTION top

       The abort() first unblocks the SIGABRT signal, and then raises that signal
       for the calling process.  This results in the abnormal termination of the
       process unless the SIGABRT signal is caught and the signal handler does not
       return (see longjmp(3)).

       If the abort() function causes process termination, all open streams are
       closed and flushed.

       If the SIGABRT signal is ignored, or caught by a handler that returns, the
       abort() function will still terminate the process.  It does this by
       restoring the default disposition for SIGABRT and then raising the signal
       for a second time.

RETURN VALUE top

       The abort() function never returns.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD, C89, C99.

SEE ALSO top

       gdb(1), sigaction(2), exit(3), longjmp(3), raise(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-12-15                            ABORT(3)


abs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ABS(3)                       Linux Programmer's Manual                      ABS(3)

NAME top

       abs, labs, llabs, imaxabs - compute the absolute value of an integer

SYNOPSIS top

       #include <stdlib.h>

       int abs(int j);
       long int labs(long int j);
       long long int llabs(long long int j);

       #include <inttypes.h>

       intmax_t imaxabs(intmax_t j);

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

       llabs():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The abs() function computes the absolute value of the integer argument j.
       The labs(), llabs() and imaxabs() functions compute the absolute value of
       the argument j of the appropriate integer type for the function.

RETURN VALUE top

       Returns the absolute value of the integer argument, of the appropriate
       integer type for the function.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD, C99.  C89 only includes the abs() and labs()
       functions; the functions llabs() and imaxabs() were added in C99.

NOTES top

       Trying to take the absolute value of the most negative integer is not
       defined.

       The llabs() function is included in glibc since version 2.0, but is not in
       libc5 or libc4.  The imaxabs() function is included in glibc since version
       2.1.1.

       For llabs() to be declared, it may be necessary to define _ISOC99_SOURCE or
       _ISOC9X_SOURCE (depending on the version of glibc) before including any
       standard headers.

       GCC handles abs() and labs() as built-in functions.  GCC 3.0 also handles
       llabs() and imaxabs() as built-ins.

SEE ALSO top

       cabs(3), ceil(3), fabs(3), floor(3), rint(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                              ABS(3)


accept(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

ACCEPT(2)                    Linux Programmer's Manual                   ACCEPT(2)

NAME top

       accept - accept a connection on a socket

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/socket.h>

       int accept4(int sockfd, struct sockaddr *addr,
                   socklen_t *addrlen, int flags);

DESCRIPTION top

       The accept() system call is used with connection-based socket types
       (SOCK_STREAM, SOCK_SEQPACKET).  It extracts the first connection request on
       the queue of pending connections for the listening socket, sockfd, creates
       a new connected socket, and returns a new file descriptor referring to that
       socket.  The newly created socket is not in the listening state.  The
       original socket sockfd is unaffected by this call.

       The argument sockfd is a socket that has been created with socket(2), bound
       to a local address with bind(2), and is listening for connections after a
       listen(2).

       The argument addr is a pointer to a sockaddr structure.  This structure is
       filled in with the address of the peer socket, as known to the
       communications layer.  The exact format of the address returned addr is
       determined by the socket's address family (see socket(2) and the respective
       protocol man pages).  When addr is NULL, nothing is filled in; in this
       case, addrlen is not used, and should also be NULL.

       The addrlen argument is a value-result argument: the caller must initialize
       it to contain the size (in bytes) of the structure pointed to by addr; on
       return it will contain the actual size of the peer address.

       The returned address is truncated if the buffer provided is too small; in
       this case, addrlen will return a value greater than was supplied to the
       call.

       If no pending connections are present on the queue, and the socket is not
       marked as nonblocking, accept() blocks the caller until a connection is
       present.  If the socket is marked nonblocking and no pending connections
       are present on the queue, accept() fails with the error EAGAIN or
       EWOULDBLOCK.

       In order to be notified of incoming connections on a socket, you can use
       select(2) or poll(2).  A readable event will be delivered when a new
       connection is attempted and you may then call accept() to get a socket for
       that connection.  Alternatively, you can set the socket to deliver SIGIO
       when activity occurs on a socket; see socket(7) for details.

       For certain protocols which require an explicit confirmation, such as
       DECNet, accept() can be thought of as merely dequeuing the next connection
       request and not implying confirmation.  Confirmation can be implied by a
       normal read or write on the new file descriptor, and rejection can be
       implied by closing the new socket.  Currently only DECNet has these
       semantics on Linux.

       If flags is 0, then accept4() is the same as accept().  The following
       values can be bitwise ORed in flags to obtain different behavior:

       SOCK_NONBLOCK   Set the O_NONBLOCK file status flag on the new open file
                       description.  Using this flag saves extra calls to fcntl(2)
                       to achieve the same result.

       SOCK_CLOEXEC    Set the close-on-exec (FD_CLOEXEC) flag on the new file
                       descriptor.  See the description of the O_CLOEXEC flag in
                       open(2) for reasons why this may be useful.

RETURN VALUE top

       On success, these system calls return a nonnegative integer that is a
       descriptor for the accepted socket.  On error, -1 is returned, and errno is
       set appropriately.

Error Handling

       Linux accept() (and accept4()) passes already-pending network errors on the
       new socket as an error code from accept().  This behavior differs from
       other BSD socket implementations.  For reliable operation the application
       should detect the network errors defined for the protocol after accept()
       and treat them like EAGAIN by retrying.  In the case of TCP/IP, these are
       ENETDOWN, EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP,
       and ENETUNREACH.

ERRORS top

       EAGAIN or EWOULDBLOCK
              The socket is marked nonblocking and no connections are present to
              be accepted.  POSIX.1-2001 allows either error to be returned for
              this case, and does not require these constants to have the same
              value, so a portable application should check for both
              possibilities.

       EBADF  The descriptor is invalid.

       ECONNABORTED
              A connection has been aborted.

       EFAULT The addr argument is not in a writable part of the user address
              space.

       EINTR  The system call was interrupted by a signal that was caught before a
              valid connection arrived; see signal(7).

       EINVAL Socket is not listening for connections, or addrlen is invalid
              (e.g., is negative).

       EINVAL (accept4()) invalid value in flags.

       EMFILE The per-process limit of open file descriptors has been reached.

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

       ENOBUFS, ENOMEM
              Not enough free memory.  This often means that the memory allocation
              is limited by the socket buffer limits, not by the system memory.

       ENOTSOCK
              The descriptor references a file, not a socket.

       EOPNOTSUPP
              The referenced socket is not of type SOCK_STREAM.

       EPROTO Protocol error.

       In addition, Linux accept() may fail if:

       EPERM  Firewall rules forbid connection.

       In addition, network errors for the new socket and as defined for the
       protocol may be returned.  Various Linux kernels can return other errors
       such as ENOSR, ESOCKTNOSUPPORT, EPROTONOSUPPORT, ETIMEDOUT.  The value
       ERESTARTSYS may be seen during a trace.

VERSIONS top

       The accept4() system call is available starting with Linux 2.6.28; support
       in glibc is available starting with version 2.10.

CONFORMING TO top

       accept(): POSIX.1-2001, SVr4, 4.4BSD, (accept() first appeared in 4.2BSD).

       accept4() is a nonstandard Linux extension.

       On Linux, the new socket returned by accept() does not inherit file status
       flags such as O_NONBLOCK and O_ASYNC from the listening socket.  This
       behavior differs from the canonical BSD sockets implementation.  Portable
       programs should not rely on inheritance or noninheritance of file status
       flags and always explicitly set all required flags on the socket returned
       from accept().

NOTES top

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

       There may not always be a connection waiting after a SIGIO is delivered or
       select(2) or poll(2) return a readability event because the connection
       might have been removed by an asynchronous network error or another thread
       before accept() is called.  If this happens then the call will block
       waiting for the next connection to arrive.  To ensure that accept() never
       blocks, the passed socket sockfd needs to have the O_NONBLOCK flag set (see
       socket(7)).

The socklen_t type

       The third argument of accept() was originally declared as an int * (and is
       that under libc4 and libc5 and on many other systems like 4.x BSD, SunOS 4,
       SGI); a POSIX.1g draft standard wanted to change it into a size_t *, and
       that is what it is for SunOS 5.  Later POSIX drafts have socklen_t *, and
       so do the Single UNIX Specification and glibc2.  Quoting Linus Torvalds:

       "_Any_ sane library _must_ have "socklen_t" be the same size as int.
       Anything else breaks any BSD socket layer stuff.  POSIX initially did make
       it a size_t, and I (and hopefully others, but obviously not too many)
       complained to them very loudly indeed.  Making it a size_t is completely
       broken, exactly because size_t very seldom is the same size as "int" on
       64-bit architectures, for example.  And it has to be the same size as "int"
       because that's what the BSD socket interface is.  Anyway, the POSIX people
       eventually got a clue, and created "socklen_t".  They shouldn't have
       touched it in the first place, but once they did they felt it had to have a
       named type for some unfathomable reason (probably somebody didn't like
       losing face over having done the original stupid thing, so they silently
       just renamed their blunder)."

EXAMPLE top

       See bind(2).

SEE ALSO top

       bind(2), connect(2), listen(2), select(2), socket(2), socket(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10                           ACCEPT(2)


access(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ACCESS(2)                    Linux Programmer's Manual                   ACCESS(2)

NAME top

       access - check real user's permissions for a file

SYNOPSIS top

       #include <unistd.h>

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

DESCRIPTION top

       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 determine
       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 top

       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 top

       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 top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       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.  (In the example just described, a safer
       alternative would be to temporarily switch the process's effective user ID
       to the real ID and then call open(2).)

       access() always dereferences symbolic links.  If you need to check the
       permissions on a symbolic link, use faccessat(2) with the flag
       AT_SYMLINK_NOFOLLOW.

       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 an 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 top

       In kernel 2.4 (and earlier) there is some strangeness in the handling of
       X_OK tests for superuser.  If all categories of execute permission are
       disabled for a nondirectory 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 underlying file system.  Since kernel
       2.6.20, access() honors this flag.

SEE ALSO top

       chmod(2), chown(2), faccessat(2), open(2), setgid(2), setuid(2), stat(2),
       euidaccess(3), credentials(7), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-24                           ACCESS(2)


acct(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ACCT(2)                      Linux Programmer's Manual                     ACCT(2)

NAME top

       acct - switch process accounting on or off

SYNOPSIS top

       #include <unistd.h>

       int acct(const char *filename);

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

       acct(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       The acct() system call enables or disables process accounting.  If called
       with the name of an existing file as its argument, accounting is turned on,
       and records for each terminating process are appended to filename as it
       terminates.  An argument of NULL causes accounting to be turned off.

RETURN VALUE top

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

ERRORS top

       EACCES Write permission is denied for the specified file, or search
              permission is denied for one of the directories in the path prefix
              of filename (see also path_resolution(7)), or filename is not a
              regular file.

       EFAULT filename points outside your accessible address space.

       EIO    Error writing to the file filename.

       EISDIR filename is a directory.

       ELOOP  Too many symbolic links were encountered in resolving filename.

       ENAMETOOLONG
              filename was too long.

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

       ENOENT The specified filename does not exist.

       ENOMEM Out of memory.

       ENOSYS BSD process accounting has not been enabled when the operating
              system kernel was compiled.  The kernel configuration parameter
              controlling this feature is CONFIG_BSD_PROCESS_ACCT.

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

       EPERM  The calling process has insufficient privilege to enable process
              accounting.  On Linux the CAP_SYS_PACCT capability is required.

       EROFS  filename refers to a file on a read-only file system.

       EUSERS There are no more free file structures or we ran out of memory.

CONFORMING TO top

       SVr4, 4.3BSD (but not POSIX).

NOTES top

       No accounting is produced for programs running when a system crash occurs.
       In particular, nonterminating processes are never accounted for.

       The structure of the records written to the accounting file is described in
       acct(5).

SEE ALSO top

       acct(5)

COLOPHON top

       This page is part of release 3.45 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-06-16                             ACCT(2)


acct(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ACCT(5)                      Linux Programmer's Manual                     ACCT(5)

NAME top

       acct - process accounting file

SYNOPSIS top

       #include <sys/acct.h>

DESCRIPTION top

       If the kernel is built with the process accounting option enabled
       (CONFIG_BSD_PROCESS_ACCT), then calling acct(2) starts process accounting,
       for example:

           acct("/var/log/pacct");

       When process accounting is enabled, the kernel writes a record to the
       accounting file as each process on the system terminates.  This record
       contains information about the terminated process, and is defined in
       <sys/acct.h> as follows:

           #define ACCT_COMM 16

           typedef u_int16_t comp_t;

           struct acct {
               char ac_flag;           /* Accounting flags */
               u_int16_t ac_uid;       /* Accounting user ID */
               u_int16_t ac_gid;       /* Accounting group ID */
               u_int16_t ac_tty;       /* Controlling terminal */
               u_int32_t ac_btime;     /* Process creation time
                                          (seconds since the Epoch) */
               comp_t    ac_utime;     /* User CPU time */
               comp_t    ac_stime;     /* System CPU time */
               comp_t    ac_etime;     /* Elapsed time */
               comp_t    ac_mem;       /* Average memory usage (kB) */
               comp_t    ac_io;        /* Characters transferred (unused) */
               comp_t    ac_rw;        /* Blocks read or written (unused) */
               comp_t    ac_minflt;    /* Minor page faults */
               comp_t    ac_majflt;    /* Major page faults */
               comp_t    ac_swaps;     /* Number of swaps (unused) */
               u_int32_t ac_exitcode;  /* Process termination status
                                          (see wait(2)) */
               char      ac_comm[ACCT_COMM+1];
                                       /* Command name (basename of last
                                          executed command; null-terminated) */
               char      ac_pad[X];    /* padding bytes */
           };

           enum {          /* Bits that may be set in ac_flag field */
               AFORK = 0x01,           /* Has executed fork, but no exec */
               ASU   = 0x02,           /* Used superuser privileges */
               ACORE = 0x08,           /* Dumped core */
               AXSIG = 0x10            /* Killed by a signal */
           };

       The comp_t data type is a floating-point value consisting of a 3-bit,
       base-8 exponent, and a 13-bit mantissa.  A value, c, of this type can be
       converted to a (long) integer as follows:

           v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3);

       The ac_utime, ac_stime, and ac_etime fields measure time in "clock ticks";
       divide these values by sysconf(_SC_CLK_TCK) to convert them to seconds.

Version 3 Accounting File Format

       Since kernel 2.6.8, an optional alternative version of the accounting file
       can be produced if the CONFIG_BSD_PROCESS_ACCT_V3 option is set when
       building the kernel.  With this option is set, the records written to the
       accounting file contain additional fields, and the width of c_uid and
       ac_gid fields is widened from 16 to 32 bits (in line with the increased
       size of UID and GIDs in Linux 2.4 and later).  The records are defined as
       follows:

           struct acct_v3 {
               char      ac_flag;      /* Flags */
               char      ac_version;   /* Always set to ACCT_VERSION (3) */
               u_int16_t ac_tty;       /* Controlling terminal */
               u_int32_t ac_exitcode;  /* Process termination status */
               u_int32_t ac_uid;       /* Real user ID */
               u_int32_t ac_gid;       /* Real group ID */
               u_int32_t ac_pid;       /* Process ID */
               u_int32_t ac_ppid;      /* Parent process ID */
               u_int32_t ac_btime;     /* Process creation time */
               float     ac_etime;     /* Elapsed time */
               comp_t    ac_utime;     /* User CPU time */
               comp_t    ac_stime;     /* System time */
               comp_t    ac_mem;       /* Average memory usage (kB) */
               comp_t    ac_io;        /* Characters transferred (unused) */
               comp_t    ac_rw;        /* Blocks read or written
                                          (unused) */
               comp_t    ac_minflt;    /* Minor page faults */
               comp_t    ac_majflt;    /* Major page faults */
               comp_t    ac_swaps;     /* Number of swaps (unused) */
               char      ac_comm[ACCT_COMM]; /* Command name */
           };

VERSIONS top

       The acct_v3 structure is defined in glibc since version 2.6.

CONFORMING TO top

       Process accounting originated on BSD.  Although it is present on most
       systems, it is not standardized, and the details vary somewhat between
       systems.

NOTES top

       Records in the accounting file are ordered by termination time of the
       process.

       In kernels up to and including 2.6.9, a separate accounting record is
       written for each thread created using the NPTL threading library; since
       Linux 2.6.10, a single accounting record is written for the entire process
       on termination of the last thread in the process.

       The proc/sys/kernel/acct file, described in proc(5), defines settings that
       control the behavior of process accounting when disk space runs low.

SEE ALSO top

       lastcomm(1), acct(2), accton(8), sa(8)

COLOPHON top

       This page is part of release 3.45 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-06-15                             ACCT(5)


acos(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ACOS(3)                      Linux Programmer's Manual                     ACOS(3)

NAME top

       acos, acosf, acosl - arc cosine function

SYNOPSIS top

       #include <math.h>

       double acos(double x);
       float acosf(float x);
       long double acosl(long double x);

       Link with -lm.

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

       acosf(), acosl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The acos() function calculates the arc cosine of x; that is the value whose
       cosine is x.

RETURN VALUE top

       On success, these functions return the arc cosine of x in radians; the
       return value is in the range [0, pi].

       If x is a NaN, a NaN is returned.

       If x is +1, +0 is returned.

       If x is positive infinity or negative infinity, a domain error occurs, and
       a NaN is returned.

       If x is outside the range [-1, 1], a domain error occurs, and a NaN is
       returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is outside the range [-1, 1]
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       asin(3), atan(3), atan2(3), cacos(3), cos(3), sin(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             ACOS(3)


acosh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ACOSH(3)                     Linux Programmer's Manual                    ACOSH(3)

NAME top

       acosh, acoshf, acoshl - inverse hyperbolic cosine function

SYNOPSIS top

       #include <math.h>

       double acosh(double x);
       float acoshf(float x);
       long double acoshl(long double x);

       Link with -lm.

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

       acosh():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       acoshf(), acoshl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The acosh() function calculates the inverse hyperbolic cosine of x; that is
       the value whose hyperbolic cosine is x.

RETURN VALUE top

       On success, these functions return the inverse hyperbolic cosine of x.

       If x is a NaN, a NaN is returned.

       If x is +1, +0 is returned.

       If x is positive infinity, positive infinity is returned.

       If x is less than 1, a domain error occurs, and the functions return a NaN.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is less than 1
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       asinh(3), atanh(3), cacosh(3), cosh(3), sinh(3), tanh(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            ACOSH(3)


getmntent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETMNTENT(3)                 Linux Programmer's Manual                GETMNTENT(3)

NAME top

       getmntent,  setmntent,  addmntent,  endmntent, hasmntopt, getmntent_r - get
       file system descriptor file entry

SYNOPSIS top

       #include <stdio.h>
       #include <mntent.h>

       FILE *setmntent(const char *filename, const char *type);

       struct mntent *getmntent(FILE *fp);

       int addmntent(FILE *fp, const struct mntent *mnt);

       int endmntent(FILE *fp);

       char *hasmntopt(const struct mntent *mnt, const char *opt);

       /* GNU extension */
       #include <mntent.h>

       struct mntent *getmntent_r(FILE *fp, struct mntent *mntbuf,
                                  char *buf, int buflen);

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

       getmntent_r(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       These routines are used to access the file system description file
       /etc/fstab and the mounted file system description file /etc/mtab.

       The setmntent() function opens the file system description file filename
       and returns a file pointer which can be used by getmntent().  The argument
       type is the type of access required and can take the same values as the
       mode argument of fopen(3).

       The getmntent() function reads the next line from the file system
       description file fp and returns a pointer to a structure containing the
       broken out fields from a line in the file.  The pointer points to a static
       area of memory which is overwritten by subsequent calls to getmntent().

       The addmntent() function adds the mntent structure mnt to the end of the
       open file fp.

       The endmntent() function closes the file system description file fp.

       The hasmntopt() function scans the mnt_opts field (see below) of the mntent
       structure mnt for a substring that matches opt.  See <mntent.h> and
       mount(8) for valid mount options.

       The reentrant getmntent_r() function is similar to getmntent(), but stores
       the struct mount in the provided *mntbuf and stores the strings pointed to
       by the entries in that struct in the provided array buf of size buflen.

       The mntent structure is defined in <mntent.h> as follows:

           struct mntent {
               char *mnt_fsname;   /* name of mounted file system */
               char *mnt_dir;      /* file system path prefix */
               char *mnt_type;     /* mount type (see mntent.h) */
               char *mnt_opts;     /* mount options (see mntent.h) */
               int   mnt_freq;     /* dump frequency in days */
               int   mnt_passno;   /* pass number on parallel fsck */
           };

       Since fields in the mtab and fstab files are separated by whitespace, octal
       escapes are used to represent the four characters space (\040), tab (\011),
       newline (\012) and backslash (\134) in those files when they occur in one
       of the four strings in a mntent structure.  The routines addmntent() and
       getmntent() will convert from string representation to escaped
       representation and back.

RETURN VALUE top

       The getmntent() and getmntent_r() functions return a pointer to the mntent
       structure or NULL on failure.

       The addmntent() function returns 0 on success and 1 on failure.

       The endmntent() function always returns 1.

       The hasmntopt() function returns the address of the substring if a match is
       found and NULL otherwise.

FILES top

       /etc/fstab          file system description file
       /etc/mtab           mounted file system description file

CONFORMING TO top

       The nonreentrant functions are from SunOS 4.1.3.  A routine getmntent_r()
       was introduced in HP-UX 10, but it returns an int.  The prototype shown
       above is glibc-only.

NOTES top

       System V also has a getmntent() function but the calling sequence differs,
       and the returned structure is different.  Under System V /etc/mnttab is
       used.  4.4BSD and Digital UNIX have a routine getmntinfo(), a wrapper
       around the system call getfsstat().

SEE ALSO top

       fopen(3), fstab(5), mount(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-09-15                        GETMNTENT(3)


addseverity(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ADDSEVERITY(3)               Linux Programmer's Manual              ADDSEVERITY(3)

NAME top

       addseverity - introduce new severity classes

SYNOPSIS top

       #include <fmtmsg.h>

       int addseverity(int severity, const char *s);

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

       addseverity(): _SVID_SOURCE

DESCRIPTION top

       This function allows the introduction of new severity classes which can be
       addressed by the severity argument of the fmtmsg(3) function.  By default
       that latter function only knows how to print messages for severity 0-4
       (with strings (none), HALT, ERROR, WARNING, INFO).  This call attaches the
       given string s to the given value severity.  If s is NULL, the severity
       class with the numeric value severity is removed.  It is not possible to
       overwrite or remove one of the default severity classes.  The severity
       value must be nonnegative.

RETURN VALUE top

       Upon success, the value MM_OK is returned.  Upon error, the return value is
       MM_NOTOK.  Possible errors include: out of memory, attempt to remove a
       nonexistent or default severity class.

VERSIONS top

       addseverity() is provided in glibc since version 2.1.

CONFORMING TO top

       This function is not specified in the X/Open Portability Guide although the
       fmtmsg(3) function is.  It is available on System V systems.

NOTES top

       New severity classes can also be added by setting the environment variable
       SEV_LEVEL.

SEE ALSO top

       fmtmsg(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-06-14                      ADDSEVERITY(3)


add_key(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | KEY TYPES | RETURN VALUE | ERRORS | LINKING | SEE ALSO | COLOPHON The Linux Programming Interface

ADD_KEY(2)                  Linux Key Management Calls                  ADD_KEY(2)

NAME top

       add_key - add a key to the kernel's key management facility

SYNOPSIS top

       #include <keyutils.h>

       key_serial_t add_key(const char *type, const char *description,
                            const void *payload, size_t plen,
                            key_serial_t keyring);

DESCRIPTION top

       add_key() asks the kernel to create or update a key of the given type and
       description, instantiate it with the payload of length plen, and to attach
       it to the nominated keyring and to return its serial number.

       The key type may reject the data if it's in the wrong format or in some
       other way invalid.

       If the destination keyring already contains a key that matches the
       specified type and description then, if the key type supports it, that key
       will be updated rather than a new key being created; if not, a new key will
       be created and it will displace the link to the extant key from the
       keyring.

       The destination keyring serial number may be that of a valid keyring to
       which the caller has write permission, or it may be a special keyring ID:

       KEY_SPEC_THREAD_KEYRING
              This specifies the caller's thread-specific keyring.

       KEY_SPEC_PROCESS_KEYRING
              This specifies the caller's process-specific keyring.

       KEY_SPEC_SESSION_KEYRING
              This specifies the caller's session-specific keyring.

       KEY_SPEC_USER_KEYRING
              This specifies the caller's UID-specific keyring.

       KEY_SPEC_USER_SESSION_KEYRING
              This specifies the caller's UID-session keyring.

KEY TYPES top

       There are a number of key types available in the core key management code,
       and these can be specified to this function:

       "user" Keys of the user-defined key type may contain a blob of arbitrary
              data, and the description may be any valid string, though it is
              preferred that the description be prefixed with a string
              representing the service to which the key is of interest and a colon
              (for instance "afs:mykey").  The payload may be empty or NULL for
              keys of this type.

       "keyring"
              Keyrings are special key types that may contain links to sequences
              of other keys of any type.  If this interface is used to create a
              keyring, then a NULL payload should be specified, and plen should be
              zero.

RETURN VALUE top

       On success add_key() returns the serial number of the key it created or
       updated.  On error, the value -1 will be returned and errno will have been
       set to an appropriate error.

ERRORS top

       ENOKEY The keyring doesn't exist.

       EKEYEXPIRED
              The keyring has expired.

       EKEYREVOKED
              The keyring has been revoked.

       EINVAL The payload data was invalid.

       ENOMEM Insufficient memory to create a key.

       EDQUOT The key quota for this user would be exceeded by creating this key
              or linking it to the keyring.

       EACCES The keyring wasn't available for modification by the user.

LINKING top

       Although this is a Linux system call, it is not present in libc but can be
       found rather in libkeyutils.  When linking, -lkeyutils should be specified
       to the linker.

SEE ALSO top

       keyctl(1), keyctl(2), request_key(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-25                          ADD_KEY(2)


adjtime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ADJTIME(3)                   Linux Programmer's Manual                  ADJTIME(3)

NAME top

       adjtime - correct the time to synchronize the system clock

SYNOPSIS top

       int adjtime(const struct timeval *delta, struct timeval *olddelta);

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

       adjtime(): _BSD_SOURCE

DESCRIPTION top

       The adjtime() function gradually adjusts the system clock (as returned by
       gettimeofday(2)).  The amount of time by which the clock is to be adjusted
       is specified in the structure pointed to by delta.  This structure has the
       following form:

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

       If the adjustment in delta is positive, then the system clock is speeded up
       by some small percentage (i.e., by adding a small amount of time to the
       clock value in each second) until the adjustment has been completed.  If
       the adjustment in delta is negative, then the clock is slowed down in a
       similar fashion.

       If a clock adjustment from an earlier adjtime() call is already in progress
       at the time of a later adjtime() call, and delta is not NULL for the later
       call, then the earlier adjustment is stopped, but any already completed
       part of that adjustment is not undone.

       If olddelta is not NULL, then the buffer that it points to is used to
       return the amount of time remaining from any previous adjustment that has
       not yet been completed.

RETURN VALUE top

       On success, adjtime() returns 0.  On failure, -1 is returned, and errno is
       set to indicate the error.

ERRORS top

       EINVAL The adjustment in delta is outside the permitted range.

       EPERM  The caller does not have sufficient privilege to adjust the time.
              Under Linux the CAP_SYS_TIME capability is required.

CONFORMING TO top

       4.3BSD, System V.

NOTES top

       The adjustment that adjtime() makes to the clock is carried out in such a
       manner that the clock is always monotonically increasing.  Using adjtime()
       to adjust the time prevents the problems that can be caused for certain
       applications (e.g., make(1)) by abrupt positive or negative jumps in the
       system time.

       adjtime() is intended to be used to make small adjustments to the system
       time.  Most systems impose a limit on the adjustment that can be specified
       in delta.  In the glibc implementation, delta must be less than or equal to
       (INT_MAX / 1000000 - 2) and greater than or equal to (INT_MIN / 1000000 +
       2) (respectively 2145 and -2145 seconds on i386).

BUGS top

       A longstanding bug meant that if delta was specified as NULL, no valid
       information about the outstanding clock adjustment was returned in
       olddelta.  (In this circumstance, adjtime() should return the outstanding
       clock adjustment, without changing it.)  This bug is fixed on systems with
       glibc 2.8 or later and Linux kernel 2.6.26 or later.

SEE ALSO top

       adjtimex(2), gettimeofday(2), time(7)

COLOPHON top

       This page is part of release 3.45 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-06-22                          ADJTIME(3)


adjtimex(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ADJTIMEX(2)                  Linux Programmer's Manual                 ADJTIMEX(2)

NAME top

       adjtimex - tune kernel clock

SYNOPSIS top

       #include <sys/timex.h>

       int adjtimex(struct timex *buf);

DESCRIPTION top

       Linux uses David L. Mills' clock adjustment algorithm (see RFC 1305).  The
       system call adjtimex() reads and optionally sets adjustment parameters for
       this algorithm.  It takes a pointer to a timex structure, updates kernel
       parameters from field values, and returns the same structure with current
       kernel values.  This structure is declared as follows:

           struct timex {
               int modes;           /* mode selector */
               long offset;         /* time offset (usec) */
               long freq;           /* frequency offset (scaled ppm) */
               long maxerror;       /* maximum error (usec) */
               long esterror;       /* estimated error (usec) */
               int status;          /* clock command/status */
               long constant;       /* pll time constant */
               long precision;      /* clock precision (usec) (read-only) */
               long tolerance;      /* clock frequency tolerance (ppm)
                                       (read-only) */
               struct timeval time; /* current time (read-only) */
               long tick;           /* usecs between clock ticks */
           };

       The modes field determines which parameters, if any, to set.  It may
       contain a bitwise-or combination of zero or more of the following bits:

           #define ADJ_OFFSET            0x0001 /* time offset */
           #define ADJ_FREQUENCY         0x0002 /* frequency offset */
           #define ADJ_MAXERROR          0x0004 /* maximum time error */
           #define ADJ_ESTERROR          0x0008 /* estimated time error */
           #define ADJ_STATUS            0x0010 /* clock status */
           #define ADJ_TIMECONST         0x0020 /* pll time constant */
           #define ADJ_TICK              0x4000 /* tick value */
           #define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime() */

       Ordinary users are restricted to a zero value for mode.  Only the superuser
       may set any parameters.

RETURN VALUE top

       On success, adjtimex() returns the clock state:

           #define TIME_OK   0 /* clock synchronized */
           #define TIME_INS  1 /* insert leap second */
           #define TIME_DEL  2 /* delete leap second */
           #define TIME_OOP  3 /* leap second in progress */
           #define TIME_WAIT 4 /* leap second has occurred */
           #define TIME_BAD  5 /* clock not synchronized */

       On failure, adjtimex() returns -1 and sets errno.

ERRORS top

       EFAULT buf does not point to writable memory.

       EINVAL An attempt is made to set buf.offset to a value outside the range
              -131071 to +131071, or to set buf.status to a value other than those
              listed above, or to set buf.tick to a value outside the range
              900000/HZ to 1100000/HZ, where HZ is the system timer interrupt
              frequency.

       EPERM  buf.mode is nonzero and the caller does not have sufficient
              privilege.  Under Linux the CAP_SYS_TIME capability is required.

CONFORMING TO top

       adjtimex() is Linux-specific and should not be used in programs intended to
       be portable.  See adjtime(3) for a more portable, but less flexible, method
       of adjusting the system clock.

SEE ALSO top

       settimeofday(2), adjtime(3), capabilities(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2004-05-27                         ADJTIMEX(2)


unimplemented(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UNIMPLEMENTED(2)             Linux Programmer's Manual            UNIMPLEMENTED(2)

NAME top

       afs_syscall,  break,  ftime, getpmsg, gtty, lock, madvise1, mpx, prof, pro-
       fil, putpmsg, security, stty, tuxcall, ulimit, vserver - unimplemented sys-
       tem calls

SYNOPSIS top

       Unimplemented system calls.

DESCRIPTION top

       These system calls are not implemented in the Linux 2.6.22 kernel.

RETURN VALUE top

       These system calls always return -1 and set errno to ENOSYS.

NOTES top

       Note that ftime(3), profil(3) and ulimit(3) are implemented as library
       functions.

       Some system calls, like alloc_hugepages(2), free_hugepages(2), ioperm(2),
       iopl(2), and vm86(2) only exist on certain architectures.

       Some system calls, like ipc(2), create_module(2), init_module(2), and
       delete_module(2) only exist when the Linux kernel was built with support
       for them.

SEE ALSO top

       syscalls(2)

COLOPHON top

       This page is part of release 3.45 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-05                    UNIMPLEMENTED(2)


aio(7) - Linux manual page

NAME | DESCRIPTION | NOTES | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

AIO(7)                       Linux Programmer's Manual                      AIO(7)

NAME top

       aio - POSIX asynchronous I/O overview

DESCRIPTION top

       The POSIX asynchronous I/O (AIO) interface allows applications to initiate
       one or more I/O operations that are performed asynchronously (i.e., in the
       background).  The application can elect to be notified of completion of the
       I/O operation in a variety of ways: by delivery of a signal, by
       instantiation of a thread, or no notification at all.

       The POSIX AIO interface consists of the following functions:

       aio_read(3)     Enqueue a read request.  This is the asynchronous analog of
                       read(2).

       aio_write(3)    Enqueue a write request.  This is the asynchronous analog
                       of write(2).

       aio_fsync(3)    Enqueue a sync request for the I/O operations on a file
                       descriptor.  This is the asynchronous analog of fsync(2)
                       and fdatasync(2).

       aio_error(3)    Obtain the error status of an enqueued I/O request.

       aio_return(3)   Obtain the return status of a completed I/O request.

       aio_suspend(3)  Suspend the caller until one or more of a specified set of
                       I/O requests completes.

       aio_cancel(3)   Attempt to cancel outstanding I/O requests on a specified
                       file descriptor.

       lio_listio(3)   Enqueue multiple I/O requests using a single function call.

       The aiocb ("asynchronous I/O control block") structure defines parameters
       that control an I/O operation.  An argument of this type is employed with
       all of the functions listed above.  This structure has the following form:

           #include <aiocb.h>

           struct aiocb {
               /* The order of these fields is implementation-dependent */

               int             aio_fildes;     /* File descriptor */
               off_t           aio_offset;     /* File offset */
               volatile void  *aio_buf;        /* Location of buffer */
               size_t          aio_nbytes;     /* Length of transfer */
               int             aio_reqprio;    /* Request priority */
               struct sigevent aio_sigevent;   /* Notification method */
               int             aio_lio_opcode; /* Operation to be performed;
                                                  lio_listio() only */

               /* Various implementation-internal fields not shown */
           };

           /* Operation codes for 'aio_lio_opcode': */

           enum { LIO_READ, LIO_WRITE, LIO_NOP };

       The fields of this structure are as follows:

       aio_filedes     The file descriptor on which the I/O operation is to be
                       performed.

       aio_offset      This is the file offset at which the I/O operation is to be
                       performed.

       aio_buf         This is the buffer used to transfer data for a read or
                       write operation.

       aio_nbytes      This is the size of the buffer pointed to by aio_buf.

       aio_reqprio     This field specifies a value that is subtracted from the
                       calling thread's real-time priority in order to determine
                       the priority for execution of this I/O request (see
                       pthread_setschedparam(3)).  The specified value must be
                       between 0 and the value returned by
                       sysconf(_SC_AIO_PRIO_DELTA_MAX).  This field is ignored for
                       file synchronization operations.

       aio_sigevent    This field is a structure that specifies how the caller is
                       to be notified when the asynchronous I/O operation
                       completes.  Possible values for aio_sigevent.sigev_notify
                       are SIGEV_NONE, SIGEV_SIGNAL, and SIGEV_THREAD.  See
                       sigevent(7) for further details.

       aio_lio_opcode  The type of operation to be performed; used only for
                       lio_listio(3).

       In addition to the standard functions listed above, the GNU C library
       provides the following extension to the POSIX AIO API:

       aio_init(3)     Set parameters for tuning the behavior of the glibc POSIX
                       AIO implementation.

NOTES top

       It is a good idea to zero out the control block buffer before use (see
       memset(3)).  The control block buffer and the buffer pointed to by aio_buf
       must not be changed while the I/O operation is in progress.  These buffers
       must remain valid until the I/O operation completes.

       Simultaneous asynchronous read or write operations using the same aiocb
       structure yield undefined results.

       The current Linux POSIX AIO implementation is provided in user space by
       glibc.  This has a number of limitations, most notably that maintaining
       multiple threads to perform I/O operations is expensive and scales poorly.
       Work has been in progress for some time on a kernel state-machine-based
       implementation of asynchronous I/O (see io_submit(2), io_setup(2),
       io_cancel(2), io_destroy(2), io_getevents(2)), but this implementation
       hasn't yet matured to the point where the POSIX AIO implementation can be
       completely reimplemented using the kernel system calls.

ERRORS top

       EINVAL The aio_reqprio field of the aiocb structure was less than 0, or was
              greater than the limit returned by the call
              sysconf(_SC_AIO_PRIO_DELTA_MAX).

VERSIONS top

       The POSIX AIO interfaces are provided by glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

EXAMPLE top

       The program below opens each of the files named in its command-line
       arguments and queues a request on the resulting file descriptor using
       aio_read(3).  The program then loops, periodically monitoring each of the
       I/O operations that is still in progress using aio_error(3).  Each of the
       I/O requests is set up to provide notification by delivery of a signal.
       After all I/O requests have completed, the program retrieves their status
       using aio_return(3).

       The SIGQUIT signal (generated by typing control-\) causes the program to
       request cancellation of each of the outstanding requests using
       aio_cancel(3).

       Here is an example of what we might see when running this program.  In this
       example, the program queues two requests to standard input, and these are
       satisfied by two lines of input containing "abc" and "x".

           $ ./a.out /dev/stdin /dev/stdin
           opened /dev/stdin on descriptor 3
           opened /dev/stdin on descriptor 4
           aio_error():
               for request 0 (descriptor 3): In progress
               for request 1 (descriptor 4): In progress
           abc
           I/O completion signal received
           aio_error():
               for request 0 (descriptor 3): I/O succeeded
               for request 1 (descriptor 4): In progress
           aio_error():
               for request 1 (descriptor 4): In progress
           x
           I/O completion signal received
           aio_error():
               for request 1 (descriptor 4): I/O succeeded
           All I/O requests completed
           aio_return():
               for request 0 (descriptor 3): 4
               for request 1 (descriptor 4): 2

Program source

       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>
       #include <errno.h>
       #include <aio.h>
       #include <signal.h>

       #define BUF_SIZE 20     /* Size of buffers for read operations */

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

       #define errMsg(msg)  do { perror(msg); } while (0)

       struct ioRequest {      /* Application-defined structure for tracking
                                  I/O requests */
           int           reqNum;
           int           status;
           struct aiocb *aiocbp;
       };

       static volatile sig_atomic_t gotSIGQUIT = 0;
                               /* On delivery of SIGQUIT, we attempt to
                                  cancel all outstanding I/O requests */

       static void             /* Handler for SIGQUIT */
       quitHandler(int sig)
       {
           gotSIGQUIT = 1;
       }

       #define IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */

       static void                 /* Handler for I/O completion signal */
       aioSigHandler(int sig, siginfo_t *si, void *ucontext)
       {
           write(STDOUT_FILENO, "I/O completion signal received\n", 31);

           /* The corresponding ioRequest structure would be available as
                  struct ioRequest *ioReq = si->si_value.sival_ptr;
              and the file descriptor would then be available via
                  ioReq->aiocbp->aio_fildes */
       }

       int
       main(int argc, char *argv[])
       {
           struct ioRequest *ioList;
           struct aiocb *aiocbList;
           struct sigaction sa;
           int s, j;
           int numReqs;        /* Total number of queued I/O requests */
           int openReqs;       /* Number of I/O requests still in progress */

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

           numReqs = argc - 1;

           /* Allocate our arrays */

           ioList = calloc(numReqs, sizeof(struct ioRequest));
           if (ioList == NULL)
               errExit("calloc");

           aiocbList = calloc(numReqs, sizeof(struct aiocb));
           if (aiocbList == NULL)
               errExit("calloc");

           /* Establish handlers for SIGQUIT and the I/O completion signal */

           sa.sa_flags = SA_RESTART;
           sigemptyset(&sa.sa_mask);

           sa.sa_handler = quitHandler;
           if (sigaction(SIGQUIT, &sa, NULL) == -1)
               errExit("sigaction");

           sa.sa_flags = SA_RESTART | SA_SIGINFO;
           sa.sa_sigaction = aioSigHandler;
           if (sigaction(IO_SIGNAL, &sa, NULL) == -1)
               errExit("sigaction");

           /* Open each file specified on the command line, and queue
              a read request on the resulting file descriptor */

           for (j = 0; j < numReqs; j++) {
               ioList[j].reqNum = j;
               ioList[j].status = EINPROGRESS;
               ioList[j].aiocbp = &aiocbList[j];

               ioList[j].aiocbp->aio_fildes = open(argv[j + 1], O_RDONLY);
               if (ioList[j].aiocbp->aio_fildes == -1)
                   errExit("open");
               printf("opened %s on descriptor %d\n", argv[j + 1],
                       ioList[j].aiocbp->aio_fildes);

               ioList[j].aiocbp->aio_buf = malloc(BUF_SIZE);
               if (ioList[j].aiocbp->aio_buf == NULL)
                   errExit("malloc");

               ioList[j].aiocbp->aio_nbytes = BUF_SIZE;
               ioList[j].aiocbp->aio_reqprio = 0;
               ioList[j].aiocbp->aio_offset = 0;
               ioList[j].aiocbp->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
               ioList[j].aiocbp->aio_sigevent.sigev_signo = IO_SIGNAL;
               ioList[j].aiocbp->aio_sigevent.sigev_value.sival_ptr =
                                       &ioList[j];

               s = aio_read(ioList[j].aiocbp);
               if (s == -1)
                   errExit("aio_read");
           }

           openReqs = numReqs;

           /* Loop, monitoring status of I/O requests */

           while (openReqs > 0) {
               sleep(3);       /* Delay between each monitoring step */

               if (gotSIGQUIT) {

                   /* On receipt of SIGQUIT, attempt to cancel each of the
                      outstanding I/O requests, and display status returned
                      from the cancellation requests */

                   printf("got SIGQUIT; canceling I/O requests: \n");

                   for (j = 0; j < numReqs; j++) {
                       if (ioList[j].status == EINPROGRESS) {
                           printf("    Request %d on descriptor %d:", j,
                                   ioList[j].aiocbp->aio_fildes);
                           s = aio_cancel(ioList[j].aiocbp->aio_fildes,
                                   ioList[j].aiocbp);
                           if (s == AIO_CANCELED)
                               printf("I/O canceled\n");
                           else if (s == AIO_NOTCANCELED)
                                   printf("I/O not canceled\n");
                           else if (s == AIO_ALLDONE)
                               printf("I/O all done\n");
                           else
                               errMsg("aio_cancel");
                       }
                   }

                   gotSIGQUIT = 0;
               }

               /* Check the status of each I/O request that is still
                  in progress */

               printf("aio_error():\n");
               for (j = 0; j < numReqs; j++) {
                   if (ioList[j].status == EINPROGRESS) {
                       printf("    for request %d (descriptor %d): ",
                               j, ioList[j].aiocbp->aio_fildes);
                       ioList[j].status = aio_error(ioList[j].aiocbp);

                       switch (ioList[j].status) {
                       case 0:
                           printf("I/O succeeded\n");
                           break;
                       case EINPROGRESS:
                           printf("In progress\n");
                           break;
                       case ECANCELED:
                           printf("Canceled\n");
                           break;
                       default:
                           errMsg("aio_error");
                           break;
                       }

                       if (ioList[j].status != EINPROGRESS)
                           openReqs--;
                   }
               }
           }

           printf("All I/O requests completed\n");

           /* Check status return of all I/O requests */

           printf("aio_return():\n");
           for (j = 0; j < numReqs; j++) {
               ssize_t s;

               s = aio_return(ioList[j].aiocbp);
               printf("    for request %d (descriptor %d): %ld\n",
                       j, ioList[j].aiocbp->aio_fildes, (long) s);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2), io_submit(2),
       aio_cancel(3), aio_error(3), aio_init(3), aio_read(3), aio_return(3),
       aio_write(3), lio_listio(3)

       <http://www.squid-cache.org/~adrian/Reprint-Pulavarty-OLS2003.pdf>

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                              AIO(7)


aio_cancel(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_CANCEL(3)                Linux Programmer's Manual               AIO_CANCEL(3)

NAME top

       aio_cancel - cancel an outstanding asynchronous I/O request

SYNOPSIS top

       #include <aio.h>

       int aio_cancel(int fd, struct aiocb *aiocbp);

       Link with -lrt.

DESCRIPTION top

       The aio_cancel() function attempts to cancel outstanding asynchronous I/O
       requests for the file descriptor fd.  If aiocbp is NULL, all such requests
       are canceled.  Otherwise, only the request described by the control block
       pointed to by aiocbp is canceled.  (See aio(7) for a description of the
       aiocb structure.)

       Normal asynchronous notification occurs for canceled requests (see aio(7)
       and sigevent(7)).  The request return status (aio_return(3)) is set to -1,
       and the request error status (aio_error(3)) is set to ECANCELED.  The
       control block of requests that cannot be canceled is not changed.

       If the request could not be canceled, then it will terminate in the usual
       way after performing the I/O operation.  (In this case, aio_error(3) will
       return the status EINPROGRESSS.)

       If aiocbp is not NULL, and fd differs from the file descriptor with which
       the asynchronous operation was initiated, unspecified results occur.

       Which operations are cancelable is implementation-defined.

RETURN VALUE top

       The aio_cancel() function returns one of the following values:

       AIO_CANCELED
              All requests were successfully canceled.

       AIO_NOTCANCELED
              At least one of the requests specified was not canceled because it
              was in progress.  In this case, one may check the status of
              individual requests using aio_error(3).

       AIO_ALLDONE
              All requests had already been completed before the call.

       -1     An error occurred.  The cause of the error can be found by
              inspecting errno.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       ENOSYS aio_cancel() is not implemented.

VERSIONS top

       The aio_cancel() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

EXAMPLE top

       See aio(7).

SEE ALSO top

       aio_error(3), aio_fsync(3), aio_read(3), aio_return(3), aio_suspend(3),
       aio_write(3), lio_listio(3), aio(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                       AIO_CANCEL(3)


aio_error(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_ERROR(3)                 Linux Programmer's Manual                AIO_ERROR(3)

NAME top

       aio_error - get error status of asynchronous I/O operation

SYNOPSIS top

       #include <aio.h>

       int aio_error(const struct aiocb *aiocbp);

       Link with -lrt.

DESCRIPTION top

       The aio_error() function returns the error status for the asynchronous I/O
       request with control block pointed to by aiocbp.  (See aio(7) for a
       description of the aiocb structure.)

RETURN VALUE top

       This function returns one of the following:

       *  EINPROGRESS, if the request has not been completed yet.

       *  ECANCELED, if the request was canceled.

       *  0, if the request completed successfully.

       *  A positive error number, if the asynchronous I/O operation failed.  This
          is the same value that would have been stored in the errno variable in
          the case of a synchronous read(2), write(2), fsync(2), or fdatasync(2)
          call.

ERRORS top

       EINVAL aiocbp does not point at a control block for an asynchronous I/O
              request of which the return status (see aio_return(3)) has not been
              retrieved yet.

       ENOSYS aio_error() is not implemented.

VERSIONS top

       The aio_error() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

EXAMPLE top

       See aio(7).

SEE ALSO top

       aio_cancel(3), aio_fsync(3), aio_read(3), aio_return(3), aio_suspend(3),
       aio_write(3), lio_listio(3), aio(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                        AIO_ERROR(3)


aio_fsync(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_FSYNC(3)                 Linux Programmer's Manual                AIO_FSYNC(3)

NAME top

       aio_fsync - asynchronous file synchronization

SYNOPSIS top

       #include <aio.h>

       int aio_fsync(int op, struct aiocb *aiocbp);

       Link with -lrt.

DESCRIPTION top

       The aio_fsync() function does a sync on all outstanding asynchronous I/O
       operations associated with aiocbp->aio_fildes.  (See aio(7) for a
       description of the aiocb structure.)

       More precisely, if op is O_SYNC, then all currently queued I/O operations
       shall be completed as if by a call of fsync(2), and if op is O_DSYNC, this
       call is the asynchronous analog of fdatasync(2).

       Note that this is a request only; it does not wait for I/O completion.

       Apart from aio_fildes, the only field in the structure pointed to by aiocbp
       that is used by this call is the aio_sigevent field (a sigevent structure,
       described in sigevent(7)), which indicates the desired type of asynchronous
       notification at completion.  All other fields are ignored.

RETURN VALUE top

       On success (the sync request was successfully queued) this function returns
       0.  On error -1 is returned, and errno is set appropriately.

ERRORS top

       EAGAIN Out of resources.

       EBADF  aio_fildes is not a valid file descriptor open for writing.

       EINVAL Synchronized I/O is not supported for this file, or op is not O_SYNC
              or O_DSYNC.

       ENOSYS aio_fsync() is not implemented.

VERSIONS top

       The aio_fsync() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

SEE ALSO top

       aio_cancel(3), aio_error(3), aio_read(3), aio_return(3), aio_suspend(3),
       aio_write(3), lio_listio(3), aio(7), sigevent(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                        AIO_FSYNC(3)


aio_init(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_INIT(3)                  Linux Programmer's Manual                 AIO_INIT(3)

NAME top

       aio_init - asynchronous I/O initialization

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <aio.h>

       void aio_init(const struct aioinit *init);

       Link with -lrt.

DESCRIPTION top

       The GNU-specific aio_init() function allows the caller to provide tuning
       hints to the glibc POSIX AIO implementation.  Use of this function is
       optional, but to be effective, it must be called before employing any other
       functions in the POSIX AIO API.

       The tuning information is provided in the buffer pointed to by the argument
       init.  This buffer is a structure of the following form:

           struct aioinit {
               int aio_threads;    /* Maximum number of threads */
               int aio_num;        /* Number of expected simultaneous
                                      requests */
               int aio_locks;      /* Not used */
               int aio_usedba;     /* Not used */
               int aio_debug;      /* Not used */
               int aio_numusers;   /* Not used */
               int aio_idle_time;  /* Number of seconds before idle thread
                                      terminates (since glibc 2.2) */
               int aio_reserved;
           };

       The following fields are used in the aioinit structure:

       aio_threads    This field specifies the maximum number of worker threads
                      that may be used by the implementation.  If the number of
                      outstanding I/O operations exceeds this limit, then excess
                      operations will be queued until a worker thread becomes
                      free.  If this field is specified with a value less than 1,
                      the value 1 is used.  The default value is 20.

       aio_num        This field should specify the maximum number of simultaneous
                      I/O requests that the caller expects to enqueue.  If a value
                      less than 32 is specified for this field, it is rounded up
                      to 32.  The default value is 64.

       aio_idle_time  This field specifies the amount of time in seconds that a
                      worker thread should wait for further requests before
                      terminating, after having completed a previous request.  The
                      default value is 1.

VERSIONS top

       The aio_init() function is available since glibc 2.1.

CONFORMING TO top

       This function is a GNU extension.

SEE ALSO top

       aio(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-26                         AIO_INIT(3)


aio_read(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_READ(3)                  Linux Programmer's Manual                 AIO_READ(3)

NAME top

       aio_read - asynchronous read

SYNOPSIS top

       #include <aio.h>

       int aio_read(struct aiocb *aiocbp);

       Link with -lrt.

DESCRIPTION top

       The aio_read() function queues the I/O request described by the buffer
       pointed to by aiocbp.  This function is the asynchronous analog of read(2).
       The arguments of the call

           read(fd, buf, count)

       correspond (in order) to the fields aio_fildes, aio_buf, and aio_nbytes of
       the structure pointed to by aiocbp.  (See aio(7) for a description of the
       aiocb structure.)

       The data is read starting at the absolute file offset aiocbp->aio_offset,
       regardless of the current file offset.  After the call, the value of the
       current file offset is unspecified.

       The "asynchronous" means that this call returns as soon as the request has
       been enqueued; the read may or may not have completed when the call
       returns.  One tests for completion using aio_error(3).  The return status
       of a completed I/O operation can be obtained by aio_return(3).
       Asynchronous notification of I/O completion can be obtained by setting
       aiocbp->aio_sigevent appropriately; see sigevent(7) for details.

       If _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the
       asynchronous operation is submitted at a priority equal to that of the
       calling process minus aiocbp->aio_reqprio.

       The field aiocbp->aio_lio_opcode is ignored.

       No data is read from a regular file beyond its maximum offset.

RETURN VALUE top

       On success, 0 is returned.  On error the request is not enqueued, -1 is
       returned, and errno is set appropriately.  If an error is only detected
       later, it will be reported via aio_return(3) (returns status -1) and
       aio_error(3) (error status--whatever one would have gotten in errno, such
       as EBADF).

ERRORS top

       EAGAIN Out of resources.

       EBADF  aio_fildes is not a valid file descriptor open for reading.

       EINVAL One or more of aio_offset, aio_reqprio, or aio_nbytes are invalid.

       ENOSYS aio_read() is not implemented.

       EOVERFLOW
              The file is a regular file, we start reading before end-of-file and
              want at least one byte, but the starting position is past the
              maximum offset for this file.

VERSIONS top

       The aio_read() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

NOTES top

       It is a good idea to zero out the control block before use.  The control
       block must not be changed while the read operation is in progress.  The
       buffer area being read into must not be accessed during the operation or
       undefined results may occur.  The memory areas involved must remain valid.

       Simultaneous I/O operations specifying the same aiocb structure produce
       undefined results.

EXAMPLE top

       See aio(7).

SEE ALSO top

       aio_cancel(3), aio_error(3), aio_fsync(3), aio_return(3), aio_suspend(3),
       aio_write(3), lio_listio(3), aio(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                         AIO_READ(3)


aio_return(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_RETURN(3)                Linux Programmer's Manual               AIO_RETURN(3)

NAME top

       aio_return - get return status of asynchronous I/O operation

SYNOPSIS top

       #include <aio.h>

       ssize_t aio_return(struct aiocb *aiocbp);

       Link with -lrt.

DESCRIPTION top

       The aio_return() function returns the final return status for the
       asynchronous I/O request with control block pointed to by aiocbp.  (See
       aio(7) for a description of the aiocb structure.)

       This function should be called only once for any given request, after
       aio_error(3) returns something other than EINPROGRESS.

RETURN VALUE top

       If the asynchronous I/O operation has completed, this function returns the
       value that would have been returned in case of a synchronous read(2),
       write(2), fsync(2) or fdatasync(2), call.

       If the asynchronous I/O operation has not yet completed, the return value
       and effect of aio_return() are undefined.

ERRORS top

       EINVAL aiocbp does not point at a control block for an asynchronous I/O
              request of which the return status has not been retrieved yet.

       ENOSYS aio_return() is not implemented.

VERSIONS top

       The aio_return() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

EXAMPLE top

       See aio(7).

SEE ALSO top

       aio_cancel(3), aio_error(3), aio_fsync(3), aio_read(3), aio_suspend(3),
       aio_write(3), lio_listio(3), aio(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                       AIO_RETURN(3)


aio_suspend(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_SUSPEND(3)               Linux Programmer's Manual              AIO_SUSPEND(3)

NAME top

       aio_suspend - wait for asynchronous I/O operation or timeout

SYNOPSIS top

       #include <aio.h>

       int aio_suspend(const struct aiocb * const aiocb_list[],
                       int nitems, const struct timespec *timeout);

       Link with -lrt.

DESCRIPTION top

       The aio_suspend() function suspends the calling thread until one of the
       following occurs:

       *  One or more of the asynchronous I/O requests in the list aiocb_list has
          completed.

       *  A signal is delivered.

       *  timeout is not NULL and the specified time interval has passed.  (For
          details of the timespec structure, see nanosleep(2).)

       The nitems argument specifies the number of items in aiocb_list.  Each item
       in the list pointed to by aiocb_list must be either NULL (and then is
       ignored), or a pointer to a control block on which I/O was initiated using
       aio_read(3), aio_write(3), or lio_listio(3).  (See aio(7) for a description
       of the aiocb structure.)

       If CLOCK_MONOTONIC is supported, this clock is used to measure the timeout
       interval (see clock_gettime(3)).

RETURN VALUE top

       If this function returns after completion of one of the I/O requests
       specified in aiocb_list, 0 is returned.  Otherwise, -1 is returned, and
       errno is set to indicate the error.

ERRORS top

       EAGAIN The call timed out before any of the indicated operations had
              completed.

       EINTR  The call was ended by signal (possibly the completion signal of one
              of the operations we were waiting for); see signal(7).

       ENOSYS aio_suspend() is not implemented.

VERSIONS top

       The aio_suspend() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

NOTES top

       One can achieve polling by using a non-NULL timeout that specifies a zero
       time interval.

       If one or more of the asynchronous I/O operations specified in aiocb_list
       has already completed at the time of the call to aio_suspend(), then the
       call returns immediately.

       To determine which I/O operations have completed after a successful return
       from aio_suspend(), use aio_error(3) to scan the list of aiocb structures
       pointed to by aiocb_list.

SEE ALSO top

       aio_cancel(3), aio_error(3), aio_fsync(3), aio_read(3), aio_return(3),
       aio_write(3), lio_listio(3), aio(7), time(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                      AIO_SUSPEND(3)


aio_write(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

AIO_WRITE(3)                 Linux Programmer's Manual                AIO_WRITE(3)

NAME top

       aio_write - asynchronous write

SYNOPSIS top

       #include <aio.h>

       int aio_write(struct aiocb *aiocbp);

       Link with -lrt.

DESCRIPTION top

       The aio_write() function queues the I/O request described by the buffer
       pointed to by aiocbp.  This function is the asynchronous analog of
       write(2).  The arguments of the call

           write(fd, buf, count)

       correspond (in order) to the fields aio_fildes, aio_buf, and aio_nbytes of
       the structure pointed to by aiocbp.  (See aio(7) for a description of the
       aiocb structure.)

       If O_APPEND is not set, the data is written starting at the absolute file
       offset aiocbp->aio_offset, regardless of the current file offset.  If
       O_APPEND is set, data is written at the end of the file in the same order
       as aio_write() calls are made.  After the call, the value of the current
       file offset is unspecified.

       The "asynchronous" means that this call returns as soon as the request has
       been enqueued; the write may or may not have completed when the call
       returns.  One tests for completion using aio_error(3).  The return status
       of a completed I/O operation can be obtained aio_return(3).  Asynchronous
       notification of I/O completion can be obtained by setting
       aiocbp->aio_sigevent appropriately; see sigevent(7) for details.

       If _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the
       asynchronous operation is submitted at a priority equal to that of the
       calling process minus aiocbp->aio_reqprio.

       The field aiocbp->aio_lio_opcode is ignored.

       No data is written to a regular file beyond its maximum offset.

RETURN VALUE top

       On success, 0 is returned.  On error the request is not enqueued, -1 is
       returned, and errno is set appropriately.  If an error is only detected
       later, it will be reported via aio_return(3) (returns status -1) and
       aio_error(3) (error status--whatever one would have gotten in errno, such
       as EBADF).

ERRORS top

       EAGAIN Out of resources.

       EBADF  aio_fildes is not a valid file descriptor open for writing.

       EFBIG  The file is a regular file, we want to write at least one byte, but
              the starting position is at or beyond the maximum offset for this
              file.

       EINVAL One or more of aio_offset, aio_reqprio, aio_nbytes are invalid.

       ENOSYS aio_write() is not implemented.

VERSIONS top

       The aio_write() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

NOTES top

       It is a good idea to zero out the control block before use.  The control
       block must not be changed while the write operation is in progress.  The
       buffer area being written out must not be accessed during the operation or
       undefined results may occur.  The memory areas involved must remain valid.

       Simultaneous I/O operations specifying the same aiocb structure produce
       undefined results.

SEE ALSO top

       aio_cancel(3), aio_error(3), aio_fsync(3), aio_read(3), aio_return(3),
       aio_suspend(3), lio_listio(3), aio(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                        AIO_WRITE(3)


alarm(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ALARM(2)                     Linux Programmer's Manual                    ALARM(2)

NAME top

       alarm - set an alarm clock for delivery of a signal

SYNOPSIS top

       #include <unistd.h>

       unsigned int alarm(unsigned int seconds);

DESCRIPTION top

       alarm() arranges for a SIGALRM signal to be delivered to the calling
       process in seconds seconds.

       If seconds is zero, no new alarm() is scheduled.

       In any event any previously set alarm() is canceled.

RETURN VALUE top

       alarm() returns the number of seconds remaining until any previously
       scheduled alarm was due to be delivered, or zero if there was no previously
       scheduled alarm.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD.

NOTES top

       alarm() and setitimer(2) share the same timer; calls to one will interfere
       with use of the other.

       sleep(3) may be implemented using SIGALRM; mixing calls to alarm() and
       sleep(3) is a bad idea.

       Scheduling delays can, as ever, cause the execution of the process to be
       delayed by an arbitrary amount of time.

SEE ALSO top

       gettimeofday(2), pause(2), select(2), setitimer(2), sigaction(2),
       signal(2), sleep(3), time(7)

COLOPHON top

       This page is part of release 3.45 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-06-12                            ALARM(2)


posix_memalign(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

POSIX_MEMALIGN(3)            Linux Programmer's Manual           POSIX_MEMALIGN(3)

NAME top

       posix_memalign, aligned_alloc, memalign, valloc, pvalloc - allocate aligned
       memory

SYNOPSIS top

       #include <stdlib.h>

       int posix_memalign(void **memptr, size_t alignment, size_t size);
       void *aligned_alloc(size_t alignment, size_t size);
       void *valloc(size_t size);

       #include <malloc.h>

       void *memalign(size_t alignment, size_t size);
       void *pvalloc(size_t size);

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

       posix_memalign(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

       aligned_alloc(): _ISOC11_SOURCE

       valloc():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
               (The (nonstandard) header file <malloc.h> also exposes the declara-
               tion of valloc(); no feature test macros are required.)

DESCRIPTION top

       The function posix_memalign() allocates size bytes and places the address
       of the allocated memory in *memptr.  The address of the allocated memory
       will be a multiple of alignment, which must be a power of two and a
       multiple of sizeof(void *).  If size is 0, then posix_memalign() returns
       either NULL, or a unique pointer value that can later be successfully
       passed to free(3).

       The obsolete function memalign() allocates size bytes and returns a pointer
       to the allocated memory.  The memory address will be a multiple of
       alignment, which must be a power of two.

       The function aligned_alloc() is the same as memalign(), except for the
       added restriction that size should be a multiple of alignment.

       The obsolete function valloc() allocates size bytes and returns a pointer
       to the allocated memory.  The memory address will be a multiple of the page
       size.  It is equivalent to memalign(sysconf(_SC_PAGESIZE),size).

       The obsolete function pvalloc() is similar to valloc(), but rounds the size
       of the allocation up to the next multiple of the system page size.

       For all of these functions, the memory is not zeroed.

RETURN VALUE top

       aligned_alloc(), memalign(), valloc(), and pvalloc() return a pointer to
       the allocated memory, or NULL if the request fails.

       posix_memalign() returns zero on success, or one of the error values listed
       in the next section on failure.  Note that errno is not set.

ERRORS top

       EINVAL The alignment argument was not a power of two, or was not a multiple
              of sizeof(void *).

       ENOMEM There was insufficient memory to fulfill the allocation request.

VERSIONS top

       The functions memalign(), valloc(), and pvalloc() have been available in
       all Linux libc libraries.

       The function aligned_alloc() was added to glibc in version 2.16.

       The function posix_memalign() is available since glibc 2.1.91.

CONFORMING TO top

       The function valloc() appeared in 3.0BSD.  It is documented as being
       obsolete in 4.3BSD, and as legacy in SUSv2.  It does not appear in
       POSIX.1-2001.

       The function pvalloc() is a GNU extension.

       The function memalign() appears in SunOS 4.1.3 but not in 4.4BSD.

       The function posix_memalign() comes from POSIX.1d.

       The function aligned_alloc() is specified in the C11 standard.

Headers

       Everybody agrees that posix_memalign() is declared in <stdlib.h>.

       On some systems memalign() is declared in <stdlib.h> instead of <malloc.h>.

       According to SUSv2, valloc() is declared in <stdlib.h>.  Libc4,5 and glibc
       declare it in <malloc.h>, and also in <stdlib.h> if suitable feature test
       macros are defined (see above).

NOTES top

       On many systems there are alignment restrictions, for example, on buffers
       used for direct block device I/O.  POSIX specifies the
       pathconf(path,_PC_REC_XFER_ALIGN) call that tells what alignment is needed.
       Now one can use posix_memalign() to satisfy this requirement.

       posix_memalign() verifies that alignment matches the requirements detailed
       above.  memalign() may not check that the alignment argument is correct.

       POSIX requires that memory obtained from posix_memalign() can be freed
       using free(3).  Some systems provide no way to reclaim memory allocated
       with memalign() or valloc() (because one can only pass to free(3) a pointer
       gotten from malloc(3), while, for example, memalign() would call malloc(3)
       and then align the obtained value).  The glibc implementation allows memory
       obtained from any of these functions to be reclaimed with free(3).

       The glibc malloc(3) always returns 8-byte aligned memory addresses, so
       these functions are only needed if you require larger alignment values.

SEE ALSO top

       brk(2), getpagesize(2), free(3), malloc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-23                   POSIX_MEMALIGN(3)


alloca(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ALLOCA(3)                    Linux Programmer's Manual                   ALLOCA(3)

NAME top

       alloca - allocate memory that is automatically freed

SYNOPSIS top

       #include <alloca.h>

       void *alloca(size_t size);

DESCRIPTION top

       The alloca() function allocates size bytes of space in the stack frame of
       the caller.  This temporary space is automatically freed when the function
       that called alloca() returns to its caller.

RETURN VALUE top

       The alloca() function returns a pointer to the beginning of the allocated
       space.  If the allocation causes stack overflow, program behavior is
       undefined.

CONFORMING TO top

       This function is not in POSIX.1-2001.

       There is evidence that the alloca() function appeared in 32V, PWB, PWB.2,
       3BSD, and 4BSD.  There is a man page for it in 4.3BSD.  Linux uses the GNU
       version.

NOTES top

       The alloca() function is machine- and compiler-dependent.  For certain
       applications, its use can improve efficiency compared to the use of
       malloc(3) plus free(3).  In certain cases, it can also simplify memory
       deallocation in applications that use longjmp(3) or siglongjmp(3).
       Otherwise, its use is discouraged.

       Because the space allocated by alloca() is allocated within the stack
       frame, that space is automatically freed if the function return is jumped
       over by a call to longjmp(3) or siglongjmp(3).

       Do not attempt to free(3) space allocated by alloca()!

Notes on the GNU Version

       Normally, gcc(1) translates calls to alloca() with inlined code.  This is
       not done when either the -ansi, -std=c89, -std=c99, or the -fno-builtin
       option is given (and the header <alloca.h> is not included).  But beware!
       By default the glibc version of <stdlib.h> includes <alloca.h> and that
       contains the line:

           #define alloca(size)   __builtin_alloca (size)

       with messy consequences if one has a private version of this function.

       The fact that the code is inlined means that it is impossible to take the
       address of this function, or to change its behavior by linking with a
       different library.

       The inlined code often consists of a single instruction adjusting the stack
       pointer, and does not check for stack overflow.  Thus, there is no NULL
       error return.

BUGS top

       There is no error indication if the stack frame cannot be extended.
       (However, after a failed allocation, the program is likely to receive a
       SIGSEGV signal if it attempts to access the unallocated space.)

       On many systems alloca() cannot be used inside the list of arguments of a
       function call, because the stack space reserved by alloca() would appear on
       the stack in the middle of the space for the function arguments.

SEE ALSO top

       brk(2), longjmp(3), malloc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-01-24                           ALLOCA(3)


alloc_hugepages(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | NOTES | COLOPHON The Linux Programming Interface

ALLOC_HUGEPAGES(2)           Linux Programmer's Manual          ALLOC_HUGEPAGES(2)

NAME top

       alloc_hugepages, free_hugepages - allocate or free huge pages

SYNOPSIS top

       void *alloc_hugepages(int key, void *addr, size_t len,
                             int prot, int flag);

       int free_hugepages(void *addr);

DESCRIPTION top

       The system calls alloc_hugepages() and free_hugepages() were introduced in
       Linux 2.5.36 and removed again in 2.5.54.  They existed only on i386 and
       ia64 (when built with CONFIG_HUGETLB_PAGE).  In Linux 2.4.20 the syscall
       numbers exist, but the calls fail with the error ENOSYS.

       On i386 the memory management hardware knows about ordinary pages (4 KiB)
       and huge pages (2 or 4 MiB).  Similarly ia64 knows about huge pages of
       several sizes.  These system calls serve to map huge pages into the
       process's memory or to free them again.  Huge pages are locked into memory,
       and are not swapped.

       The key argument is an identifier.  When zero the pages are private, and
       not inherited by children.  When positive the pages are shared with other
       applications using the same key, and inherited by child processes.

       The addr argument of free_hugepages() tells which page is being freed: it
       was the return value of a call to alloc_hugepages().  (The memory is first
       actually freed when all users have released it.)  The addr argument of
       alloc_hugepages() is a hint, that the kernel may or may not follow.
       Addresses must be properly aligned.

       The len argument is the length of the required segment.  It must be a
       multiple of the huge page size.

       The prot argument specifies the memory protection of the segment.  It is
       one of PROT_READ, PROT_WRITE, PROT_EXEC.

       The flag argument is ignored, unless key is positive.  In that case, if
       flag is IPC_CREAT, then a new huge page segment is created when none with
       the given key existed.  If this flag is not set, then ENOENT is returned
       when no segment with the given key exists.

RETURN VALUE top

       On success, alloc_hugepages() returns the allocated virtual address, and
       free_hugepages() returns zero.  On error, -1 is returned, and errno is set
       appropriately.

ERRORS top

       ENOSYS The system call is not supported on this kernel.

FILES top

       /proc/sys/vm/nr_hugepages Number of configured hugetlb pages.  This can be
       read and written.

       /proc/meminfo Gives info on the number of configured hugetlb pages and on
       their size in the three variables HugePages_Total, HugePages_Free,
       Hugepagesize.

CONFORMING TO top

       These calls are specific to Linux on Intel processors, and should not be
       used in programs intended to be portable.

NOTES top

       These system calls are gone; they existed only in Linux 2.5.36 through to
       2.5.54.  Now the hugetlbfs file system can be used instead.  Memory backed
       by huge pages (if the CPU supports them) is obtained by using mmap(2) to
       map files in this virtual file system.

       The maximal number of huge pages can be specified using the hugepages= boot
       parameter.

COLOPHON top

       This page is part of release 3.45 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-05-31                  ALLOC_HUGEPAGES(2)


scandir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SCANDIR(3)                   Linux Programmer's Manual                  SCANDIR(3)

NAME top

       scandir, alphasort, versionsort - scan a directory for matching entries

SYNOPSIS top

       #include <dirent.h>

       int scandir(const char *dirp, struct dirent ***namelist,
              int (*filter)(const struct dirent *),
              int (*compar)(const struct dirent **, const struct dirent **));

       int alphasort(const void *a, const void *b);

       int versionsort(const void *a, const void *b);

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

       scandir(), alphasort(): _BSD_SOURCE || _SVID_SOURCE
       versionsort(): _GNU_SOURCE

DESCRIPTION top

       The scandir() function scans the directory dirp, calling filter() on each
       directory entry.  Entries for which filter() returns nonzero are stored in
       strings allocated via malloc(3), sorted using qsort(3) with the comparison
       function compar(), and collected in array namelist which is allocated via
       malloc(3).  If filter is NULL, all entries are selected.

       The alphasort() and versionsort() functions can be used as the comparison
       function compar().  The former sorts directory entries using strcoll(3),
       the latter using strverscmp(3) on the strings (*a)->d_name and
       (*b)->d_name.

RETURN VALUE top

       The scandir() function returns the number of directory entries selected or
       -1 if an error occurs.

       The alphasort() and versionsort() functions return an integer less than,
       equal to, or greater than zero if the first argument is considered to be
       respectively less than, equal to, or greater than the second.

ERRORS top

       ENOENT The path in dirp does not exist.

       ENOMEM Insufficient memory to complete the operation.

       ENOTDIR
              The path in dirp is not a directory.

VERSIONS top

       versionsort() was added to glibc in version 2.1.

CONFORMING TO top

       alphasort() and scandir() are specified in POSIX.1-2008, and are widely
       available.  versionsort() is a GNU extension.

       The functions scandir() and alphasort() are from 4.3BSD, and have been
       available under Linux since libc4.  Libc4 and libc5 use the more precise
       prototype

           int alphasort(const struct dirent ** a,
                         const struct dirent **b);

       but glibc 2.0 returns to the imprecise BSD prototype.

       The function versionsort() is a GNU extension, available since glibc 2.1.

       Since glibc 2.1, alphasort() calls strcoll(3); earlier it used strcmp(3).

EXAMPLE top

       #define _SVID_SOURCE
       /* print files in current directory in reverse order */
       #include <dirent.h>

       int
       main(void)
       {
           struct dirent **namelist;
           int n;

           n = scandir(".", &namelist, NULL, alphasort);
           if (n < 0)
               perror("scandir");
           else {
               while (n--) {
                   printf("%s\n", namelist[n]->d_name);
                   free(namelist[n]);
               }
               free(namelist);
           }
       }

SEE ALSO top

       closedir(3), fnmatch(3), opendir(3), readdir(3), rewinddir(3),
       scandirat(3), seekdir(3), strcmp(3), strcoll(3), strverscmp(3), telldir(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-26                          SCANDIR(3)


arch_prctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ARCH_PRCTL(2)                Linux Programmer's Manual               ARCH_PRCTL(2)

NAME top

       arch_prctl - set architecture-specific thread state

SYNOPSIS top

       #include <asm/prctl.h>
       #include <sys/prctl.h>

       int arch_prctl(int code, unsigned long addr);
       int arch_prctl(int code, unsigned long *addr);

DESCRIPTION top

       The arch_prctl() function sets architecture-specific process or thread
       state.  code selects a subfunction and passes argument addr to it; addr is
       interpreted as either an unsigned long for the "set" operations, or as an
       unsigned long *, for the "get" operations.

       Sub functions for x86-64 are:

       ARCH_SET_FS
              Set the 64-bit base for the FS register to addr.

       ARCH_GET_FS
              Return the 64-bit base value for the FS register of the current
              thread in the unsigned long pointed to by addr.

       ARCH_SET_GS
              Set the 64-bit base for the GS register to addr.

       ARCH_GET_GS
              Return the 64-bit base value for the GS register of the current
              thread in the unsigned long pointed to by addr.

RETURN VALUE top

       On success, arch_prctl() returns 0; on error, -1 is returned, and errno is
       set to indicate the error.

ERRORS top

       EFAULT addr points to an unmapped address or is outside the process address
              space.

       EINVAL code is not a valid subcommand.

       EPERM  addr is outside the process address space.

CONFORMING TO top

       arch_prctl() is a Linux/x86-64 extension and should not be used in programs
       intended to be portable.

NOTES top

       arch_prctl() is only supported on Linux/x86-64 for 64-bit programs
       currently.

       The 64-bit base changes when a new 32-bit segment selector is loaded.

       ARCH_SET_GS is disabled in some kernels.

       Context switches for 64-bit segment bases are rather expensive.  It may be
       a faster alternative to set a 32-bit base using a segment selector by
       setting up an LDT with modify_ldt(2) or using the set_thread_area(2) system
       call in kernel 2.5 or later.  arch_prctl() is only needed when you want to
       set bases that are larger than 4GB.  Memory in the first 2GB of address
       space can be allocated by using mmap(2) with the MAP_32BIT flag.

       As of version 2.7, glibc provides no prototype for arch_prctl().  You have
       to declare it yourself for now.  This may be fixed in future glibc
       versions.

       FS may be already used by the threading library.

SEE ALSO top

       mmap(2), modify_ldt(2), prctl(2), set_thread_area(2)

       AMD X86-64 Programmer's manual

COLOPHON top

       This page is part of release 3.45 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-12-26                       ARCH_PRCTL(2)


argz_add(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ARGZ_ADD(3)                  Linux Programmer's Manual                 ARGZ_ADD(3)

NAME top

       argz_add,  argz_add_sep,  argz_append,  argz_count,  argz_create, argz_cre-
       ate_sep, argz_delete, argz_extract, argz_insert,  argz_next,  argz_replace,
       argz_stringify - functions to handle an argz list

SYNOPSIS top

       #include <argz.h>

       error_t argz_add(char **argz, size_t *argz_len, const char *str);

       error_t argz_add_sep(char **argz, size_t *argz_len,
                    const char *str, int delim);

       error_t argz_append(char **argz, size_t *argz_len,
                    const char *buf, size_t buf_len);

       size_t argz_count(const char *argz, size_t argz_len);

       error_t argz_create(char * const argv[], char **argz,
                    size_t *argz_len);

       error_t argz_create_sep(const char *str, int sep, char **argz,
                    size_t *argz_len);

       error_t argz_delete(char **argz, size_t *argz_len, char *entry);

       void argz_extract(char *argz, size_t argz_len, char  **argv);

       error_t argz_insert(char **argz, size_t *argz_len, char *before,
                    const char *entry);

       char *argz_next(char *argz, size_t argz_len, const char *entry);

       error_t argz_replace(char **argz, size_t *argz_len, const char *str,
                    const char *with, unsigned int *replace_count);

       void argz_stringify(char *argz, size_t len, int sep);

DESCRIPTION top

       These functions are glibc-specific.

       An argz vector is a pointer to a character buffer together with a length.
       The intended interpretation of the character buffer is an array of strings,
       where the strings are separated by null bytes ('\0').  If the length is
       nonzero, the last byte of the buffer must be a null byte.

       These functions are for handling argz vectors.  The pair (NULL,0) is an
       argz vector, and, conversely, argz vectors of length 0 must have NULL
       pointer.  Allocation of nonempty argz vectors is done using malloc(3), so
       that free(3) can be used to dispose of them again.

       argz_add() adds the string str at the end of the array *argz, and updates
       *argz and *argz_len.

       argz_add_sep() is similar, but splits the string str into substrings
       separated by the delimiter delim.  For example, one might use this on a
       UNIX search path with delimiter ':'.

       argz_append() appends the argz vector (buf, buf_len) after
       (*argz, *argz_len) and updates *argz and *argz_len.  (Thus, *argz_len will
       be increased by buf_len.)

       argz_count() counts the number of strings, that is, the number of null
       bytes ('\0'), in (argz, argz_len).

       argz_create() converts a UNIX-style argument vector argv, terminated by
       (char *) 0, into an argz vector (*argz, *argz_len).

       argz_create_sep() converts the null-terminated string str into an argz
       vector (*argz, *argz_len) by breaking it up at every occurrence of the
       separator sep.

       argz_delete() removes the substring pointed to by entry from the argz
       vector (*argz, *argz_len) and updates *argz and *argz_len.

       argz_extract() is the opposite of argz_create().  It takes the argz vector
       (argz, argz_len) and fills the array starting at argv with pointers to the
       substrings, and a final NULL, making a UNIX-style argv vector.  The array
       argv must have room for argz_count(argz,argz_len) + 1 pointers.

       argz_insert() is the opposite of argz_delete().  It inserts the argument
       entry at position before into the argz vector (*argz, *argz_len) and
       updates *argz and *argz_len.  If before is NULL, then entry will inserted
       at the end.

       argz_next() is a function to step trough the argz vector.  If entry is
       NULL, the first entry is returned.  Otherwise, the entry following is
       returned.  It returns NULL if there is no following entry.

       argz_replace() replaces each occurrence of str with with, reallocating argz
       as necessary.  If replace_count is non-NULL, *replace_count will be
       incremented by the number of replacements.

       argz_stringify() is the opposite of argz_create_sep().  It transforms the
       argz vector into a normal string by replacing all null bytes ('\0') except
       the last by sep.

RETURN VALUE top

       All argz functions that do memory allocation have a return type of error_t,
       and return 0 for success, and ENOMEM if an allocation error occurs.

CONFORMING TO top

       These functions are a GNU extension.  Handle with care.

BUGS top

       Argz vectors without a terminating null byte may lead to Segmentation
       Faults.

SEE ALSO top

       envz_add(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-05-18                         ARGZ_ADD(3)


armscii-8(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ARMSCII-8(7)                 Linux Programmer's Manual                ARMSCII-8(7)

NAME top

       armscii-8   -  Armenian  character  set  encoded  in  octal,  decimal,  and
       hexadecimal

DESCRIPTION top

       The Armenian Standard Code for Information Interchange, 8-bit coded
       character set.

ArmSCII-8 Characters

       The following table displays the characters in ArmSCII-8, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ArmSCII-8.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       242   162   A2     /c     ARMENIAN SMALL LIGATURE ECH YIWN
       243   163   A3     -L     ARMENIAN FULL STOP
       244   164   A4     )     RIGHT PARENTHESIS
       245   165   A5     (     LEFT PARENTHESIS
       246   166   A6     |     RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       247   167   A7     S     LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       250   168   A8     "     EM DASH
       251   169   A9     .     FULL STOP
       252   170   AA     _a     ARMENIAN COMMA
       253   171   AB     ,     COMMA
       254   172   AC     -     HYPHEN-MINUS
       255   173   AD           ARMENIAN HYPHEN
       256   174   AE    (R_)    HORIZONTAL ELLIPSIS
       257   175   AF           ARMENIAN EXCLAMATION MARK
       260   176   B0     o     ARMENIAN EMPHASIS MARK
       261   177   B1     +-    ARMENIAN QUESTION MARK
       262   178   B2     2     ARMENIAN CAPITAL LETTER AYB
       263   179   B3     3     ARMENIAN SMALL LETTER AYB
       264   180   B4     '     ARMENIAN CAPITAL LETTER BEN
       265   181   B5     ,u     ARMENIAN SMALL LETTER BEN
       266   182   B6     9|    ARMENIAN CAPITAL LETTER GIM
       267   183   B7     .     ARMENIAN SMALL LETTER GIM
       270   184   B8     ,     ARMENIAN CAPITAL LETTER DA
       271   185   B9     1     ARMENIAN SMALL LETTER DA
       272   186   BA     _o     ARMENIAN CAPITAL LETTER ECH
       273   187   BB     >>    ARMENIAN SMALL LETTER ECH
       274   188   BC    1/4    ARMENIAN CAPITAL LETTER ZA
       275   189   BD    1/2    ARMENIAN SMALL LETTER ZA
       276   190   BE    3/4    ARMENIAN CAPITAL LETTER EH
       277   191   BF     'c     ARMENIAN SMALL LETTER EH
       300   192   C0     `A     ARMENIAN CAPITAL LETTER ET
       301   193   C1     'A     ARMENIAN SMALL LETTER ET
       302   194   C2     ^A     ARMENIAN CAPITAL LETTER TO
       303   195   C3     ~A     ARMENIAN SMALL LETTER TO
       304   196   C4     "A     ARMENIAN CAPITAL LETTER ZHE
       305   197   C5     oA     ARMENIAN SMALL LETTER ZHE
       306   198   C6     AE    ARMENIAN CAPITAL LETTER INI
       307   199   C7     ,C     ARMENIAN SMALL LETTER INI
       310   200   C8     `E     ARMENIAN CAPITAL LETTER LIWN
       311   201   C9     'E     ARMENIAN SMALL LETTER LIWN
       312   202   CA     ^E     ARMENIAN CAPITAL LETTER XEH
       313   203   CB     "E     ARMENIAN SMALL LETTER XEH
       314   204   CC     `I     ARMENIAN CAPITAL LETTER CA
       315   205   CD     'I     ARMENIAN SMALL LETTER CA
       316   206   CE     ^I     ARMENIAN CAPITAL LETTER KEN

       317   207   CF     "I     ARMENIAN SMALL LETTER KEN
       320   208   D0     -D     ARMENIAN CAPITAL LETTER HO
       321   209   D1     ~N     ARMENIAN SMALL LETTER HO
       322   210   D2     `O     ARMENIAN CAPITAL LETTER JA
       323   211   D3     'O     ARMENIAN SMALL LETTER JA
       324   212   D4     ^O     ARMENIAN CAPITAL LETTER GHAD
       325   213   D5     ~O     ARMENIAN SMALL LETTER GHAD
       326   214   D6     "O     ARMENIAN CAPITAL LETTER CHEH
       327   215   D7     x     ARMENIAN SMALL LETTER CHEH
       330   216   D8     /O     ARMENIAN CAPITAL LETTER MEN
       331   217   D9     `U     ARMENIAN SMALL LETTER MEN
       332   218   DA     'U     ARMENIAN CAPITAL LETTER YI
       333   219   DB     ^U     ARMENIAN SMALL LETTER YI
       334   220   DC     "U     ARMENIAN CAPITAL LETTER NOW
       335   221   DD     'Y     ARMENIAN SMALL LETTER NOW
       336   222   DE     Ib     ARMENIAN CAPITAL LETTER SHA
       337   223   DF     B     ARMENIAN SMALL LETTER SHA
       340   224   E0     `a     ARMENIAN CAPITAL LETTER VO
       341   225   E1     'a     ARMENIAN SMALL LETTER VO
       342   226   E2     ^a     ARMENIAN CAPITAL LETTER CHA
       343   227   E3     ~a     ARMENIAN SMALL LETTER CHA
       344   228   E4     "a     ARMENIAN CAPITAL LETTER PEH
       345   229   E5     oa     ARMENIAN SMALL LETTER PEH
       346   230   E6     ae    ARMENIAN CAPITAL LETTER JHEH
       347   231   E7     ,c     ARMENIAN SMALL LETTER JHEH
       350   232   E8     `e     ARMENIAN CAPITAL LETTER RA
       351   233   E9     'e     ARMENIAN SMALL LETTER RA
       352   234   EA     ^e     ARMENIAN CAPITAL LETTER SEH
       353   235   EB     "e     ARMENIAN SMALL LETTER SEH
       354   236   EC     `i     ARMENIAN CAPITAL LETTER VEW
       355   237   ED     'i     ARMENIAN SMALL LETTER VEW
       356   238   EE     ^i     ARMENIAN CAPITAL LETTER TIWN
       357   239   EF     "i     ARMENIAN SMALL LETTER TIWN
       360   240   F0     `'o     ARMENIAN CAPITAL LETTER REH
       361   241   F1     ~n     ARMENIAN SMALL LETTER REH
       362   242   F2     `o     ARMENIAN CAPITAL LETTER CO
       363   243   F3     'o     ARMENIAN SMALL LETTER CO
       364   244   F4     ^o     ARMENIAN CAPITAL LETTER YIWN
       365   245   F5     ~o     ARMENIAN SMALL LETTER YIWN
       366   246   F6     "o     ARMENIAN CAPITAL LETTER PIWR
       367   247   F7    -:-    ARMENIAN SMALL LETTER PIWR
       370   248   F8     /o     ARMENIAN CAPITAL LETTER KEH
       371   249   F9     `u     ARMENIAN SMALL LETTER KEH
       372   250   FA     'u     ARMENIAN CAPITAL LETTER OH
       373   251   FB     ^u     ARMENIAN SMALL LETTER OH
       374   252   FC     "u     ARMENIAN CAPITAL LETTER FEH
       375   253   FD     'y     ARMENIAN SMALL LETTER FEH
       376   254   FE     pb     ARMENIAN APOSTROPHE

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                        ARMSCII-8(7)


posix_fadvise(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

POSIX_FADVISE(2)             Linux Programmer's Manual            POSIX_FADVISE(2)

NAME top

       posix_fadvise - predeclare an access pattern for file data

SYNOPSIS top

       #include <fcntl.h>

       int posix_fadvise(int fd, off_t offset, off_t len, int advice);

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

       posix_fadvise():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       Programs can use posix_fadvise() to announce an intention to access file
       data in a specific pattern in the future, thus allowing the kernel to
       perform appropriate optimizations.

       The advice applies to a (not necessarily existent) region starting at
       offset and extending for len bytes (or until the end of the file if len is
       0) within the file referred to by fd.  The advice is not binding; it merely
       constitutes an expectation on behalf of the application.

       Permissible values for advice include:

       POSIX_FADV_NORMAL
              Indicates that the application has no advice to give about its
              access pattern for the specified data.  If no advice is given for an
              open file, this is the default assumption.

       POSIX_FADV_SEQUENTIAL
              The application expects to access the specified data sequentially
              (with lower offsets read before higher ones).

       POSIX_FADV_RANDOM
              The specified data will be accessed in random order.

       POSIX_FADV_NOREUSE
              The specified data will be accessed only once.

       POSIX_FADV_WILLNEED
              The specified data will be accessed in the near future.

       POSIX_FADV_DONTNEED
              The specified data will not be accessed in the near future.

RETURN VALUE top

       On success, zero is returned.  On error, an error number is returned.

ERRORS top

       EBADF  The fd argument was not a valid file descriptor.

       EINVAL An invalid value was specified for advice.

       ESPIPE The specified file descriptor refers to a pipe or FIFO.  (Linux
              actually returns EINVAL in this case.)

VERSIONS top

       Kernel support first appeared in Linux 2.5.60; the underlying system call
       is called fadvise64().  Library support has been provided since glibc
       version 2.2, via the wrapper function posix_fadvise().

CONFORMING TO top

       POSIX.1-2001.  Note that the type of the len argument was changed from
       size_t to off_t in POSIX.1-2003 TC1.

NOTES top

       Under Linux, POSIX_FADV_NORMAL sets the readahead window to the default
       size for the backing device; POSIX_FADV_SEQUENTIAL doubles this size, and
       POSIX_FADV_RANDOM disables file readahead entirely.  These changes affect
       the entire file, not just the specified region (but other open file handles
       to the same file are unaffected).

       POSIX_FADV_WILLNEED initiates a nonblocking read of the specified region
       into the page cache.  The amount of data read may be decreased by the
       kernel depending on virtual memory load.  (A few megabytes will usually be
       fully satisfied, and more is rarely useful.)

       In kernels before 2.6.18, POSIX_FADV_NOREUSE had the same semantics as
       POSIX_FADV_WILLNEED.  This was probably a bug; since kernel 2.6.18, this
       flag is a no-op.

       POSIX_FADV_DONTNEED attempts to free cached pages associated with the
       specified region.  This is useful, for example, while streaming large
       files.  A program may periodically request the kernel to free cached data
       that has already been used, so that more useful cached pages are not
       discarded instead.

       Pages that have not yet been written out will be unaffected, so if the
       application wishes to guarantee that pages will be released, it should call
       fsync(2) or fdatasync(2) first.

arm_fadvise()

       The ARM architecture needs 64-bit arguments to be aligned in a suitable
       pair of registers.  On this architecture, the call signature of
       posix_fadvise() is flawed, since it forces a register to be wasted as
       padding between the fd and len arguments.  Therefore, since Linux 2.6.14,
       ARM defines a different system call that orders the arguments suitably:

           long arm_fadvise64_64(int fd, int advice,
                                 loff_t offset, loff_t len);

       The behavior of this system call is otherwise exactly the same as
       posix_fadvise().  No library support is provided for this system call in
       glibc.

BUGS top

       In kernels before 2.6.6, if len was specified as 0, then this was
       interpreted literally as "zero bytes", rather than as meaning "all bytes
       through to the end of the file".

SEE ALSO top

       readahead(2), sync_file_range(2), posix_fallocate(3), posix_madvise(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-09                    POSIX_FADVISE(2)


sync_file_range(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYNC_FILE_RANGE(2)           Linux Programmer's Manual          SYNC_FILE_RANGE(2)

NAME top

       sync_file_range - sync a file segment with disk

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <fcntl.h>

       int sync_file_range(int fd, off64_t offset, off64_t nbytes,
                           unsigned int flags);

DESCRIPTION top

       sync_file_range() permits fine control when synchronizing the open file
       referred to by the file descriptor fd with disk.

       offset is the starting byte of the file range to be synchronized.  nbytes
       specifies the length of the range to be synchronized, in bytes; if nbytes
       is zero, then all bytes from offset through to the end of file are
       synchronized.  Synchronization is in units of the system page size: offset
       is rounded down to a page boundary; (offset+nbytes-1) is rounded up to a
       page boundary.

       The flags bit-mask argument can include any of the following values:

       SYNC_FILE_RANGE_WAIT_BEFORE
              Wait upon write-out of all pages in the specified range that have
              already been submitted to the device driver for write-out before
              performing any write.

       SYNC_FILE_RANGE_WRITE
              Initiate write-out of all dirty pages in the specified range which
              are not presently submitted write-out.  Note that even this may
              block if you attempt to write more than request queue size.

       SYNC_FILE_RANGE_WAIT_AFTER
              Wait upon write-out of all pages in the range after performing any
              write.

       Specifying flags as 0 is permitted, as a no-op.

Warning

       This system call is extremely dangerous and should not be used in portable
       programs.  None of these operations writes out the file's metadata.
       Therefore, unless the application is strictly performing overwrites of
       already-instantiated disk blocks, there are no guarantees that the data
       will be available after a crash.  There is no user interface to know if a
       write is purely an overwrite.  On file systems using copy-on-write
       semantics (e.g., btrfs) an overwrite of existing allocated blocks is
       impossible.  When writing into preallocated space, many file systems also
       require calls into the block allocator, which this system call does not
       sync out to disk.  This system call does not flush disk write caches and
       thus does not provide any data integrity on systems with volatile disk
       write caches.

Some details

       SYNC_FILE_RANGE_WAIT_BEFORE and SYNC_FILE_RANGE_WAIT_AFTER will detect any
       I/O errors or ENOSPC conditions and will return these to the caller.

       Useful combinations of the flags bits are:

       SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
              Ensures that all pages in the specified range which were dirty when
              sync_file_range() was called are placed under write-out.  This is a
              start-write-for-data-integrity operation.

       SYNC_FILE_RANGE_WRITE
              Start write-out of all dirty pages in the specified range which are
              not presently under write-out.  This is an asynchronous flush-to-
              disk operation.  This is not suitable for data integrity operations.

       SYNC_FILE_RANGE_WAIT_BEFORE (or SYNC_FILE_RANGE_WAIT_AFTER)
              Wait for completion of write-out of all pages in the specified
              range.  This can be used after an earlier
              SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE operation to
              wait for completion of that operation, and obtain its result.

       SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE |
       SYNC_FILE_RANGE_WAIT_AFTER
              This is a write-for-data-integrity operation that will ensure that
              all pages in the specified range which were dirty when
              sync_file_range() was called are committed to disk.

RETURN VALUE top

       On success, sync_file_range() returns 0; on failure -1 is returned and
       errno is set to indicate the error.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       EINVAL flags specifies an invalid bit; or offset or nbytes is invalid.

       EIO    I/O error.

       ENOMEM Out of memory.

       ENOSPC Out of disk space.

       ESPIPE fd refers to something other than a regular file, a block device, a
              directory, or a symbolic link.

VERSIONS top

       sync_file_range() appeared on Linux in kernel 2.6.17.

CONFORMING TO top

       This system call is Linux-specific, and should be avoided in portable
       programs.

NOTES top

       Some architectures (e.g., PowerPC, ARM) need 64-bit arguments to be aligned
       in a suitable pair of registers.  On such architectures, the call signature
       of sync_file_range() is flawed, since it forces a register to be wasted as
       padding between the fd and offset arguments.  Therefore, these
       architectures define a different system call that orders the arguments
       suitably:

           int sync_file_range2(int fd, unsigned int flags,
                                off64_t offset, off64_t nbytes);

       The behavior of this system call is otherwise exactly the same as
       sync_file_range().

       A system call with this signature first appeared on the ARM architecture in
       Linux 2.6.20, with the name arm_sync_file_range().  It was renamed in Linux
       2.6.22, when the analogous system call was added for PowerPC.  On
       architectures where glibc support is provided, glibc transparently wraps
       sync_file_range2() under the name sync_file_range().

SEE ALSO top

       fdatasync(2), fsync(2), msync(2), sync(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-09                  SYNC_FILE_RANGE(2)


arp(7) - Linux manual page

NAME | DESCRIPTION | VERSIONS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ARP(7)                       Linux Programmer's Manual                      ARP(7)

NAME top

       arp - Linux ARP kernel module.

DESCRIPTION top

       This kernel protocol module implements the Address Resolution Protocol
       defined in RFC 826.  It is used to convert between Layer2 hardware
       addresses and IPv4 protocol addresses on directly connected networks.  The
       user normally doesn't interact directly with this module except to
       configure it; instead it provides a service for other protocols in the
       kernel.

       A user process can receive ARP packets by using packet(7) sockets.  There
       is also a mechanism for managing the ARP cache in user-space by using
       netlink(7) sockets.  The ARP table can also be controlled via ioctl(2) on
       any AF_INET socket.

       The ARP module maintains a cache of mappings between hardware addresses and
       protocol addresses.  The cache has a limited size so old and less
       frequently used entries are garbage-collected.  Entries which are marked as
       permanent are never deleted by the garbage-collector.  The cache can be
       directly manipulated by the use of ioctls and its behavior can be tuned by
       the /proc interfaces described below.

       When there is no positive feedback for an existing mapping after some time
       (see the /proc interfaces below), a neighbor cache entry is considered
       stale.  Positive feedback can be gotten from a higher layer; for example
       from a successful TCP ACK.  Other protocols can signal forward progress
       using the MSG_CONFIRM flag to sendmsg(2).  When there is no forward
       progress, ARP tries to reprobe.  It first tries to ask a local arp daemon
       app_solicit times for an updated MAC address.  If that fails and an old MAC
       address is known, a unicast probe is sent ucast_solicit times.  If that
       fails too, it will broadcast a new ARP request to the network.  Requests
       are only sent when there is data queued for sending.

       Linux will automatically add a nonpermanent proxy arp entry when it
       receives a request for an address it forwards to and proxy arp is enabled
       on the receiving interface.  When there is a reject route for the target,
       no proxy arp entry is added.

Ioctls

       Three ioctls are available on all AF_INET sockets.  They take a pointer to
       a struct arpreq as their argument.

           struct arpreq {
               struct sockaddr arp_pa;      /* protocol address */
               struct sockaddr arp_ha;      /* hardware address */
               int             arp_flags;   /* flags */
               struct sockaddr arp_netmask; /* netmask of protocol address */
               char            arp_dev[16];
           };

       SIOCSARP, SIOCDARP and SIOCGARP respectively set, delete and get an ARP
       mapping.  Setting and deleting ARP maps are privileged operations and may
       only be performed by a process with the CAP_NET_ADMIN capability or an
       effective UID of 0.

       arp_pa must be an AF_INET address and arp_ha must have the same type as the
       device which is specified in arp_dev.  arp_dev is a zero-terminated string
       which names a device.

              +-------------------------------------+
              |             arp_flags               |
              +----------------+--------------------+
              |flag            | meaning            |
              +----------------+--------------------+
              |ATF_COM         | Lookup complete    |
              +----------------+--------------------+
              |ATF_PERM        | Permanent entry    |
              +----------------+--------------------+
              |ATF_PUBL        | Publish entry      |
              +----------------+--------------------+
              |ATF_USETRAILERS | Trailers requested |
              +----------------+--------------------+
              |ATF_NETMASK     | Use a netmask      |
              +----------------+--------------------+
              |ATF_DONTPUB     | Don't answer       |
              +----------------+--------------------+

       If the ATF_NETMASK flag is set, then arp_netmask should be valid.  Linux
       2.2 does not support proxy network ARP entries, so this should be set to
       0xffffffff, or 0 to remove an existing proxy arp entry.  ATF_USETRAILERS is
       obsolete and should not be used.

/proc interfaces

       ARP supports a range of /proc interfaces to configure parameters on a
       global or per-interface basis.  The interfaces can be accessed by reading
       or writing the /proc/sys/net/ipv4/neigh/*/* files.  Each interface in the
       system has its own directory in /proc/sys/net/ipv4/neigh/.  The setting in
       the "default" directory is used for all newly created devices.  Unless
       otherwise specified, time-related interfaces are specified in seconds.

       anycast_delay (since Linux 2.2)
              The maximum number of jiffies to delay before replying to a IPv6
              neighbor solicitation message.  Anycast support is not yet
              implemented.  Defaults to 1 second.

       app_solicit (since Linux 2.2)
              The maximum number of probes to send to the user space ARP daemon
              via netlink before dropping back to multicast probes (see
              mcast_solicit).  Defaults to 0.

       base_reachable_time (since Linux 2.2)
              Once a neighbor has been found, the entry is considered to be valid
              for at least a random value between base_reachable_time/2 and
              3*base_reachable_time/2.  An entry's validity will be extended if it
              receives positive feedback from higher level protocols.  Defaults to
              30 seconds.  This file is now obsolete in favor of
              base_reachable_time_ms.

       base_reachable_time_ms (since Linux 2.6.12)
              As for base_reachable_time, but measures time in milliseconds.
              Defaults to 30000 milliseconds.

       delay_first_probe_time (since Linux 2.2)
              Delay before first probe after it has been decided that a neighbor
              is stale.  Defaults to 5 seconds.

       gc_interval (since Linux 2.2)
              How frequently the garbage collector for neighbor entries should
              attempt to run.  Defaults to 30 seconds.

       gc_stale_time (since Linux 2.2)
              Determines how often to check for stale neighbor entries.  When a
              neighbor entry is considered stale, it is resolved again before
              sending data to it.  Defaults to 60 seconds.

       gc_thresh1 (since Linux 2.2)
              The minimum number of entries to keep in the ARP cache.  The garbage
              collector will not run if there are fewer than this number of
              entries in the cache.  Defaults to 128.

       gc_thresh2 (since Linux 2.2)
              The soft maximum number of entries to keep in the ARP cache.  The
              garbage collector will allow the number of entries to exceed this
              for 5 seconds before collection will be performed.  Defaults to 512.

       gc_thresh3 (since Linux 2.2)
              The hard maximum number of entries to keep in the ARP cache.  The
              garbage collector will always run if there are more than this number
              of entries in the cache.  Defaults to 1024.

       locktime (since Linux 2.2)
              The minimum number of jiffies to keep an ARP entry in the cache.
              This prevents ARP cache thrashing if there is more than one
              potential mapping (generally due to network misconfiguration).
              Defaults to 1 second.

       mcast_solicit (since Linux 2.2)
              The maximum number of attempts to resolve an address by
              multicast/broadcast before marking the entry as unreachable.
              Defaults to 3.

       proxy_delay (since Linux 2.2)
              When an ARP request for a known proxy-ARP address is received, delay
              up to proxy_delay jiffies before replying.  This is used to prevent
              network flooding in some cases.  Defaults to 0.8 seconds.

       proxy_qlen (since Linux 2.2)
              The maximum number of packets which may be queued to proxy-ARP
              addresses.  Defaults to 64.

       retrans_time (since Linux 2.2)
              The number of jiffies to delay before retransmitting a request.
              Defaults to 1 second.  This file is now obsolete in favor of
              retrans_time_ms.

       retrans_time_ms (since Linux 2.6.12)
              The number of milliseconds to delay before retransmitting a request.
              Defaults to 1000 milliseconds.

       ucast_solicit (since Linux 2.2)
              The maximum number of attempts to send unicast probes before asking
              the ARP daemon (see app_solicit).  Defaults to 3.

       unres_qlen (since Linux 2.2)
              The maximum number of packets which may be queued for each
              unresolved address by other network layers.  Defaults to 3.

VERSIONS top

       The struct arpreq changed in Linux 2.0 to include the arp_dev member and
       the ioctl numbers changed at the same time.  Support for the old ioctls was
       dropped in Linux 2.2.

       Support for proxy arp entries for networks (netmask not equal 0xffffffff)
       was dropped in Linux 2.2.  It is replaced by automatic proxy arp setup by
       the kernel for all reachable hosts on other interfaces (when forwarding and
       proxy arp is enabled for the interface).

       The neigh/* interfaces did not exist before Linux 2.2.

BUGS top

       Some timer settings are specified in jiffies, which is architecture- and
       kernel version-dependent; see time(7).

       There is no way to signal positive feedback from user space.  This means
       connection-oriented protocols implemented in user space will generate
       excessive ARP traffic, because ndisc will regularly reprobe the MAC
       address.  The same problem applies for some kernel protocols (e.g., NFS
       over UDP).

       This man page mashes IPv4 specific and shared between IPv4 and IPv6
       functionality together.

SEE ALSO top

       capabilities(7), ip(7)

       RFC 826 for a description of ARP.  RFC 2461 for a description of IPv6
       neighbor discovery and the base algorithms used.  Linux 2.2+ IPv4 ARP uses
       the IPv6 algorithms when applicable.

COLOPHON top

       This page is part of release 3.45 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-25                              ARP(7)


ascii(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ASCII(7)                     Linux Programmer's Manual                    ASCII(7)

NAME top

       ascii - ASCII character set encoded in octal, decimal, and hexadecimal

DESCRIPTION top

       ASCII is the American Standard Code for Information Interchange.  It is a
       7-bit code.  Many 8-bit codes (such as ISO 8859-1, the Linux default
       character set) contain ASCII as their lower half.  The international
       counterpart of ASCII is known as ISO 646.

       The following table contains the 128 ASCII characters.

       C program '\X' escapes are noted.

       Oct   Dec   Hex   Char                        Oct   Dec   Hex   Char
       ------------------------------------------------------------------------
       000   0     00    NUL '\0'                    100   64    40    @
       001   1     01    SOH (start of heading)      101   65    41    A
       002   2     02    STX (start of text)         102   66    42    B
       003   3     03    ETX (end of text)           103   67    43    C
       004   4     04    EOT (end of transmission)   104   68    44    D
       005   5     05    ENQ (enquiry)               105   69    45    E
       006   6     06    ACK (acknowledge)           106   70    46    F
       007   7     07    BEL '\a' (bell)             107   71    47    G
       010   8     08    BS  '\b' (backspace)        110   72    48    H
       011   9     09    HT  '\t' (horizontal tab)   111   73    49    I
       012   10    0A    LF  '\n' (new line)         112   74    4A    J
       013   11    0B    VT  '\v' (vertical tab)     113   75    4B    K
       014   12    0C    FF  '\f' (form feed)        114   76    4C    L
       015   13    0D    CR  '\r' (carriage ret)     115   77    4D    M
       016   14    0E    SO  (shift out)             116   78    4E    N
       017   15    0F    SI  (shift in)              117   79    4F    O
       020   16    10    DLE (data link escape)      120   80    50    P
       021   17    11    DC1 (device control 1)      121   81    51    Q
       022   18    12    DC2 (device control 2)      122   82    52    R
       023   19    13    DC3 (device control 3)      123   83    53    S
       024   20    14    DC4 (device control 4)      124   84    54    T
       025   21    15    NAK (negative ack.)         125   85    55    U
       026   22    16    SYN (synchronous idle)      126   86    56    V
       027   23    17    ETB (end of trans. blk)     127   87    57    W
       030   24    18    CAN (cancel)                130   88    58    X
       031   25    19    EM  (end of medium)         131   89    59    Y
       032   26    1A    SUB (substitute)            132   90    5A    Z
       033   27    1B    ESC (escape)                133   91    5B    [
       034   28    1C    FS  (file separator)        134   92    5C    \  '\\'
       035   29    1D    GS  (group separator)       135   93    5D    ]
       036   30    1E    RS  (record separator)      136   94    5E    ^
       037   31    1F    US  (unit separator)        137   95    5F    _
       040   32    20    SPACE                       140   96    60    `
       041   33    21    !                           141   97    61    a
       042   34    22    "                           142   98    62    b
       043   35    23    #                           143   99    63    c
       044   36    24    $                           144   100   64    d
       045   37    25    %                           145   101   65    e
       046   38    26    &                           146   102   66    f
       047   39    27    '                           147   103   67    g
       050   40    28    (                           150   104   68    h
       051   41    29    )                           151   105   69    i
       052   42    2A    *                           152   106   6A    j
       053   43    2B    +                           153   107   6B    k
       054   44    2C    ,                           154   108   6C    l
       055   45    2D    -                           155   109   6D    m

       056   46    2E    .                           156   110   6E    n
       057   47    2F    /                           157   111   6F    o
       060   48    30    0                           160   112   70    p
       061   49    31    1                           161   113   71    q
       062   50    32    2                           162   114   72    r
       063   51    33    3                           163   115   73    s
       064   52    34    4                           164   116   74    t
       065   53    35    5                           165   117   75    u
       066   54    36    6                           166   118   76    v
       067   55    37    7                           167   119   77    w
       070   56    38    8                           170   120   78    x
       071   57    39    9                           171   121   79    y
       072   58    3A    :                           172   122   7A    z
       073   59    3B    ;                           173   123   7B    {
       074   60    3C    <                           174   124   7C    |
       075   61    3D    =                           175   125   7D    }
       076   62    3E    >                           176   126   7E    ~
       077   63    3F    ?                           177   127   7F    DEL

Tables

       For convenience, let us give more compact tables in hex and decimal.

          2 3 4 5 6 7       30 40 50 60 70 80 90 100 110 120
        -------------      ---------------------------------
       0:   0 @ P ` p     0:    (  2  <  F  P  Z  d   n   x
       1: ! 1 A Q a q     1:    )  3  =  G  Q  [  e   o   y
       2: " 2 B R b r     2:    *  4  >  H  R  \  f   p   z
       3: # 3 C S c s     3: !  +  5  ?  I  S  ]  g   q   {
       4: $ 4 D T d t     4: "  ,  6  @  J  T  ^  h   r   |
       5: % 5 E U e u     5: #  -  7  A  K  U  _  i   s   }
       6: & 6 F V f v     6: $  .  8  B  L  V  `  j   t   ~
       7: ' 7 G W g w     7: %  /  9  C  M  W  a  k   u  DEL
       8: ( 8 H X h x     8: &  0  :  D  N  X  b  l   v
       9: ) 9 I Y i y     9: '  1  ;  E  O  Y  c  m   w
       A: * : J Z j z
       B: + ; K [ k {
       C: , < L \ l |
       D: - = M ] m }
       E: . > N ^ n ~
       F: / ? O _ o DEL

NOTES top

History

       An ascii manual page appeared in Version 7 of AT&T UNIX.

       On older terminals, the underscore code is displayed as a left arrow,
       called backarrow, the caret is displayed as an up-arrow and the vertical
       bar has a hole in the middle.

       Uppercase and lowercase characters differ by just one bit and the ASCII
       character 2 differs from the double quote by just one bit, too.  That made
       it much easier to encode characters mechanically or with a non-
       microcontroller-based electronic keyboard and that pairing was found on old
       teletypes.

       The ASCII standard was published by the United States of America Standards
       Institute (USASI) in 1968.

SEE ALSO          top
       iso_8859-1(7), iso_8859-10(7), iso_8859-13(7), iso_8859-14(7),
       iso_8859-15(7), iso_8859-16(7), iso_8859-2(7), iso_8859-3(7),
       iso_8859-4(7), iso_8859-5(7), iso_8859-6(7), iso_8859-7(7), iso_8859-8(7),
       iso_8859-9(7)

COLOPHON          top
       This page is part of release 3.45 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                               2009-02-12                            ASCII(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


ctime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CTIME(3)                     Linux Programmer's Manual                    CTIME(3)

NAME top

       asctime,  ctime,  gmtime,  localtime, mktime, asctime_r, ctime_r, gmtime_r,
       localtime_r - transform date and time to broken-down time or ASCII

SYNOPSIS top

       #include <time.h>

       char *asctime(const struct tm *tm);
       char *asctime_r(const struct tm *tm, char *buf);

       char *ctime(const time_t *timep);
       char *ctime_r(const time_t *timep, char *buf);

       struct tm *gmtime(const time_t *timep);
       struct tm *gmtime_r(const time_t *timep, struct tm *result);

       struct tm *localtime(const time_t *timep);
       struct tm *localtime_r(const time_t *timep, struct tm *result);

       time_t mktime(struct tm *tm);

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

       asctime_r(), ctime_r(), gmtime_r(), localtime_r():
              _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
              || _POSIX_SOURCE

DESCRIPTION top

       The ctime(), gmtime() and localtime() functions all take an argument of
       data type time_t which represents calendar time.  When interpreted as an
       absolute time value, it represents the number of seconds elapsed since the
       Epoch, 1970-01-01 00:00:00 +0000 (UTC).

       The asctime() and mktime() functions both take an argument representing
       broken-down time which is a representation separated into year, month, day,
       and so on.

       Broken-down time is stored in the structure tm which is defined in <time.h>
       as follows:

           struct tm {
               int tm_sec;         /* seconds */
               int tm_min;         /* minutes */
               int tm_hour;        /* hours */
               int tm_mday;        /* day of the month */
               int tm_mon;         /* month */
               int tm_year;        /* year */
               int tm_wday;        /* day of the week */
               int tm_yday;        /* day in the year */
               int tm_isdst;       /* daylight saving time */
           };

       The members of the tm structure are:

       tm_sec    The number of seconds after the minute, normally in the range 0
                 to 59, but can be up to 60 to allow for leap seconds.

       tm_min    The number of minutes after the hour, in the range 0 to 59.

       tm_hour   The number of hours past midnight, in the range 0 to 23.

       tm_mday   The day of the month, in the range 1 to 31.

       tm_mon    The number of months since January, in the range 0 to 11.

       tm_year   The number of years since 1900.

       tm_wday   The number of days since Sunday, in the range 0 to 6.

       tm_yday   The number of days since January 1, in the range 0 to 365.

       tm_isdst  A flag that indicates whether daylight saving time is in effect
                 at the time described.  The value is positive if daylight saving
                 time is in effect, zero if it is not, and negative if the
                 information is not available.

       The call ctime(t) is equivalent to asctime(localtime(t)).  It converts the
       calendar time t into a null-terminated string of the form

              "Wed Jun 30 21:49:08 1993\n"

       The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
       "Thu", "Fri", and "Sat".  The abbreviations for the months are "Jan",
       "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
       "Dec".  The return value points to a statically allocated string which
       might be overwritten by subsequent calls to any of the date and time
       functions.  The function also sets the external variables tzname, timezone,
       and daylight (see tzset(3)) with information about the current timezone.
       The reentrant version ctime_r() does the same, but stores the string in a
       user-supplied buffer which should have room for at least 26 bytes.  It need
       not set tzname, timezone, and daylight.

       The gmtime() function converts the calendar time timep to broken-down time
       representation, expressed in Coordinated Universal Time (UTC).  It may
       return NULL when the year does not fit into an integer.  The return value
       points to a statically allocated struct which might be overwritten by
       subsequent calls to any of the date and time functions.  The gmtime_r()
       function does the same, but stores the data in a user-supplied struct.

       The localtime() function converts the calendar time timep to broken-down
       time representation, expressed relative to the user's specified timezone.
       The function acts as if it called tzset(3) and sets the external variables
       tzname with information about the current timezone, timezone with the
       difference between Coordinated Universal Time (UTC) and local standard time
       in seconds, and daylight to a nonzero value if daylight savings time rules
       apply during some part of the year.  The return value points to a
       statically allocated struct which might be overwritten by subsequent calls
       to any of the date and time functions.  The localtime_r() function does the
       same, but stores the data in a user-supplied struct.  It need not set
       tzname, timezone, and daylight.

       The asctime() function converts the broken-down time value tm into a null-
       terminated string with the same format as ctime().  The return value points
       to a statically allocated string which might be overwritten by subsequent
       calls to any of the date and time functions.  The asctime_r() function does
       the same, but stores the string in a user-supplied buffer which should have
       room for at least 26 bytes.

       The mktime() function converts a broken-down time structure, expressed as
       local time, to calendar time representation.  The function ignores the
       values supplied by the caller in the tm_wday and tm_yday fields.  The value
       specified in the tm_isdst field informs mktime() whether or not daylight
       saving time (DST) is in effect for the time supplied in the tm structure: a
       positive value means DST is in effect; zero means that DST is not in
       effect; and a negative value means that mktime() should (use timezone
       information and system databases to) attempt to determine whether DST is in
       effect at the specified time.

       The mktime() function modifies the fields of the tm structure as follows:
       tm_wday and tm_yday are set to values determined from the contents of the
       other fields; if structure members are outside their valid interval, they
       will be normalized (so that, for example, 40 October is changed into 9
       November); tm_isdst is set (regardless of its initial value) to a positive
       value or to 0, respectively, to indicate whether DST is or is not in effect
       at the specified time.  Calling mktime() also sets the external variable
       tzname with information about the current timezone.

       If the specified broken-down time cannot be represented as calendar time
       (seconds since the Epoch), mktime() returns (time_t) -1 and does not alter
       the members of the broken-down time structure.

RETURN VALUE top

       Each of these functions returns the value described, or NULL (-1 in case of
       mktime()) in case an error was detected.

CONFORMING TO top

       POSIX.1-2001.  C89 and C99 specify asctime(), ctime(), gmtime(),
       localtime(), and mktime().  POSIX.1-2008 marks asctime(), asctime_r(),
       ctime(), and ctime_r() as obsolete, recommending the use of strftime(3)
       instead.

NOTES top

       The four functions asctime(), ctime(), gmtime() and localtime() return a
       pointer to static data and hence are not thread-safe.  Thread-safe versions
       asctime_r(), ctime_r(), gmtime_r() and localtime_r() are specified by
       SUSv2, and available since libc 5.2.5.

       POSIX.1-2001 says: "The asctime(), ctime(), gmtime(), and localtime()
       functions shall return values in one of two static objects: a broken-down
       time structure and an array of type char.  Execution of any of the
       functions may overwrite the information returned in either of these objects
       by any of the other functions."  This can occur in the glibc
       implementation.

       In many implementations, including glibc, a 0 in tm_mday is interpreted as
       meaning the last day of the preceding month.

       The glibc version of struct tm has additional fields

              long tm_gmtoff;           /* Seconds east of UTC */
              const char *tm_zone;      /* Timezone abbreviation */

       defined when _BSD_SOURCE was set before including <time.h>.  This is a BSD
       extension, present in 4.3BSD-Reno.

       According to POSIX.1-2004, localtime() is required to behave as though
       tzset(3) was called, while localtime_r() does not have this requirement.
       For portable code tzset(3) should be called before localtime_r().

SEE ALSO top

       date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3),
       strftime(3), strptime(3), timegm(3), tzset(3), time(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-02-25                            CTIME(3)


asin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ASIN(3)                      Linux Programmer's Manual                     ASIN(3)

NAME top

       asin, asinf, asinl - arc sine function

SYNOPSIS top

       #include <math.h>

       double asin(double x);
       float asinf(float x);
       long double asinl(long double x);

       Link with -lm.

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

       asinf(), asinl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The asin() function calculates the principal value of the arc sine of x;
       that is the value whose sine is x.

RETURN VALUE top

       On success, these functions return the principal value of the arc sine of x
       in radians; the return value is in the range [-pi/2, pi/2].

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is outside the range [-1, 1], a domain error occurs, and a NaN is
       returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is outside the range [-1, 1]
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       acos(3), atan(3), atan2(3), casin(3), cos(3), sin(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             ASIN(3)


asinh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ASINH(3)                     Linux Programmer's Manual                    ASINH(3)

NAME top

       asinh, asinhf, asinhl - inverse hyperbolic sine function

SYNOPSIS top

       #include <math.h>

       double asinh(double x);
       float asinhf(float x);
       long double asinhl(long double x);

       Link with -lm.

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

       asinh():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       asinhf(), asinhl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The asinh() function calculates the inverse hyperbolic sine of x; that is
       the value whose hyperbolic sine is x.

RETURN VALUE top

       On success, these functions return the inverse hyperbolic sine of x.

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity (negative infinity), positive infinity (negative
       infinity) is returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       acosh(3), atanh(3), casinh(3), cosh(3), sinh(3), tanh(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                            ASINH(3)


asprintf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ASPRINTF(3)                  Linux Programmer's Manual                 ASPRINTF(3)

NAME top

       asprintf, vasprintf - print to allocated string

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <stdio.h>

       int asprintf(char **strp, const char *fmt, ...);

       int vasprintf(char **strp, const char *fmt, va_list ap);

DESCRIPTION top

       The functions asprintf() and vasprintf() are analogs of sprintf(3) and
       vsprintf(3), except that they allocate a string large enough to hold the
       output including the terminating null byte, and return a pointer to it via
       the first argument.  This pointer should be passed to free(3) to release
       the allocated storage when it is no longer needed.

RETURN VALUE top

       When successful, these functions return the number of bytes printed, just
       like sprintf(3).  If memory allocation wasn't possible, or some other error
       occurs, these functions will return -1, and the contents of strp is
       undefined.

CONFORMING TO top

       These functions are GNU extensions, not in C or POSIX.  They are also
       available under *BSD.  The FreeBSD implementation sets strp to NULL on
       error.

SEE ALSO top

       free(3), malloc(3), printf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2001-12-18                         ASPRINTF(3)


assert(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ASSERT(3)                    Linux Programmer's Manual                   ASSERT(3)

NAME top

       assert - abort the program if assertion is false

SYNOPSIS top

       #include <assert.h>

       void assert(scalar expression);

DESCRIPTION top

       If the macro NDEBUG was defined at the moment <assert.h> was last included,
       the macro assert() generates no code, and hence does nothing at all.
       Otherwise, the macro assert() prints an error message to standard error and
       terminates the program by calling abort(3) if expression is false (i.e.,
       compares equal to zero).

       The purpose of this macro is to help the programmer find bugs in his
       program.  The message "assertion failed in file foo.c, function do_bar(),
       line 1287" is of no help at all to a user.

RETURN VALUE top

       No value is returned.

CONFORMING TO top

       POSIX.1-2001, C89, C99.  In C89, expression is required to be of type int
       and undefined behavior results if it is not, but in C99 it may have any
       scalar type.

BUGS top

       assert() is implemented as a macro; if the expression tested has side-
       effects, program behavior will be different depending on whether NDEBUG is
       defined.  This may create Heisenbugs which go away when debugging is turned
       on.

SEE ALSO top

       abort(3), assert_perror(3), exit(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2002-08-25                           ASSERT(3)


assert_perror(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ASSERT_PERROR(3)             Linux Programmer's Manual            ASSERT_PERROR(3)

NAME top

       assert_perror - test errnum and abort

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <assert.h>

       void assert_perror(int errnum);

DESCRIPTION top

       If the macro NDEBUG was defined at the moment <assert.h> was last included,
       the macro assert_perror() generates no code, and hence does nothing at all.
       Otherwise, the macro assert_perror() prints an error message to standard
       error and terminates the program by calling abort(3) if errnum is nonzero.
       The message contains the filename, function name and line number of the
       macro call, and the output of strerror(errnum).

RETURN VALUE top

       No value is returned.

CONFORMING TO top

       This is a GNU extension.

BUGS top

       The purpose of the assert macros is to help the programmer find bugs in his
       program, things that cannot happen unless there was a coding mistake.
       However, with system or library calls the situation is rather different,
       and error returns can happen, and will happen, and should be tested for.
       Not by an assert, where the test goes away when NDEBUG is defined, but by
       proper error handling code.  Never use this macro.

SEE ALSO top

       abort(3), assert(3), exit(3), strerror(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2002-08-25                    ASSERT_PERROR(3)


atan(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ATAN(3)                      Linux Programmer's Manual                     ATAN(3)

NAME top

       atan, atanf, atanl - arc tangent function

SYNOPSIS top

       #include <math.h>

       double atan(double x);
       float atanf(float x);
       long double atanl( long double x);

       Link with -lm.

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

       atanf(), atanl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The atan() function calculates the principal value of the arc tangent of x;
       that is the value whose tangent is x.

RETURN VALUE top

       On success, these functions return the principal value of the arc tangent
       of x in radians; the return value is in the range [-pi/2, pi/2].

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity (negative infinity), +pi/2 (-pi/2) is returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       acos(3), asin(3), atan2(3), carg(3), catan(3), cos(3), sin(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             ATAN(3)


atan2(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ATAN2(3)                     Linux Programmer's Manual                    ATAN2(3)

NAME top

       atan2, atan2f, atan2l - arc tangent function of two variables

SYNOPSIS top

       #include <math.h>

       double atan2(double y, double x);
       float atan2f(float y, float x);
       long double atan2l(long double y, long double x);

       Link with -lm.

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

       atan2f(), atan2l():
              _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 ||
              _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
              or cc -std=c99

DESCRIPTION top

       The atan2() function calculates the principal value of the arc tangent of
       y/x, using the signs of the two arguments to determine the quadrant of the
       result.

RETURN VALUE top

       On success, these functions return the principal value of the arc tangent
       of y/x in radians; the return value is in the range [-pi, pi].

       If y is +0 (-0) and x is less than 0, +pi (-pi) is returned.

       If y is +0 (-0) and x is greater than 0, +0 (-0) is returned.

       If y is less than 0 and x is +0 or -0, -pi/2 is returned.

       If y is greater than 0 and x is +0 or -0, pi/2 is returned.

       If either x or y is NaN, a NaN is returned.

       If y is +0 (-0) and x is -0, +pi (-pi) is returned.

       If y is +0 (-0) and x is +0, +0 (-0) is returned.

       If y is a finite value greater (less) than 0, and x is negative infinity,
       +pi (-pi) is returned.

       If y is a finite value greater (less) than 0, and x is positive infinity,
       +0 (-0) is returned.

       If y is positive infinity (negative infinity), and x is finite, pi/2
       (-pi/2) is returned.

       If y is positive infinity (negative infinity) and x is negative infinity,
       +3*pi/4 (-3*pi/4) is returned.

       If y is positive infinity (negative infinity) and x is positive infinity,
       +pi/4 (-pi/4) is returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       acos(3), asin(3), atan(3), carg(3), cos(3), sin(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            ATAN2(3)


atanh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ATANH(3)                     Linux Programmer's Manual                    ATANH(3)

NAME top

       atanh, atanhf, atanhl - inverse hyperbolic tangent function

SYNOPSIS top

       #include <math.h>

       double atanh(double x);
       float atanhf(float x);
       long double atanhl(long double x);

       Link with -lm.

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

       atanh():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       atanhf(), atanhl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The atanh() function calculates the inverse hyperbolic tangent of x; that
       is the value whose hyperbolic tangent is x.

RETURN VALUE top

       On success, these functions return the inverse hyperbolic tangent of x.

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is +1 or -1, a pole error occurs, and the functions return HUGE_VAL,
       HUGE_VALF, or HUGE_VALL, respectively, with the mathematically correct
       sign.

       If the absolute value of x is greater than 1, a domain error occurs, and a
       NaN is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x less than -1 or greater than +1
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

       Pole error: x is +1 or -1
              errno is set to ERANGE (but see BUGS).  A divide-by-zero floating-
              point exception (FE_DIVBYZERO) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

BUGS top

       In glibc 2.9 and earlier, when a pole error occurs, errno as set to EDOM
       instead of the POSIX-mandated ERANGE.  Since version 2.10, glibc does the
       right thing.

SEE ALSO top

       acosh(3), asinh(3), catanh(3), cosh(3), sinh(3), tanh(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-11                            ATANH(3)


atexit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

ATEXIT(3)                    Linux Programmer's Manual                   ATEXIT(3)

NAME top

       atexit - register a function to be called at normal process termination

SYNOPSIS top

       #include <stdlib.h>

       int atexit(void (*function)(void));

DESCRIPTION top

       The atexit() function registers the given function to be called at normal
       process termination, either via exit(3) or via return from the program's
       main().  Functions so registered are called in the reverse order of their
       registration; no arguments are passed.

       The same function may be registered multiple times: it is called once for
       each registration.

       POSIX.1-2001 requires that an implementation allow at least ATEXIT_MAX (32)
       such functions to be registered.  The actual limit supported by an
       implementation can be obtained using sysconf(3).

       When a child process is created via fork(2), it inherits copies of its
       parent's registrations.  Upon a successful call to one of the exec(3)
       functions, all registrations are removed.

RETURN VALUE top

       The atexit() function returns the value 0 if successful; otherwise it
       returns a nonzero value.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

NOTES top

       Functions registered using atexit() (and on_exit(3)) are not called if a
       process terminates abnormally because of the delivery of a signal.

       If one of the functions registered functions calls _exit(2), then any
       remaining functions are not invoked, and the other process termination
       steps performed by exit(3) are not performed.

       POSIX.1-2001 says that the result of calling exit(3) more than once (i.e.,
       calling exit(3) within a function registered using atexit()) is undefined.
       On some systems (but not Linux), this can result in an infinite recursion;
       portable programs should not invoke exit(3) inside a function registered
       using atexit().

       The atexit() and on_exit(3) functions register functions on the same list:
       at normal process termination, the registered functions are invoked in
       reverse order of their registration by these two functions.

       POSIX.1-2001 says that the result is undefined if longjmp(3) is used to
       terminate execution of one of the functions registered atexit().

Linux Notes

       Since glibc 2.2.3, atexit() (and on_exit(3)) can be used within a shared
       library to establish functions that are called when the shared library is
       unloaded.

EXAMPLE top

       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       void
       bye(void)
       {
           printf("That was all, folks\n");
       }

       int
       main(void)
       {
           long a;
           int i;

           a = sysconf(_SC_ATEXIT_MAX);
           printf("ATEXIT_MAX = %ld\n", a);

           i = atexit(bye);
           if (i != 0) {
               fprintf(stderr, "cannot set exit function\n");
               exit(EXIT_FAILURE);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       _exit(2), exit(3), on_exit(3)

COLOPHON top

       This page is part of release 3.45 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-05                           ATEXIT(3)


atof(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ATOF(3)                      Linux Programmer's Manual                     ATOF(3)

NAME top

       atof - convert a string to a double

SYNOPSIS top

       #include <stdlib.h>

       double atof(const char *nptr);

DESCRIPTION top

       The atof() function converts the initial portion of the string pointed to
       by nptr to double.  The behavior is the same as

           strtod(nptr, NULL);

       except that atof() does not detect errors.

RETURN VALUE top

       The converted value.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD, C89, C99.

SEE ALSO top

       atoi(3), atol(3), strtod(3), strtol(3), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-03                             ATOF(3)


atoi(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ATOI(3)                      Linux Programmer's Manual                     ATOI(3)

NAME top

       atoi, atol, atoll, atoq - convert a string to an integer

SYNOPSIS top

       #include <stdlib.h>

       int atoi(const char *nptr);
       long atol(const char *nptr);
       long long atoll(const char *nptr);
       long long atoq(const char *nptr);

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

       atoll():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The atoi() function converts the initial portion of the string pointed to
       by nptr to int.  The behavior is the same as

           strtol(nptr, NULL, 10);

       except that atoi() does not detect errors.

       The atol() and atoll() functions behave the same as atoi(), except that
       they convert the initial portion of the string to their return type of long
       or long long.  atoq() is an obsolete name for atoll().

RETURN VALUE top

       The converted value.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD, C99.  C89 and POSIX.1-1996 include the
       functions atoi() and atol() only.  atoq() is a GNU extension.

NOTES top

       The nonstandard atoq() function is not present in libc 4.6.27 or glibc 2,
       but is present in libc5 and libc 4.7 (though only as an inline function in
       <stdlib.h> until libc 5.4.44).  The atoll() function is present in glibc 2
       since version 2.0.2, but not in libc4 or libc5.

SEE ALSO top

       atof(3), strtod(3), strtol(3), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-03                             ATOI(3)


rpc(3) - Linux manual page

NAME | SYNOPSIS AND DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

RPC(3)                       Linux Programmer's Manual                      RPC(3)

NAME top

       rpc - library routines for remote procedure calls

SYNOPSIS AND DESCRIPTION top

       These routines allow C programs to make procedure calls on other machines
       across the network.  First, the client calls a procedure to send a data
       packet to the server.  Upon receipt of the packet, the server calls a
       dispatch routine to perform the requested service, and then sends back a
       reply.  Finally, the procedure call returns to the client.

       To take use of these routines, include the header file <rpc/rpc.h>.

       The prototypes below make use of the following types:

           typedef int bool_t;

           typedef bool_t (*xdrproc_t) (XDR *, void *, ...);

           typedef bool_t (*resultproc_t) (caddr_t resp,
                                           struct sockaddr_in *raddr);

       See the header files for the declarations of the AUTH, CLIENT, SVCXPRT, and
       XDR types.

       void auth_destroy(AUTH *auth);

              A macro that destroys the authentication information associated with
              auth.  Destruction usually involves deallocation of private data
              structures.  The use of auth is undefined after calling
              auth_destroy().

       AUTH *authnone_create(void);

              Create and return an RPC authentication handle that passes nonusable
              authentication information with each remote procedure call.  This is
              the default authentication used by RPC.

       AUTH *authunix_create(char *host, int uid, int gid,
                             int len, int *aup_gids);

              Create and return an RPC authentication handle that contains
              authentication information.  The parameter host is the name of the
              machine on which the information was created; uid is the user's user
              ID; gid is the user's current group ID; len and aup_gids refer to a
              counted array of groups to which the user belongs.  It is easy to
              impersonate a user.

       AUTH *authunix_create_default(void);

              Calls authunix_create() with the appropriate parameters.

       int callrpc(char *host, unsigned long prognum,
                   unsigned long versnum, unsigned long procnum,
                   xdrproc_t inproc, char *in,
                   xdrproc_t outproc, char *out);

              Call the remote procedure associated with prognum, versnum, and
              procnum on the machine, host.  The parameter in is the address of
              the procedure's argument(s), and out is the address of where to
              place the result(s); inproc is used to encode the procedure's
              parameters, and outproc is used to decode the procedure's results.
              This routine returns zero if it succeeds, or the value of enum
              clnt_stat cast to an integer if it fails.  The routine clnt_perrno()
              is handy for translating failure statuses into messages.

              Warning: calling remote procedures with this routine uses UDP/IP as
              a transport; see clntudp_create() for restrictions.  You do not have
              control of timeouts or authentication using this routine.

       enum clnt_stat clnt_broadcast(unsigned long prognum,
                            unsigned long versnum, unsigned long procnum,
                            xdrproc_t inproc, char *in,
                            xdrproc_t outproc, char *out,
                            resultproc_t eachresult);

              Like callrpc(), except the call message is broadcast to all locally
              connected broadcast nets.  Each time it receives a response, this
              routine calls eachresult(), whose form is:

                  eachresult(char *out, struct sockaddr_in *addr);

              where out is the same as out passed to clnt_broadcast(), except that
              the remote procedure's output is decoded there; addr points to the
              address of the machine that sent the results.  If eachresult()
              returns zero, clnt_broadcast() waits for more replies; otherwise it
              returns with appropriate status.

              Warning: broadcast sockets are limited in size to the maximum
              transfer unit of the data link.  For ethernet, this value is 1500
              bytes.

       enum clnt_stat clnt_call(CLIENT *clnt, unsigned long procnum,
                           xdrproc_t inproc, char *in,
                           xdrproc_t outproc, char *out,
                           struct timeval tout);

              A macro that calls the remote procedure procnum associated with the
              client handle, clnt, which is obtained with an RPC client creation
              routine such as clnt_create().  The parameter in is the address of
              the procedure's argument(s), and out is the address of where to
              place the result(s); inproc is used to encode the procedure's
              parameters, and outproc is used to decode the procedure's results;
              tout is the time allowed for results to come back.

       clnt_destroy(CLIENT *clnt);

              A macro that destroys the client's RPC handle.  Destruction usually
              involves deallocation of private data structures, including clnt
              itself.  Use of clnt is undefined after calling clnt_destroy().  If
              the RPC library opened the associated socket, it will close it also.
              Otherwise, the socket remains open.

       CLIENT *clnt_create(char *host, unsigned long prog,
                           unsigned long vers, char *proto);

              Generic client creation routine.  host identifies the name of the
              remote host where the server is located.  proto indicates which kind
              of transport protocol to use.  The currently supported values for
              this field are "udp" and "tcp".  Default timeouts are set, but can
              be modified using clnt_control().

              Warning: Using UDP has its shortcomings.  Since UDP-based RPC
              messages can only hold up to 8 Kbytes of encoded data, this
              transport cannot be used for procedures that take large arguments or
              return huge results.

       bool_t clnt_control(CLIENT *cl, int req, char *info);

              A macro used to change or retrieve various information about a
              client object.  req indicates the type of operation, and info is a
              pointer to the information.  For both UDP and TCP, the supported
              values of req and their argument types and what they do are:

                  CLSET_TIMEOUT  struct timeval // set total timeout
                  CLGET_TIMEOUT  struct timeval // get total timeout

              Note: if you set the timeout using clnt_control(), the timeout
              parameter passed to clnt_call() will be ignored in all future calls.

                  CLGET_SERVER_ADDR  struct sockaddr_in  // get server's address

              The following operations are valid for UDP only:

                  CLSET_RETRY_TIMEOUT  struct timeval // set the retry timeout
                  CLGET_RETRY_TIMEOUT  struct timeval // get the retry timeout

              The retry timeout is the time that "UDP RPC" waits for the server to
              reply before retransmitting the request.

       clnt_freeres(CLIENT * clnt, xdrproc_t outproc, char *out);

              A macro that frees any data allocated by the RPC/XDR system when it
              decoded the results of an RPC call.  The parameter out is the
              address of the results, and outproc is the XDR routine describing
              the results.  This routine returns one if the results were
              successfully freed, and zero otherwise.

       void clnt_geterr(CLIENT *clnt, struct rpc_err *errp);

              A macro that copies the error structure out of the client handle to
              the structure at address errp.

       void clnt_pcreateerror(char *s);

              Print a message to standard error indicating why a client RPC handle
              could not be created.  The message is prepended with string s and a
              colon.  Used when a clnt_create(), clntraw_create(),
              clnttcp_create(), or clntudp_create() call fails.

       void clnt_perrno(enum clnt_stat stat);

              Print a message to standard error corresponding to the condition
              indicated by stat.  Used after callrpc().

       clnt_perror(CLIENT *clnt, char *s);

              Print a message to standard error indicating why an RPC call failed;
              clnt is the handle used to do the call.  The message is prepended
              with string s and a colon.  Used after clnt_call().

       char *clnt_spcreateerror(char *s);

              Like clnt_pcreateerror(), except that it returns a string instead of
              printing to the standard error.

              Bugs: returns pointer to static data that is overwritten on each
              call.

       char *clnt_sperrno(enum clnt_stat stat);

              Take the same arguments as clnt_perrno(), but instead of sending a
              message to the standard error indicating why an RPC call failed,
              return a pointer to a string which contains the message.  The string
              ends with a NEWLINE.

              clnt_sperrno() is used instead of clnt_perrno() if the program does
              not have a standard error (as a program running as a server quite
              likely does not), or if the programmer does not want the message to
              be output with printf(3), or if a message format different than that
              supported by clnt_perrno() is to be used.  Note: unlike
              clnt_sperror() and clnt_spcreaterror(), clnt_sperrno() returns
              pointer to static data, but the result will not get overwritten on
              each call.

       char *clnt_sperror(CLIENT *rpch, char *s);

              Like clnt_perror(), except that (like clnt_sperrno()) it returns a
              string instead of printing to standard error.

              Bugs: returns pointer to static data that is overwritten on each
              call.

       CLIENT *clntraw_create(unsigned long prognum, unsigned long versnum);

              This routine creates a toy RPC client for the remote program
              prognum, version versnum.  The transport used to pass messages to
              the service is actually a buffer within the process's address space,
              so the corresponding RPC server should live in the same address
              space; see svcraw_create().  This allows simulation of RPC and
              acquisition of RPC overheads, such as round trip times, without any
              kernel interference.  This routine returns NULL if it fails.

       CLIENT *clnttcp_create(struct sockaddr_in *addr,
                       unsigned long prognum, unsigned long versnum,
                       int *sockp, unsigned int sendsz, unsigned int recvsz);

              This routine creates an RPC client for the remote program prognum,
              version versnum; the client uses TCP/IP as a transport.  The remote
              program is located at Internet address *addr.  If addr->sin_port is
              zero, then it is set to the actual port that the remote program is
              listening on (the remote portmap service is consulted for this
              information).  The parameter sockp is a socket; if it is
              RPC_ANYSOCK, then this routine opens a new one and sets sockp.
              Since TCP-based RPC uses buffered I/O, the user may specify the size
              of the send and receive buffers with the parameters sendsz and
              recvsz; values of zero choose suitable defaults.  This routine
              returns NULL if it fails.

       CLIENT *clntudp_create(struct sockaddr_in *addr,
                       unsigned long prognum, unsigned long versnum,
                       struct timeval wait, int *sockp);

              This routine creates an RPC client for the remote program prognum,
              version versnum; the client uses use UDP/IP as a transport.  The
              remote program is located at Internet address addr.  If
              addr->sin_port is zero, then it is set to actual port that the
              remote program is listening on (the remote portmap service is
              consulted for this information).  The parameter sockp is a socket;
              if it is RPC_ANYSOCK, then this routine opens a new one and sets
              sockp.  The UDP transport resends the call message in intervals of
              wait time until a response is received or until the call times out.
              The total time for the call to time out is specified by clnt_call().

              Warning: since UDP-based RPC messages can only hold up to 8 Kbytes
              of encoded data, this transport cannot be used for procedures that
              take large arguments or return huge results.

       CLIENT *clntudp_bufcreate(struct sockaddr_in *addr,
                   unsigned long prognum, unsigned long versnum,
                   struct timeval wait, int *sockp,
                   unsigned int sendsize, unsigned int recosize);

              This routine creates an RPC client for the remote program prognum,
              on versnum; the client uses use UDP/IP as a transport.  The remote
              program is located at Internet address addr.  If addr->sin_port is
              zero, then it is set to actual port that the remote program is
              listening on (the remote portmap service is consulted for this
              information).  The parameter sockp is a socket; if it is
              RPC_ANYSOCK, then this routine opens a new one and sets sockp.  The
              UDP transport resends the call message in intervals of wait time
              until a response is received or until the call times out.  The total
              time for the call to time out is specified by clnt_call().

              This allows the user to specify the maximum packet size for sending
              and receiving UDP-based RPC messages.

       void get_myaddress(struct sockaddr_in *addr);

              Stuff the machine's IP address into *addr, without consulting the
              library routines that deal with /etc/hosts.  The port number is
              always set to htons(PMAPPORT).

       struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);

              A user interface to the portmap service, which returns a list of the
              current RPC program-to-port mappings on the host located at IP
              address *addr.  This routine can return NULL.  The command
              rpcinfo -p uses this routine.

       unsigned short pmap_getport(struct sockaddr_in *addr,
                           unsigned long prognum, unsigned long versnum,
                           unsigned int protocol);

              A user interface to the portmap service, which returns the port
              number on which waits a service that supports program number
              prognum, version versnum, and speaks the transport protocol
              associated with protocol.  The value of protocol is most likely
              IPPROTO_UDP or IPPROTO_TCP.  A return value of zero means that the
              mapping does not exist or that the RPC system failed to contact the
              remote portmap service.  In the latter case, the global variable
              rpc_createerr contains the RPC status.

       enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr,
                           unsigned long prognum, unsigned long versnum,
                           unsigned long procnum,
                           xdrproc_t inproc, char *in,
                           xdrproc_t outproc, char *out,
                           struct timeval tout, unsigned long *portp);

              A user interface to the portmap service, which instructs portmap on
              the host at IP address *addr to make an RPC call on your behalf to a
              procedure on that host.  The parameter *portp will be modified to
              the program's port number if the procedure succeeds.  The
              definitions of other parameters are discussed in callrpc() and
              clnt_call().  This procedure should be used for a "ping" and nothing
              else.  See also clnt_broadcast().

       bool_t pmap_set(unsigned long prognum, unsigned long versnum,
                       unsigned int protocol, unsigned short port);

              A user interface to the portmap service, which establishes a mapping
              between the triple [prognum,versnum,protocol] and port on the
              machine's portmap service.  The value of protocol is most likely
              IPPROTO_UDP or IPPROTO_TCP.  This routine returns one if it
              succeeds, zero otherwise.  Automatically done by svc_register().

       bool_t pmap_unset(unsigned long prognum, unsigned long versnum);

              A user interface to the portmap service, which destroys all mapping
              between the triple [prognum,versnum,*] and ports on the machine's
              portmap service.  This routine returns one if it succeeds, zero
              otherwise.

       int registerrpc(unsigned long prognum, unsigned long versnum,
                       unsigned long procnum, char *(*procname)(char *),
                       xdrproc_t inproc, xdrproc_t outproc);

              Register procedure procname with the RPC service package.  If a
              request arrives for program prognum, version versnum, and procedure
              procnum, procname is called with a pointer to its parameter(s);
              progname should return a pointer to its static result(s); inproc is
              used to decode the parameters while outproc is used to encode the
              results.  This routine returns zero if the registration succeeded,
              -1 otherwise.

              Warning: remote procedures registered in this form are accessed
              using the UDP/IP transport; see svcudp_create() for restrictions.

       struct rpc_createerr rpc_createerr;

              A global variable whose value is set by any RPC client creation
              routine that does not succeed.  Use the routine clnt_pcreateerror()
              to print the reason why.

       void svc_destroy(SVCXPRT *xprt);

              A macro that destroys the RPC service transport handle, xprt.
              Destruction usually involves deallocation of private data
              structures, including xprt itself.  Use of xprt is undefined after
              calling this routine.

       fd_set svc_fdset;

              A global variable reflecting the RPC service side's read file
              descriptor bit mask; it is suitable as a parameter to the select(2)
              system call.  This is only of interest if a service implementor does
              not call svc_run(), but rather does his own asynchronous event
              processing.  This variable is read-only (do not pass its address to
              select(2)!), yet it may change after calls to svc_getreqset() or any
              creation routines.

       int svc_fds;

              Similar to svc_fdset, but limited to 32 descriptors.  This interface
              is obsoleted by svc_fdset.

       svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);

              A macro that frees any data allocated by the RPC/XDR system when it
              decoded the arguments to a service procedure using svc_getargs().
              This routine returns 1 if the results were successfully freed, and
              zero otherwise.

       svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);

              A macro that decodes the arguments of an RPC request associated with
              the RPC service transport handle, xprt.  The parameter in is the
              address where the arguments will be placed; inproc is the XDR
              routine used to decode the arguments.  This routine returns one if
              decoding succeeds, and zero otherwise.

       struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);

              The approved way of getting the network address of the caller of a
              procedure associated with the RPC service transport handle, xprt.

       void svc_getreqset(fd_set *rdfds);

              This routine is only of interest if a service implementor does not
              call svc_run(), but instead implements custom asynchronous event
              processing.  It is called when the select(2) system call has
              determined that an RPC request has arrived on some RPC socket(s);
              rdfds is the resultant read file descriptor bit mask.  The routine
              returns when all sockets associated with the value of rdfds have
              been serviced.

       void svc_getreq(int rdfds);

              Similar to svc_getreqset(), but limited to 32 descriptors.  This
              interface is obsoleted by svc_getreqset().

       bool_t svc_register(SVCXPRT *xprt, unsigned long prognum,
                           unsigned long versnum,
                           void (*dispatch)(svc_req *, SVCXPRT *),
                           unsigned long protocol);

              Associates prognum and versnum with the service dispatch procedure,
              dispatch.  If protocol is zero, the service is not registered with
              the portmap service.  If protocol is nonzero, then a mapping of the
              triple [prognum,versnum,protocol] to xprt->xp_port is established
              with the local portmap service (generally protocol is zero,
              IPPROTO_UDP or IPPROTO_TCP).  The procedure dispatch has the
              following form:

                  dispatch(struct svc_req *request, SVCXPRT *xprt);

              The svc_register() routine returns one if it succeeds, and zero
              otherwise.

       void svc_run(void);

              This routine never returns.  It waits for RPC requests to arrive,
              and calls the appropriate service procedure using svc_getreq() when
              one arrives.  This procedure is usually waiting for a select(2)
              system call to return.

       bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out);

              Called by an RPC service's dispatch routine to send the results of a
              remote procedure call.  The parameter xprt is the request's
              associated transport handle; outproc is the XDR routine which is
              used to encode the results; and out is the address of the results.
              This routine returns one if it succeeds, zero otherwise.

       void svc_unregister(unsigned long prognum, unsigned long versnum);

              Remove all mapping of the double [prognum,versnum] to dispatch
              routines, and of the triple [prognum,versnum,*] to port number.

       void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);

              Called by a service dispatch routine that refuses to perform a
              remote procedure call due to an authentication error.

       void svcerr_decode(SVCXPRT *xprt);

              Called by a service dispatch routine that cannot successfully decode
              its parameters.  See also svc_getargs().

       void svcerr_noproc(SVCXPRT *xprt);

              Called by a service dispatch routine that does not implement the
              procedure number that the caller requests.

       void svcerr_noprog(SVCXPRT *xprt);

              Called when the desired program is not registered with the RPC
              package.  Service implementors usually do not need this routine.

       void svcerr_progvers(SVCXPRT *xprt);

              Called when the desired version of a program is not registered with
              the RPC package.  Service implementors usually do not need this
              routine.

       void svcerr_systemerr(SVCXPRT *xprt);

              Called by a service dispatch routine when it detects a system error
              not covered by any particular protocol.  For example, if a service
              can no longer allocate storage, it may call this routine.

       void svcerr_weakauth(SVCXPRT *xprt);

              Called by a service dispatch routine that refuses to perform a
              remote procedure call due to insufficient authentication parameters.
              The routine calls svcerr_auth(xprt, AUTH_TOOWEAK).

       SVCXPRT *svcfd_create(int fd, unsigned int sendsize,
                             unsigned int recvsize);

              Create a service on top of any open descriptor.  Typically, this
              descriptor is a connected socket for a stream protocol such as TCP.
              sendsize and recvsize indicate sizes for the send and receive
              buffers.  If they are zero, a reasonable default is chosen.

       SVCXPRT *svcraw_create(void);

              This routine creates a toy RPC service transport, to which it
              returns a pointer.  The transport is really a buffer within the
              process's address space, so the corresponding RPC client should live
              in the same address space; see clntraw_create().  This routine
              allows simulation of RPC and acquisition of RPC overheads (such as
              round trip times), without any kernel interference.  This routine
              returns NULL if it fails.

       SVCXPRT *svctcp_create(int sock, unsigned int send_buf_size,
                              unsigned int recv_buf_size);

              This routine creates a TCP/IP-based RPC service transport, to which
              it returns a pointer.  The transport is associated with the socket
              sock, which may be RPC_ANYSOCK, in which case a new socket is
              created.  If the socket is not bound to a local TCP port, then this
              routine binds it to an arbitrary port.  Upon completion,
              xprt->xp_sock is the transport's socket descriptor, and
              xprt->xp_port is the transport's port number.  This routine returns
              NULL if it fails.  Since TCP-based RPC uses buffered I/O, users may
              specify the size of buffers; values of zero choose suitable
              defaults.

       SVCXPRT *svcudp_bufcreate(int sock, unsigned int sendsize,
                                 unsigned int recosize);

              This routine creates a UDP/IP-based RPC service transport, to which
              it returns a pointer.  The transport is associated with the socket
              sock, which may be RPC_ANYSOCK, in which case a new socket is
              created.  If the socket is not bound to a local UDP port, then this
              routine binds it to an arbitrary port.  Upon completion,
              xprt->xp_sock is the transport's socket descriptor, and
              xprt->xp_port is the transport's port number.  This routine returns
              NULL if it fails.

              This allows the user to specify the maximum packet size for sending
              and receiving UDP-based RPC messages.

       SVCXPRT *svcudp_create(int sock);

              This call is equivalent to svcudp_bufcreate(sock,SZ,SZ) for some
              default size SZ.

       bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *ar);

              Used for encoding RPC reply messages.  This routine is useful for
              users who wish to generate RPC-style messages without using the RPC
              package.

       bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *aupp);

              Used for describing UNIX credentials.  This routine is useful for
              users who wish to generate these credentials without using the RPC
              authentication package.

       void xdr_callhdr(XDR *xdrs, struct rpc_msg *chdr);

              Used for describing RPC call header messages.  This routine is
              useful for users who wish to generate RPC-style messages without
              using the RPC package.

       bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg);

              Used for describing RPC call messages.  This routine is useful for
              users who wish to generate RPC-style messages without using the RPC
              package.

       bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap);

              Used for describing RPC authentication information messages.  This
              routine is useful for users who wish to generate RPC-style messages
              without using the RPC package.

       bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);

              Used for describing parameters to various portmap procedures,
              externally.  This routine is useful for users who wish to generate
              these parameters without using the pmap interface.

       bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rp);

              Used for describing a list of port mappings, externally.  This
              routine is useful for users who wish to generate these parameters
              without using the pmap interface.

       bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr);

              Used for describing RPC reply messages.  This routine is useful for
              users who wish to generate RPC-style messages without using the RPC
              package.

       bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg);

              Used for describing RPC reply messages.  This routine is useful for
              users who wish to generate RPC style messages without using the RPC
              package.

       void xprt_register(SVCXPRT *xprt);

              After RPC service transport handles are created, they should
              register themselves with the RPC service package.  This routine
              modifies the global variable svc_fds.  Service implementors usually
              do not need this routine.

       void xprt_unregister(SVCXPRT *xprt);

              Before an RPC service transport handle is destroyed, it should
              unregister itself with the RPC service package.  This routine
              modifies the global variable svc_fds.  Service implementors usually
              do not need this routine.

SEE ALSO top

       xdr(3)

       The following manuals:
              Remote Procedure Calls: Protocol Specification
              Remote Procedure Call Programming Guide
              rpcgen Programming Guide

       RPC: Remote Procedure Call Protocol Specification, RFC 1050, Sun
       Microsystems, Inc., USC-ISI.

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-07-17                              RPC(3)


backtrace(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

BACKTRACE(3)                 Linux Programmer's Manual                BACKTRACE(3)

NAME top

       backtrace,  backtrace_symbols,  backtrace_symbols_fd - support for applica-
       tion self-debugging

SYNOPSIS top

       #include <execinfo.h>

       int backtrace(void **buffer, int size);

       char **backtrace_symbols(void *const *buffer, int size);

       void backtrace_symbols_fd(void *const *buffer, int size, int fd);

DESCRIPTION top

       backtrace() returns a backtrace for the calling program, in the array
       pointed to by buffer.  A backtrace is the series of currently active
       function calls for the program.  Each item in the array pointed to by
       buffer is of type void *, and is the return address from the corresponding
       stack frame.  The size argument specifies the maximum number of addresses
       that can be stored in buffer.  If the backtrace is larger than size, then
       the addresses corresponding to the size most recent function calls are
       returned; to obtain the complete backtrace, make sure that buffer and size
       are large enough.

       Given the set of addresses returned by backtrace() in buffer,
       backtrace_symbols() translates the addresses into an array of strings that
       describe the addresses symbolically.  The size argument specifies the
       number of addresses in buffer.  The symbolic representation of each address
       consists of the function name (if this can be determined), a hexadecimal
       offset into the function, and the actual return address (in hexadecimal).
       The address of the array of string pointers is returned as the function
       result of backtrace_symbols().  This array is malloc(3)ed by
       backtrace_symbols(), and must be freed by the caller.  (The strings pointed
       to by the array of pointers need not and should not be freed.)

       backtrace_symbols_fd() takes the same buffer and size arguments as
       backtrace_symbols(), but instead of returning an array of strings to the
       caller, it writes the strings, one per line, to the file descriptor fd.
       backtrace_symbols_fd() does not call malloc(3), and so can be employed in
       situations where the latter function might fail.

RETURN VALUE top

       backtrace() returns the number of addresses returned in buffer, which is
       not greater than size.  If the return value is less than size, then the
       full backtrace was stored; if it is equal to size, then it may have been
       truncated, in which case the addresses of the oldest stack frames are not
       returned.

       On success, backtrace_symbols() returns a pointer to the array malloc(3)ed
       by the call; on error, NULL is returned.

VERSIONS top

       backtrace(), backtrace_symbols(), and backtrace_symbols_fd() are provided
       in glibc since version 2.1.

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       These functions make some assumptions about how a function's return address
       is stored on the stack.  Note the following:

       *  Omission of the frame pointers (as implied by any of gcc(1)'s nonzero
          optimization levels) may cause these assumptions to be violated.

       *  Inlined functions do not have stack frames.

       *  Tail-call optimization causes one stack frame to replace another.

       The symbol names may be unavailable without the use of special linker
       options.  For systems using the GNU linker, it is necessary to use the
       -rdynamic linker option.  Note that names of "static" functions are not
       exposed, and won't be available in the backtrace.

EXAMPLE top

       The program below demonstrates the use of backtrace() and
       backtrace_symbols().  The following shell session shows what we might see
       when running the program:

           $ cc -rdynamic prog.c -o prog
           $ ./prog 3
           backtrace() returned 8 addresses
           ./prog(myfunc3+0x5c) [0x80487f0]
           ./prog [0x8048871]
           ./prog(myfunc+0x21) [0x8048894]
           ./prog(myfunc+0x1a) [0x804888d]
           ./prog(myfunc+0x1a) [0x804888d]
           ./prog(main+0x65) [0x80488fb]
           /lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
           ./prog [0x8048711]

Program source

       #include <execinfo.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       void
       myfunc3(void)
       {
           int j, nptrs;
       #define SIZE 100
           void *buffer[100];
           char **strings;

           nptrs = backtrace(buffer, SIZE);
           printf("backtrace() returned %d addresses\n", nptrs);

           /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
              would produce similar output to the following: */

           strings = backtrace_symbols(buffer, nptrs);
           if (strings == NULL) {
               perror("backtrace_symbols");
               exit(EXIT_FAILURE);
           }

           for (j = 0; j < nptrs; j++)
               printf("%s\n", strings[j]);

           free(strings);
       }

       static void   /* "static" means don't export the symbol... */
       myfunc2(void)
       {
           myfunc3();
       }

       void
       myfunc(int ncalls)
       {
           if (ncalls > 1)
               myfunc(ncalls - 1);
           else
               myfunc2();
       }

       int
       main(int argc, char *argv[])
       {
           if (argc != 2) {
               fprintf(stderr, "%s num-calls\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           myfunc(atoi(argv[1]));
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       gcc(1), ld(1), dlopen(3), malloc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-06-14                        BACKTRACE(3)


basename(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

BASENAME(3)                  Linux Programmer's Manual                 BASENAME(3)

NAME top

       basename, dirname - parse pathname components

SYNOPSIS top

       #include <libgen.h>

       char *dirname(char *path);

       char *basename(char *path);

DESCRIPTION top

       Warning: there are two different functions basename() - see below.

       The functions dirname() and basename() break a null-terminated pathname
       string into directory and filename components.  In the usual case,
       dirname() returns the string up to, but not including, the final '/', and
       basename() returns the component following the final '/'.  Trailing '/'
       characters are not counted as part of the pathname.

       If path does not contain a slash, dirname() returns the string "." while
       basename() returns a copy of path.  If path is the string "/", then both
       dirname() and basename() return the string "/".  If path is a NULL pointer
       or points to an empty string, then both dirname() and basename() return the
       string ".".

       Concatenating the string returned by dirname(), a "/", and the string
       returned by basename() yields a complete pathname.

       Both dirname() and basename() may modify the contents of path, so it may be
       desirable to pass a copy when calling one of these functions.

       These functions may return pointers to statically allocated memory which
       may be overwritten by subsequent calls.  Alternatively, they may return a
       pointer to some part of path, so that the string referred to by path should
       not be modified or freed until the pointer returned by the function is no
       longer required.

       The following list of examples (taken from SUSv2) shows the strings
       returned by dirname() and basename() for different paths:

       path         dirname    basename
       "/usr/lib"    "/usr"    "lib"
       "/usr/"       "/"       "usr"
       "usr"         "."       "usr"
       "/"           "/"       "/"
       "."           "."       "."
       ".."          "."       ".."

RETURN VALUE top

       Both dirname() and basename() return pointers to null-terminated strings.
       (Do not pass these pointers to free(3).)

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       There are two different versions of basename() - the POSIX version
       described above, and the GNU version, which one gets after

           #define _GNU_SOURCE         /* See feature_test_macros(7) */
           #include <string.h>

       The GNU version never modifies its argument, and returns the empty string
       when path has a trailing slash, and in particular also when it is "/".
       There is no GNU version of dirname().

       With glibc, one gets the POSIX version of basename() when <libgen.h> is
       included, and the GNU version otherwise.

BUGS top

       In the glibc implementation of the POSIX versions of these functions they
       modify their argument, and segfault when called with a static string like
       "/usr/".  Before glibc 2.2.1, the glibc version of dirname() did not
       correctly handle pathnames with trailing '/' characters, and generated a
       segfault if given a NULL argument.

EXAMPLE top

           char *dirc, *basec, *bname, *dname;
           char *path = "/etc/passwd";

           dirc = strdup(path);
           basec = strdup(path);
           dname = dirname(dirc);
           bname = basename(basec);
           printf("dirname=%s, basename=%s\n", dname, bname);

SEE ALSO top

       basename(1), dirname(1)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-03-30                         BASENAME(3)


bcmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

BCMP(3)                      Linux Programmer's Manual                     BCMP(3)

NAME top

       bcmp - compare byte sequences

SYNOPSIS top

       #include <strings.h>

       int bcmp(const void *s1, const void *s2, size_t n);

DESCRIPTION top

       The bcmp() function compares the two byte sequences s1 and s2 of length n
       each.  If they are equal, and in particular if n is zero, bcmp() returns 0.
       Otherwise it returns a nonzero result.

RETURN VALUE top

       The bcmp() function returns 0 if the byte sequences are equal, otherwise a
       nonzero result is returned.

CONFORMING TO top

       4.3BSD.  This function is deprecated (marked as LEGACY in POSIX.1-2001):
       use memcmp(3) in new programs.  POSIX.1-2008 removes the specification of
       bcmp().

SEE ALSO top

       memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncasecmp(3), strncmp(3)

COLOPHON top

       This page is part of release 3.45 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                             BCMP(3)


bcopy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

BCOPY(3)                     Linux Programmer's Manual                    BCOPY(3)

NAME top

       bcopy - copy byte sequence

SYNOPSIS top

       #include <strings.h>

       void bcopy(const void *src, void *dest, size_t n);

DESCRIPTION top

       The bcopy() function copies n bytes from src to dest.  The result is
       correct, even when both areas overlap.

RETURN VALUE top

       None.

CONFORMING TO top

       4.3BSD.  This function is deprecated (marked as LEGACY in POSIX.1-2001):
       use memcpy(3) or memmove(3) in new programs.  Note that the first two
       arguments are interchanged for memcpy(3) and memmove(3).  POSIX.1-2008
       removes the specification of bcopy().

SEE ALSO top

       memccpy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3)

COLOPHON top

       This page is part of release 3.45 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                               2009-03-15                            BCOPY(3)


bdflush(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

BDFLUSH(2)                   Linux Programmer's Manual                  BDFLUSH(2)

NAME top

       bdflush - start, flush, or tune buffer-dirty-flush daemon

SYNOPSIS top

       #include <sys/kdaemon.h>

       int bdflush(int func, long *address);
       int bdflush(int func, long data);

DESCRIPTION top

       Note: Since Linux 2.6, this system call is deprecated and does nothing.  It
       is likely to disappear altogether in a future kernel release.  Nowadays,
       the task performed by bdflush() is handled by the kernel pdflush thread.

       bdflush() starts, flushes, or tunes the buffer-dirty-flush daemon.  Only a
       privileged process (one with the CAP_SYS_ADMIN capability) may call
       bdflush().

       If func is negative or 0, and no daemon has been started, then bdflush()
       enters the daemon code and never returns.

       If func is 1, some dirty buffers are written to disk.

       If func is 2 or more and is even (low bit is 0), then address is the
       address of a long word, and the tuning parameter numbered (func-2)/2 is
       returned to the caller in that address.

       If func is 3 or more and is odd (low bit is 1), then data is a long word,
       and the kernel sets tuning parameter numbered (func-3)/2 to that value.

       The set of parameters, their values, and their valid ranges are defined in
       the Linux kernel source file fs/buffer.c.

RETURN VALUE top

       If func is negative or 0 and the daemon successfully starts, bdflush()
       never returns.  Otherwise, the return value is 0 on success and -1 on
       failure, with errno set to indicate the error.

ERRORS top

       EBUSY  An attempt was made to enter the daemon code after another process
              has already entered.

       EFAULT address points outside your accessible address space.

       EINVAL An attempt was made to read or write an invalid parameter number, or
              to write an invalid value to a parameter.

       EPERM  Caller does not have the CAP_SYS_ADMIN capability.

CONFORMING TO top

       bdflush() is Linux-specific and should not be used in programs intended to
       be portable.

SEE ALSO top

       fsync(2), sync(2), sync(8), update(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-05                          BDFLUSH(2)


endian(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

ENDIAN(3)                    Linux Programmer's Manual                   ENDIAN(3)

NAME top

       htobe16,  htole16,  be16toh,  le16toh,  htobe32, htole32, be32toh, le32toh,
       htobe64, htole64, be64toh,  le64toh  -  convert  values  between  host  and
       big-/little-endian byte order

SYNOPSIS top

       #define _BSD_SOURCE             /* See feature_test_macros(7) */
       #include <endian.h>

       uint16_t htobe16(uint16_t host_16bits);
       uint16_t htole16(uint16_t host_16bits);
       uint16_t be16toh(uint16_t big_endian_16bits);
       uint16_t le16toh(uint16_t little_endian_16bits);

       uint32_t htobe32(uint32_t host_32bits);
       uint32_t htole32(uint32_t host_32bits);
       uint32_t be32toh(uint32_t big_endian_32bits);
       uint32_t le32toh(uint32_t little_endian_32bits);

       uint64_t htobe64(uint64_t host_64bits);
       uint64_t htole64(uint64_t host_64bits);
       uint64_t be64toh(uint64_t big_endian_64bits);
       uint64_t le64toh(uint64_t little_endian_64bits);

DESCRIPTION top

       These functions convert the byte encoding of integer values from the byte
       order that the current CPU (the "host") uses, to and from little-endian and
       big-endian byte order.

       The number, nn, in the name of each function indicates the size of integer
       handled by the function, either 16, 32, or 64 bits.

       The functions with names of the form "htobenn" convert from host byte order
       to big-endian order.

       The functions with names of the form "htolenn" convert from host byte order
       to little-endian order.

       The functions with names of the form "benntoh" convert from big-endian
       order to host byte order.

       The functions with names of the form "lenntoh" convert from little-endian
       order to host byte order.

VERSIONS top

       These functions were added to glibc in version 2.9.

CONFORMING TO top

       These functions are nonstandard.  Similar functions are present on the
       BSDs, where the required header file is <sys/endian.h> instead of
       <endian.h>.  Unfortunately, NetBSD, FreeBSD, and glibc haven't followed the
       original OpenBSD naming convention for these functions, whereby the nn
       component always appears at the end of the function name (thus, for
       example, in NetBSD, FreeBSD, and glibc, the equivalent of OpenBSDs
       "betoh32" is "be32toh").

NOTES top

       These functions are similar to the older byteorder(3) family of functions.
       For example, be32toh() is identical to ntohl().

       The advantage of the byteorder(3) functions is that they are standard
       functions available on all UNIX systems.  On the other hand, the fact that
       they were designed for use in the context of TCP/IP means that they lack
       the 64-bit and little-endian variants described in this page.

EXAMPLE top

       The program below display the results of converting an integer from host
       byte order to both little-endian and big-endian byte order.  Since host
       byte order is either little-endian or big-endian, only one of these
       conversions will have an effect.  When we run this program on a little-
       endian system such as x86-32, we see the following:

           $ ./a.out
           x.u32 = 0x44332211
           htole32(x.u32) = 0x44332211
           htobe32(x.u32) = 0x11223344

Program source

       #include <endian.h>
       #include <stdint.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           union {
            uint32_t u32;
            uint8_t arr[4];
           } x;

           x.arr[0] = 0x11;     /* Lowest-address byte */
           x.arr[1] = 0x22;
           x.arr[2] = 0x33;
           x.arr[3] = 0x44;     /* Highest-address byte */

           printf("x.u32 = 0x%x\n", x.u32);
           printf("htole32(x.u32) = 0x%x\n", htole32(x.u32));
           printf("htobe32(x.u32) = 0x%x\n", htobe32(x.u32));

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       byteorder(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                           ENDIAN(3)


bind(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

BIND(2)                      Linux Programmer's Manual                     BIND(2)

NAME top

       bind - bind a name to a socket

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int bind(int sockfd, const struct sockaddr *addr,
                socklen_t addrlen);

DESCRIPTION top

       When a socket is created with socket(2), it exists in a name space (address
       family) but has no address assigned to it.  bind() assigns the address
       specified by addr to the socket referred to by the file descriptor sockfd.
       addrlen specifies the size, in bytes, of the address structure pointed to
       by addr.  Traditionally, this operation is called "assigning a name to a
       socket".

       It is normally necessary to assign a local address using bind() before a
       SOCK_STREAM socket may receive connections (see accept(2)).

       The rules used in name binding vary between address families.  Consult the
       manual entries in Section 7 for detailed information.  For AF_INET see
       ip(7), for AF_INET6 see ipv6(7), for AF_UNIX see unix(7), for AF_APPLETALK
       see ddp(7), for AF_PACKET see packet(7), for AF_X25 see x25(7) and for
       AF_NETLINK see netlink(7).

       The actual structure passed for the addr argument will depend on the
       address family.  The sockaddr structure is defined as something like:

           struct sockaddr {
               sa_family_t sa_family;
               char        sa_data[14];
           }

       The only purpose of this structure is to cast the structure pointer passed
       in addr in order to avoid compiler warnings.  See EXAMPLE below.

RETURN VALUE top

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

ERRORS top

       EACCES The address is protected, and the user is not the superuser.

       EADDRINUSE
              The given address is already in use.

       EBADF  sockfd is not a valid descriptor.

       EINVAL The socket is already bound to an address.

       ENOTSOCK
              sockfd is a descriptor for a file, not a socket.

       The following errors are specific to UNIX domain (AF_UNIX) sockets:

       EACCES Search permission is denied on a component of the path prefix.  (See
              also path_resolution(7).)

       EADDRNOTAVAIL
              A nonexistent interface was requested or the requested address was
              not local.

       EFAULT addr points outside the user's accessible address space.

       EINVAL The addrlen is wrong, or the socket was not in the AF_UNIX family.

       ELOOP  Too many symbolic links were encountered in resolving addr.

       ENAMETOOLONG
              addr is too long.

       ENOENT The file does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of the path prefix is not a directory.

       EROFS  The socket inode would reside on a read-only file system.

CONFORMING TO top

       SVr4, 4.4BSD, POSIX.1-2001 (bind() first appeared in 4.2BSD).

NOTES top

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

       The third argument of bind() is in reality an int (and this is what 4.x BSD
       and libc4 and libc5 have).  Some POSIX confusion resulted in the present
       socklen_t, also used by glibc.  See also accept(2).

BUGS top

       The transparent proxy options are not described.

EXAMPLE top

       An example of the use of bind() with Internet domain sockets can be found
       in getaddrinfo(3).

       The following example shows how to bind a stream socket in the UNIX
       (AF_UNIX) domain, and accept connections:

       #include <sys/socket.h>
       #include <sys/un.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <string.h>

       #define MY_SOCK_PATH "/somepath"
       #define LISTEN_BACKLOG 50

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

       int
       main(int argc, char *argv[])
       {
           int sfd, cfd;
           struct sockaddr_un my_addr, peer_addr;
           socklen_t peer_addr_size;

           sfd = socket(AF_UNIX, SOCK_STREAM, 0);
           if (sfd == -1)
               handle_error("socket");

           memset(&my_addr, 0, sizeof(struct sockaddr_un));
                               /* Clear structure */
           my_addr.sun_family = AF_UNIX;
           strncpy(my_addr.sun_path, MY_SOCK_PATH,
                   sizeof(my_addr.sun_path) - 1);

           if (bind(sfd, (struct sockaddr *) &my_addr,
                   sizeof(struct sockaddr_un)) == -1)
               handle_error("bind");

           if (listen(sfd, LISTEN_BACKLOG) == -1)
               handle_error("listen");

           /* Now we can accept incoming connections one
              at a time using accept(2) */

           peer_addr_size = sizeof(struct sockaddr_un);
           cfd = accept(sfd, (struct sockaddr *) &peer_addr,
                        &peer_addr_size);
           if (cfd == -1)
               handle_error("accept");

           /* Code to deal with incoming connection(s)... */

           /* When no longer required, the socket pathname, MY_SOCK_PATH
              should be deleted using unlink(2) or remove(3) */
       }

SEE ALSO top

       accept(2), connect(2), getsockname(2), listen(2), socket(2),
       getaddrinfo(3), getifaddrs(3), ip(7), ipv6(7), path_resolution(7),
       socket(7), unix(7)

COLOPHON top

       This page is part of release 3.45 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-12-28                             BIND(2)


bindresvport(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

BINDRESVPORT(3)              Linux Programmer's Manual             BINDRESVPORT(3)

NAME top

       bindresvport - bind a socket to a privileged IP port

SYNOPSIS top

       #include <sys/types.h>
       #include <netinet/in.h>

       int bindresvport(int sockfd, struct sockaddr_in *sin);

DESCRIPTION top

       bindresvport() is used to bind a socket descriptor to a privileged
       anonymous IP port, that is, a port number arbitrarily selected from the
       range 512 to 1023.

       If the bind(2) performed by bindresvport() is successful, and sin is not
       NULL, then sin->sin_port returns the port number actually allocated.

       sin can be NULL, in which case sin->sin_family is implicitly taken to be
       AF_INET.  However, in this case, bindresvport() has no way to return the
       port number actually allocated.  (This information can later be obtained
       using getsockname(2).)

RETURN VALUE top

       bindresvport() returns 0 on success; otherwise -1 is returned and errno set
       to indicate the cause of the error.

ERRORS top

       bindresvport() can fail for any of the same reasons as bind(2).  In
       addition, the following errors may occur:

       EACCES The caller did not have superuser privilege (to be precise: the
              CAP_NET_BIND_SERVICE capability is required).

       EADDRINUSE
              All privileged ports are in use.

       EAFNOSUPPORT (EPFNOSUPPORT in glibc 2.7 and earlier)
              sin is not NULL and sin->sin_family is not AF_INET.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs, Solaris, and many other systems.

NOTES top

       Unlike some bindresvport() implementations, the glibc implementation
       ignores any value that the caller supplies in sin->sin_port.

SEE ALSO top

       bind(2), getsockname(2)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-12-03                     BINDRESVPORT(3)


boot(7) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

BOOT(7)                      Linux Programmer's Manual                     BOOT(7)

NAME top

       boot-scripts - general description of boot sequence

DESCRIPTION top

       The boot sequence varies in details among systems but can be roughly
       divided to the following steps: (i) hardware boot, (ii) operating system
       (OS) loader, (iii) kernel startup, (iv) init and inittab, (v) boot scripts.
       We will describe each of these in more detail below.

Hardware-boot

       After power-on or hard reset, control is given to a program stored on read-
       only memory (normally PROM).  In PC we usually call this program the BIOS.

       This program normally makes a basic self-test of the machine and accesses
       nonvolatile memory to read further parameters.  This memory in the PC is
       battery-backed CMOS memory, so most people refer to it as the CMOS,
       although outside of the PC world, it is usually called nvram (nonvolatile
       ram).

       The parameters stored in the nvram vary between systems, but as a minimum,
       the hardware boot program should know what is the boot device, or which
       devices to probe as possible boot devices.

       Then the hardware boot stage accesses the boot device, loads the OS Loader,
       which is located on a fixed position on the boot device, and transfers
       control to it.

       Note:  We do not cover here booting from network.  Those who want to
              investigate this subject may want to research: DHCP, TFTP, PXE,
              Etherboot.

OS Loader

       In PC, the OS Loader is located in the first sector of the boot device -
       this is the MBR (Master Boot Record).

       In most systems, this primary loader is very limited due to various
       constraints.  Even on non-PC systems there are some limitations to the size
       and complexity of this loader, but the size limitation of the PC MBR (512
       bytes including the partition table) makes it almost impossible to squeeze
       a full OS Loader into it.

       Therefore, most operating systems make the primary loader call a secondary
       OS loader which may be located on a specified disk partition.

       In Linux the OS loader is normally lilo(8) or grub(8).  Both of them may
       install either as secondary loaders (where the DOS installed MBR points to
       them), or as a two part loader where they provide special MBR containing
       the bootstrap code to load the second part of the loader from the root
       partition.

       The main job of the OS Loader is to locate the kernel on the disk, load it
       and run it.  Most OS loaders allow interactive use, to enable specification
       of alternative kernel (maybe a backup in case the last compiled one isn't
       functioning) and to pass optional parameters to the kernel.

Kernel Startup

       When the kernel is loaded, it initializes the devices (via their drivers),
       starts the swapper (it is a "kernel process", called kswapd in modern Linux
       kernels), and mounts the root file system (/).

       Some of the parameters that may be passed to the kernel relate to these
       activities (e.g: You can override the default root file system).  For
       further information on Linux kernel parameters read bootparam(7).

       Only then the kernel creates the first (user land) process which is
       numbered 1.  This process executes the program /sbin/init, passing any
       parameters that weren't handled by the kernel already.

init and inittab

       When init starts it reads /etc/inittab for further instructions.  This file
       defines what should be run in different run-levels.

       This gives the system administrator an easy management scheme, where each
       run-level is associated with a set of services (e.g, S is single-user, on 2
       most network services start).  The administrator may change the current
       run-level via init(8) and query the current run-level via runlevel(8).

       However, since it is not convenient to manage individual services by
       editing this file, inittab only bootstraps a set of scripts that actually
       start/stop the individual services.

Boot Scripts

       Note:  The following description applies to System V release 4-based
              systems, which currently covers most commercial UNIX systems
              (Solaris, HP-UX, Irix, Tru64) as well as the major Linux
              distributions (Red Hat, Debian, Mandriva, SUSE, Ubuntu).  Some
              systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat
              different scheme of boot scripts.

       For each managed service (mail, nfs server, cron, etc.) there is a single
       startup script located in a specific directory (/etc/init.d in most
       versions of Linux).  Each of these scripts accepts as a single argument the
       word "start" -- causing it to start the service, or the word "stop" --
       causing it to stop the service.  The script may optionally accept other
       "convenience" parameters (e.g: "restart", to stop and then start, "status"
       do display the service status).  Running the script without parameters
       displays the possible arguments.

Sequencing Directories

       To make specific scripts start/stop at specific run-levels and in specific
       order, there are sequencing directories.  These are normally in
       /etc/rc[0-6S].d.  In each of these directories there are links (usually
       symbolic) to the scripts in the /etc/init.d directory.

       A primary script (usually /etc/rc) is called from inittab(5) and calls the
       services scripts via the links in the sequencing directories.  All links
       with names that begin with 'S' are being called with the argument "start"
       (thereby starting the service).  All links with names that begin with 'K'
       are being called with the argument "stop" (thereby stopping the service).

       To define the starting or stopping order within the same run-level, the
       names of the links contain order-numbers.  Also, to make the names clearer,
       they usually end with the name of the service they refer to.  Example: the
       link /etc/rc2.d/S80sendmail starts the sendmail service on runlevel 2.
       This happens after /etc/rc2.d/S12syslog is run but before /etc/rc2.d/S90xfs
       is run.

       To manage the boot order and run-levels, we have to manage these links.
       However, on many versions of Linux, there are tools to help with this task
       (e.g: chkconfig(8)).

Boot Configuration

       Usually the daemons started may optionally receive command-line options and
       parameters.  To allow system administrators to change these parameters
       without editing the boot scripts themselves, configuration files are used.
       These are located in a specific directory (/etc/sysconfig on Red Hat
       systems) and are used by the boot scripts.

       In older UNIX systems, these files contained the actual command line
       options for the daemons, but in modern Linux systems (and also in HP-UX),
       these files just contain shell variables.  The boot scripts in /etc/init.d
       source the configuration files, and then use the variable values.

FILES top

       /etc/init.d/, /etc/rc[S0-6].d/, /etc/sysconfig/

SEE ALSO top

       inittab(5), bootparam(7), init(8), runlevel(8), shutdown(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-19                             BOOT(7)


bootparam(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

BOOTPARAM(7)                 Linux Programmer's Manual                BOOTPARAM(7)

NAME top

       bootparam - introduction to boot time parameters of the Linux kernel

DESCRIPTION top

       The Linux kernel accepts certain 'command-line options' or 'boot time
       parameters' at the moment it is started.  In general this is used to supply
       the kernel with information about hardware parameters that the kernel would
       not be able to determine on its own, or to avoid/override the values that
       the kernel would otherwise detect.

       When the kernel is booted directly by the BIOS (say from a floppy to which
       you copied a kernel using 'cp zImage /dev/fd0'), you have no opportunity to
       specify any parameters.  So, in order to take advantage of this possibility
       you have to use software that is able to pass parameters, like LILO or
       loadlin.  For a few parameters one can also modify the kernel image itself,
       using rdev, see rdev(8) for further details.

       The LILO program (LInux LOader) written by Werner Almesberger is the most
       commonly used.  It has the ability to boot various kernels, and stores the
       configuration information in a plain text file.  (See lilo(8) and
       lilo.conf(5).)  LILO can boot DOS, OS/2, Linux, FreeBSD, UnixWare, etc.,
       and is quite flexible.

       The other commonly used Linux loader is 'LoadLin' which is a DOS program
       that has the capability to launch a Linux kernel from the DOS prompt (with
       boot-args) assuming that certain resources are available.  This is good for
       people that want to launch Linux from DOS.

       It is also very useful if you have certain hardware which relies on the
       supplied DOS driver to put the hardware into a known state.  A common
       example is 'SoundBlaster Compatible' sound cards that require the DOS
       driver to twiddle a few mystical registers to put the card into a SB
       compatible mode.  Booting DOS with the supplied driver, and then loading
       Linux from the DOS prompt with loadlin avoids the reset of the card that
       happens if one rebooted instead.

The Argument List

       The kernel command line is parsed into a list of strings (boot arguments)
       separated by spaces.  Most of the boot args take the form of:

              name[=value_1][,value_2]...[,value_10]

       where 'name' is a unique keyword that is used to identify what part of the
       kernel the associated values (if any) are to be given to.  Note the limit
       of 10 is real, as the present code only handles 10 comma separated
       parameters per keyword.  (However, you can reuse the same keyword with up
       to an additional 10 parameters in unusually complicated situations,
       assuming the setup function supports it.)

       Most of the sorting goes on in linux/init/main.c.  First, the kernel checks
       to see if the argument is any of the special arguments 'root=', 'nfsroot=',
       'nfsaddrs=', 'ro', 'rw', 'debug' or 'init'.  The meaning of these special
       arguments is described below.

       Then it walks a list of setup functions (contained in the bootsetups array)
       to see if the specified argument string (such as 'foo') has been associated
       with a setup function ('foo_setup()') for a particular device or part of
       the kernel.  If you passed the kernel the line foo=3,4,5,6 then the kernel
       would search the bootsetups array to see if 'foo' was registered.  If it
       was, then it would call the setup function associated with 'foo'
       (foo_setup()) and hand it the arguments 3, 4, 5 and 6 as given on the
       kernel command line.

       Anything of the form 'foo=bar' that is not accepted as a setup function as
       described above is then interpreted as an environment variable to be set.
       A (useless?) example would be to use 'TERM=vt100' as a boot argument.

       Any remaining arguments that were not picked up by the kernel and were not
       interpreted as environment variables are then passed onto process one,
       which is usually the init program.  The most common argument that is passed
       to the init process is the word 'single' which instructs init to boot the
       computer in single user mode, and not launch all the usual daemons.  Check
       the manual page for the version of init installed on your system to see
       what arguments it accepts.

General Non-device Specific Boot Arguments

       'init=...'
              This sets the initial command to be executed by the kernel.  If this
              is not set, or cannot be found, the kernel will try /sbin/init, then
              /etc/init, then /bin/init, then /bin/sh and panic if all of this
              fails.

       'nfsaddrs=...'
              This sets the nfs boot address to the given string.  This boot
              address is used in case of a net boot.

       'nfsroot=...'
              This sets the nfs root name to the given string.  If this string
              does not begin with '/' or ',' or a digit, then it is prefixed by
              '/tftpboot/'.  This root name is used in case of a net boot.

       'no387'
              (Only when CONFIG_BUGi386 is defined.)  Some i387 coprocessor chips
              have bugs that show up when used in 32 bit protected mode.  For
              example, some of the early ULSI-387 chips would cause solid lockups
              while performing floating-point calculations.  Using the 'no387'
              boot arg causes Linux to ignore the maths coprocessor even if you
              have one.  Of course you must then have your kernel compiled with
              math emulation support!

       'no-hlt'
              (Only when CONFIG_BUGi386 is defined.)  Some of the early i486DX-100
              chips have a problem with the 'hlt' instruction, in that they can't
              reliably return to operating mode after this instruction is used.
              Using the 'no-hlt' instruction tells Linux to just run an infinite
              loop when there is nothing else to do, and to not halt the CPU.
              This allows people with these broken chips to use Linux.

       'root=...'
              This argument tells the kernel what device is to be used as the root
              file system while booting.  The default of this setting is
              determined at compile time, and usually is the value of the root
              device of the system that the kernel was built on.  To override this
              value, and select the second floppy drive as the root device, one
              would use 'root=/dev/fd1'.  (The root device can also be set using
              rdev(8).)

              The root device can be specified symbolically or numerically.  A
              symbolic specification has the form /dev/XXYN, where XX designates
              the device type ('hd' for ST-506 compatible hard disk, with Y in
              'a'-'d'; 'sd' for SCSI compatible disk, with Y in 'a'-'e'; 'ad' for
              Atari ACSI disk, with Y in 'a'-'e', 'ez' for a Syquest EZ135
              parallel port removable drive, with Y='a', 'xd' for XT compatible
              disk, with Y either 'a' or 'b'; 'fd' for floppy disk, with Y the
              floppy drive number--fd0 would be the DOS 'A:' drive, and fd1 would
              be 'B:'), Y the driver letter or number, and N the number (in
              decimal) of the partition on this device (absent in the case of
              floppies).  Recent kernels allow many other types, mostly for CD-
              ROMs: nfs, ram, scd, mcd, cdu535, aztcd, cm206cd, gscd, sbpcd,
              sonycd, bpcd.  (The type nfs specifies a net boot; ram refers to a
              ram disk.)

              Note that this has nothing to do with the designation of these
              devices on your file system.  The '/dev/' part is purely
              conventional.

              The more awkward and less portable numeric specification of the
              above possible root devices in major/minor format is also accepted.
              (E.g., /dev/sda3 is major 8, minor 3, so you could use 'root=0x803'
              as an alternative.)

       'ro' and 'rw'
              The 'ro' option tells the kernel to mount the root file system as
              'read-only' so that file system consistency check programs (fsck)
              can do their work on a quiescent file system.  No processes can
              write to files on the file system in question until it is
              'remounted' as read/write capable, for example, by 'mount -w -n -o
              remount /'.  (See also mount(8).)

              The 'rw' option tells the kernel to mount the root file system
              read/write.  This is the default.

              The choice between read-only and read/write can also be set using
              rdev(8).

       'reserve=...'
              This is used to protect I/O port regions from probes.  The form of
              the command is:

              reserve=[22miobase,extent[,iobase,extent]...[0m

              In some machines it may be necessary to prevent device drivers from
              checking for devices (auto-probing) in a specific region.  This may
              be because of hardware that reacts badly to the probing, or hardware
              that would be mistakenly identified, or merely hardware you don't
              want the kernel to initialize.

              The reserve boot-time argument specifies an I/O port region that
              shouldn't be probed.  A device driver will not probe a reserved
              region, unless another boot argument explicitly specifies that it do
              so.

              For example, the boot line

              reserve=0x300,32  blah=0x300

              keeps all device drivers except the driver for 'blah' from probing
              0x300-0x31f.

       'mem=...'
              The BIOS call defined in the PC specification that returns the
              amount of installed memory was only designed to be able to report up
              to 64MB.  Linux uses this BIOS call at boot to determine how much
              memory is installed.  If you have more than 64MB of RAM installed,
              you can use this boot arg to tell Linux how much memory you have.
              The value is in decimal or hexadecimal (prefix 0x), and the suffixes
              'k' (times 1024) or 'M' (times 1048576) can be used.  Here is a
              quote from Linus on usage of the 'mem=' parameter.

                   The kernel will accept any 'mem=xx' parameter you give it, and
                   if it turns out that you lied to it, it will crash horribly
                   sooner or later.  The parameter indicates the highest
                   addressable RAM address, so 'mem=0x1000000' means you have 16MB
                   of memory, for example.  For a 96MB machine this would be
                   'mem=0x6000000'.

                   NOTE: some machines might use the top of memory for BIOS
                   caching or whatever, so you might not actually have up to the
                   full 96MB addressable.  The reverse is also true: some chipsets
                   will map the physical memory that is covered by the BIOS area
                   into the area just past the top of memory, so the top-of-mem
                   might actually be 96MB + 384kB for example.  If you tell linux
                   that it has more memory than it actually does have, bad things
                   will happen: maybe not at once, but surely eventually.

              You can also use the boot argument 'mem=nopentium' to turn off 4 MB
              page tables on kernels configured for IA32 systems with a pentium or
              newer CPU.

       'panic=N'
              By default the kernel will not reboot after a panic, but this option
              will cause a kernel reboot after N seconds (if N is greater than
              zero).  This panic timeout can also be set by "echo N >
              /proc/sys/kernel/panic".

       'reboot=[warm|cold][,[bios|hard]]'
              (Only when CONFIG_BUGi386 is defined.)  Since 2.0.22 a reboot is by
              default a cold reboot.  One asks for the old default with
              'reboot=warm'.  (A cold reboot may be required to reset certain
              hardware, but might destroy not yet written data in a disk cache.  A
              warm reboot may be faster.)  By default a reboot is hard, by asking
              the keyboard controller to pulse the reset line low, but there is at
              least one type of motherboard where that doesn't work.  The option
              'reboot=bios' will instead jump through the BIOS.

       'nosmp' and 'maxcpus=N'
              (Only when __SMP__ is defined.)  A command-line option of 'nosmp' or
              'maxcpus=0' will disable SMP activation entirely; an option
              'maxcpus=N' limits the maximum number of CPUs activated in SMP mode
              to N.

Boot Arguments for Use by Kernel Developers

       'debug'
              Kernel messages are handed off to the kernel log daemon klogd so
              that they may be logged to disk.  Messages with a priority above
              console_loglevel are also printed on the console.  (For these
              levels, see <linux/kernel.h>.)  By default this variable is set to
              log anything more important than debug messages.  This boot argument
              will cause the kernel to also print the messages of DEBUG priority.
              The console loglevel can also be set at run time via an option to
              klogd.  See klogd(8).

       'profile=N'
              It is possible to enable a kernel profiling function, if one wishes
              to find out where the kernel is spending its CPU cycles.  Profiling
              is enabled by setting the variable prof_shift to a nonzero value.
              This is done either by specifying CONFIG_PROFILE at compile time, or
              by giving the 'profile=' option.  Now the value that prof_shift gets
              will be N, when given, or CONFIG_PROFILE_SHIFT, when that is given,
              or 2, the default.  The significance of this variable is that it
              gives the granularity of the profiling: each clock tick, if the
              system was executing kernel code, a counter is incremented:

              profile[address >> prof_shift]++;

              The raw profiling information can be read from /proc/profile.
              Probably you'll want to use a tool such as readprofile.c to digest
              it.  Writing to /proc/profile will clear the counters.

       'swap=N1,N2,N3,N4,N5,N6,N7,N8'
              Set the eight parameters max_page_age, page_advance, page_decline,
              page_initial_age, age_cluster_fract, age_cluster_min,
              pageout_weight, bufferout_weight that control the kernel swap
              algorithm.  For kernel tuners only.

       'buff=N1,N2,N3,N4,N5,N6'
              Set the six parameters max_buff_age, buff_advance, buff_decline,
              buff_initial_age, bufferout_weight, buffermem_grace that control
              kernel buffer memory management.  For kernel tuners only.

Boot Arguments for Ramdisk Use

       (Only if the kernel was compiled with CONFIG_BLK_DEV_RAM.)  In general it
       is a bad idea to use a ramdisk under Linux--the system will use available
       memory more efficiently itself.  But while booting (or while constructing
       boot floppies) it is often useful to load the floppy contents into a
       ramdisk.  One might also have a system in which first some modules (for
       file system or hardware) must be loaded before the main disk can be
       accessed.

       In Linux 1.3.48, ramdisk handling was changed drastically.  Earlier, the
       memory was allocated statically, and there was a 'ramdisk=N' parameter to
       tell its size.  (This could also be set in the kernel image at compile
       time, or by use of rdev(8).)  These days ram disks use the buffer cache,
       and grow dynamically.  For a lot of information (e.g., how to use rdev(8)
       in conjunction with the new ramdisk setup), see
       /usr/src/linux/Documentation/ramdisk.txt.

       There are four parameters, two boolean and two integral.

       'load_ramdisk=N'
              If N=1, do load a ramdisk.  If N=0, do not load a ramdisk.  (This is
              the default.)

       'prompt_ramdisk=N'
              If N=1, do prompt for insertion of the floppy.  (This is the
              default.)  If N=0, do not prompt.  (Thus, this parameter is never
              needed.)

       'ramdisk_size=N' or (obsolete) 'ramdisk=N'
              Set the maximal size of the ramdisk(s) to N kB.  The default is 4096
              (4 MB).

       'ramdisk_start=N'
              Sets the starting block number (the offset on the floppy where the
              ramdisk starts) to N.  This is needed in case the ramdisk follows a
              kernel image.

       'noinitrd'
              (Only if the kernel was compiled with CONFIG_BLK_DEV_RAM and
              CONFIG_BLK_DEV_INITRD.)  These days it is possible to compile the
              kernel to use initrd.  When this feature is enabled, the boot
              process will load the kernel and an initial ramdisk; then the kernel
              converts initrd into a "normal" ramdisk, which is mounted read-write
              as root device; then /linuxrc is executed; afterward the "real" root
              file system is mounted, and the initrd file system is moved over to
              /initrd; finally the usual boot sequence (e.g., invocation of
              /sbin/init) is performed.

              For a detailed description of the initrd feature, see
              /usr/src/linux/Documentation/initrd.txt.

              The 'noinitrd' option tells the kernel that although it was compiled
              for operation with initrd, it should not go through the above steps,
              but leave the initrd data under /dev/initrd.  (This device can be
              used only once: the data is freed as soon as the last process that
              used it has closed /dev/initrd.)

Boot Arguments for SCSI Devices

       General notation for this section:

       iobase -- the first I/O port that the SCSI host occupies.  These are
       specified in hexadecimal notation, and usually lie in the range from 0x200
       to 0x3ff.

       irq -- the hardware interrupt that the card is configured to use.  Valid
       values will be dependent on the card in question, but will usually be 5, 7,
       9, 10, 11, 12, and 15.  The other values are usually used for common
       peripherals like IDE hard disks, floppies, serial ports, and so on.

       scsi-id -- the ID that the host adapter uses to identify itself on the SCSI
       bus.  Only some host adapters allow you to change this value, as most have
       it permanently specified internally.  The usual default value is 7, but the
       Seagate and Future Domain TMC-950 boards use 6.

       parity -- whether the SCSI host adapter expects the attached devices to
       supply a parity value with all information exchanges.  Specifying a one
       indicates parity checking is enabled, and a zero disables parity checking.
       Again, not all adapters will support selection of parity behavior as a boot
       argument.

       'max_scsi_luns=...'
              A SCSI device can have a number of 'subdevices' contained within
              itself.  The most common example is one of the new SCSI CD-ROMs that
              handle more than one disk at a time.  Each CD is addressed as a
              'Logical Unit Number' (LUN) of that particular device.  But most
              devices, such as hard disks, tape drives and such are only one
              device, and will be assigned to LUN zero.

              Some poorly designed SCSI devices cannot handle being probed for
              LUNs not equal to zero.  Therefore, if the compile-time flag
              CONFIG_SCSI_MULTI_LUN is not set, newer kernels will by default only
              probe LUN zero.

              To specify the number of probed LUNs at boot, one enters
              'max_scsi_luns=n' as a boot arg, where n is a number between one and
              eight.  To avoid problems as described above, one would use n=1 to
              avoid upsetting such broken devices.

       SCSI tape configuration
              Some boot time configuration of the SCSI tape driver can be achieved
              by using the following:

              st=[22mbuf_size[,write_threshold[,max_bufs]][0m

              The first two numbers are specified in units of kB.  The default
              buf_size is 32kB, and the maximum size that can be specified is a
              ridiculous 16384kB.  The write_threshold is the value at which the
              buffer is committed to tape, with a default value of 30kB.  The
              maximum number of buffers varies with the number of drives detected,
              and has a default of two.  An example usage would be:

              st=32,30,2

              Full details can be found in the file Documentation/scsi/st.txt (or
              drivers/scsi/README.st for older kernels) in the Linux kernel
              source.

       Adaptec aha151x, aha152x, aic6260, aic6360, SB16-SCSI configuration
              The aha numbers refer to cards and the aic numbers refer to the
              actual SCSI chip on these type of cards, including the
              Soundblaster-16 SCSI.

              The probe code for these SCSI hosts looks for an installed BIOS, and
              if none is present, the probe will not find your card.  Then you
              will have to use a boot arg of the form:

              aha152x=[22miobase[,irq[,scsi-id[,reconnect[,parity]]]][0m

              If the driver was compiled with debugging enabled, a sixth value can
              be specified to set the debug level.

              All the parameters are as described at the top of this section, and
              the reconnect value will allow device disconnect/reconnect if a
              nonzero value is used.  An example usage is as follows:

              aha152x=0x340,11,7,1

              Note that the parameters must be specified in order, meaning that if
              you want to specify a parity setting, then you will have to specify
              an iobase, irq, scsi-id and reconnect value as well.

       Adaptec aha154x configuration
              The aha1542 series cards have an i82077 floppy controller onboard,
              while the aha1540 series cards do not.  These are busmastering
              cards, and have parameters to set the "fairness" that is used to
              share the bus with other devices.  The boot arg looks like the
              following.

              aha1542=[22miobase[,buson,busoff[,dmaspeed]][0m

              Valid iobase values are usually one of: 0x130, 0x134, 0x230, 0x234,
              0x330, 0x334.  Clone cards may permit other values.

              The buson, busoff values refer to the number of microseconds that
              the card dominates the ISA bus.  The defaults are 11us on, and 4us
              off, so that other cards (such as an ISA LANCE Ethernet card) have a
              chance to get access to the ISA bus.

              The dmaspeed value refers to the rate (in MB/s) at which the DMA
              (Direct Memory Access) transfers proceed.  The default is 5MB/s.
              Newer revision cards allow you to select this value as part of the
              soft-configuration, older cards use jumpers.  You can use values up
              to 10MB/s assuming that your motherboard is capable of handling it.
              Experiment with caution if using values over 5MB/s.

       Adaptec aha274x, aha284x, aic7xxx configuration
              These boards can accept an argument of the form:

              aic7xxx=[22mextended,no_reset[0m

              The extended value, if nonzero, indicates that extended translation
              for large disks is enabled.  The no_reset value, if nonzero, tells
              the driver not to reset the SCSI bus when setting up the host
              adapter at boot.

       AdvanSys SCSI Hosts configuration ('advansys=')
              The AdvanSys driver can accept up to four i/o addresses that will be
              probed for an AdvanSys SCSI card.  Note that these values (if used)
              do not effect EISA or PCI probing in any way.  They are only used
              for probing ISA and VLB cards.  In addition, if the driver has been
              compiled with debugging enabled, the level of debugging output can
              be set by adding an 0xdeb[0-f] parameter.  The 0-f allows setting
              the level of the debugging messages to any of 16 levels of
              verbosity.

       AM53C974

              AM53C974=[22mhost-scsi-id,target-scsi-id,max-rate,max-offset[0m

       BusLogic SCSI Hosts configuration ('BusLogic=')

              BusLogic=[22mN1,N2,N3,N4,N5,S1,S2,...[0m

              For an extensive discussion of the BusLogic command line parameters,
              see /usr/src/linux/drivers/scsi/BusLogic.c (lines 3149-3270 in the
              kernel version I am looking at).  The text below is a very much
              abbreviated extract.

              The parameters N1-N5 are integers.  The parameters S1,... are
              strings.  N1 is the I/O Address at which the Host Adapter is
              located.  N2 is the Tagged Queue Depth to use for Target Devices
              that support Tagged Queuing.  N3 is the Bus Settle Time in seconds.
              This is the amount of time to wait between a Host Adapter Hard Reset
              which initiates a SCSI Bus Reset and issuing any SCSI Commands.  N4
              is the Local Options (for one Host Adapter).  N5 is the Global
              Options (for all Host Adapters).

              The string options are used to provide control over Tagged Queuing
              (TQ:Default, TQ:Enable, TQ:Disable, TQ:<Per-Target-Spec>), over
              Error Recovery (ER:Default, ER:HardReset, ER:BusDeviceReset,
              ER:None, ER:<Per-Target-Spec>), and over Host Adapter Probing
              (NoProbe, NoProbeISA, NoSortPCI).

       EATA/DMA configuration
              The default list of i/o ports to be probed can be changed by

              eata=iobase,iobase,....

       Future Domain TMC-16x0 configuration

              fdomain=[22miobase,irq[,adapter_id][0m

       Great Valley Products (GVP) SCSI controller configuration

              gvp11=[22mdma_transfer_bitmask[0m

       Future Domain TMC-8xx, TMC-950 configuration

              tmc8xx=[22mmem_base,irq[0m

              The mem_base value is the value of the memory mapped I/O region that
              the card uses.  This will usually be one of the following values:
              0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000.

       IN2000 configuration

              in2000=[22mS[0m

              where S is a comma-separated string of items keyword[:value].
              Recognized keywords (possibly with value) are: ioport:addr, noreset,
              nosync:x, period:ns, disconnect:x, debug:x, proc:x.  For the
              function of these parameters, see
              /usr/src/linux/drivers/scsi/in2000.c.

       NCR5380 and NCR53C400 configuration
              The boot arg is of the form

              ncr5380=[22miobase,irq,dma[0m

              or

              ncr53c400=[22miobase,irq[0m

              If the card doesn't use interrupts, then an IRQ value of 255 (0xff)
              will disable interrupts.  An IRQ value of 254 means to autoprobe.
              More details can be found in the file
              Documentation/scsi/g_NCR5380.txt (or drivers/scsi/README.g_NCR5380
              for older kernels) in the Linux kernel source.

       NCR53C8xx configuration

              ncr53c8xx=[22mS[0m

              where S is a comma-separated string of items keyword:value.
              Recognized keywords are: mpar (master_parity), spar (scsi_parity),
              disc (disconnection), specf (special_features), ultra (ultra_scsi),
              fsn (force_sync_nego), tags (default_tags), sync (default_sync),
              verb (verbose), debug (debug), burst (burst_max).  For the function
              of the assigned values, see /usr/src/linux/drivers/scsi/ncr53c8xx.c.

       NCR53c406a configuration

              ncr53c406a=[22miobase[,irq[,fastpio]][0m

              Specify irq = 0 for noninterrupt driven mode.  Set fastpio = 1 for
              fast pio mode, 0 for slow mode.

       Pro Audio Spectrum configuration
              The PAS16 uses a NC5380 SCSI chip, and newer models support
              jumperless configuration.  The boot arg is of the form:

              pas16=[22miobase,irq[0m

              The only difference is that you can specify an IRQ value of 255,
              which will tell the driver to work without using interrupts, albeit
              at a performance loss.  The iobase is usually 0x388.

       Seagate ST-0x configuration
              If your card is not detected at boot time, you will then have to use
              a boot arg of the form:

              st0x=[22mmem_base,irq[0m

              The mem_base value is the value of the memory mapped I/O region that
              the card uses.  This will usually be one of the following values:
              0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000.

       Trantor T128 configuration
              These cards are also based on the NCR5380 chip, and accept the
              following options:

              t128=[22mmem_base,irq[0m

              The valid values for mem_base are as follows: 0xcc000, 0xc8000,
              0xdc000, 0xd8000.

       UltraStor 14F/34F configuration
              The default list of i/o ports to be probed can be changed by

              eata=iobase,iobase,....

       WD7000 configuration

              wd7000=[22mirq,dma,iobase[0m

       Commodore Amiga A2091/590 SCSI controller configuration

              wd33c93=[22mS[0m

              where S is a comma-separated string of options.  Recognized options
              are nosync:bitmask, nodma:x, period:ns, disconnect:x, debug:x,
              clock:x, next.  For details, see
              /usr/src/linux/drivers/scsi/wd33c93.c.

Hard Disks

       IDE Disk/CD-ROM Driver Parameters
              The IDE driver accepts a number of parameters, which range from disk
              geometry specifications, to support for broken controller chips.
              Drive-specific options are specified by using 'hdX=' with X in
              'a'-'h'.

              Non-drive-specific options are specified with the prefix 'hd='.
              Note that using a drive-specific prefix for a non-drive-specific
              option will still work, and the option will just be applied as
              expected.

              Also note that 'hd=' can be used to refer to the next unspecified
              drive in the (a, ..., h) sequence.  For the following discussions,
              the 'hd=' option will be cited for brevity.  See the file
              Documentation/ide.txt (or drivers/block/README.ide for older
              kernels) in the Linux kernel source for more details.

       The 'hd=cyls,heads,sects[,wpcom[,irq]]' options
              These options are used to specify the physical geometry of the disk.
              Only the first three values are required.  The cylinder/head/sectors
              values will be those used by fdisk.  The write precompensation value
              is ignored for IDE disks.  The IRQ value specified will be the IRQ
              used for the interface that the drive resides on, and is not really
              a drive-specific parameter.

       The 'hd=serialize' option
              The dual IDE interface CMD-640 chip is broken as designed such that
              when drives on the secondary interface are used at the same time as
              drives on the primary interface, it will corrupt your data.  Using
              this option tells the driver to make sure that both interfaces are
              never used at the same time.

       The 'hd=dtc2278' option
              This option tells the driver that you have a DTC-2278D IDE
              interface.  The driver then tries to do DTC-specific operations to
              enable the second interface and to enable faster transfer modes.

       The 'hd=noprobe' option
              Do not probe for this drive.  For example,

              hdb=noprobe hdb=1166,7,17

              would disable the probe, but still specify the drive geometry so
              that it would be registered as a valid block device, and hence
              usable.

       The 'hd=nowerr' option
              Some drives apparently have the WRERR_STAT bit stuck on permanently.
              This enables a work-around for these broken devices.

       The 'hd=cdrom' option
              This tells the IDE driver that there is an ATAPI compatible CD-ROM
              attached in place of a normal IDE hard disk.  In most cases the CD-
              ROM is identified automatically, but if it isn't then this may help.

       Standard ST-506 Disk Driver Options ('hd=')
              The standard disk driver can accept geometry arguments for the disks
              similar to the IDE driver.  Note however that it only expects three
              values (C/H/S); any more or any less and it will silently ignore
              you.  Also, it only accepts 'hd=' as an argument, that is, 'hda='
              and so on are not valid here.  The format is as follows:

              hd=cyls,heads,sects

              If there are two disks installed, the above is repeated with the
              geometry parameters of the second disk.

       XT Disk Driver Options ('xd=')
              If you are unfortunate enough to be using one of these old 8 bit
              cards that move data at a whopping 125kB/s then here is the scoop.
              If the card is not recognized, you will have to use a boot arg of
              the form:

              xd=type,irq,iobase,dma_chan

              The type value specifies the particular manufacturer of the card,
              overriding autodetection.  For the types to use, consult the
              drivers/block/xd.c source file of the kernel you are using.  The
              type is an index in the list xd_sigs and in the course of time types
              have been added to or deleted from the middle of the list, changing
              all type numbers.  Today (Linux 2.5.0) the types are 0=generic;
              1=DTC 5150cx; 2,3=DTC 5150x; 4,5=Western Digital; 6,7,8=Seagate;
              9=Omti; 10=XEBEC, and where here several types are given with the
              same designation, they are equivalent.

              The xd_setup() function does no checking on the values, and assumes
              that you entered all four values.  Don't disappoint it.  Here is an
              example usage for a WD1002 controller with the BIOS
              disabled/removed, using the 'default' XT controller parameters:

              xd=2,5,0x320,3

       Syquest's EZ* removable disks

              ez=[22miobase[,irq[,rep[,nybble]]][0m

IBM MCA Bus Devices

       See also /usr/src/linux/Documentation/mca.txt.

       PS/2 ESDI hard disks
              It is possible to specify the desired geometry at boot time:

              ed=[22mcyls,heads,sectors.[0m

              For a ThinkPad-720, add the option

              tp720=1.

       IBM Microchannel SCSI Subsystem configuration

              ibmmcascsi=[22mN[0m

              where N is the pun (SCSI ID) of the subsystem.

       The Aztech Interface
              The syntax for this type of card is:

              aztcd=iobase[,magic_number]

              If you set the magic_number to 0x79 then the driver will try and run
              anyway in the event of an unknown firmware version.  All other
              values are ignored.

       Parallel port CD-ROM drives
              Syntax:

              pcd.driveN=prt,pro,uni,mod,slv,dly
              pcd.nice=nice

              where 'port' is the base address, 'pro' is the protocol number,
              'uni' is the unit selector (for chained devices), 'mod' is the mode
              (or -1 to choose the best automatically), 'slv' is 1 if it should be
              a slave, and 'dly' is a small integer for slowing down port
              accesses.  The 'nice' parameter controls the driver's use of idle
              CPU time, at the expense of some speed.

       The CDU-31A and CDU-33A Sony Interface
              This CD-ROM interface is found on some of the Pro Audio Spectrum
              sound cards, and other Sony supplied interface cards.  The syntax is
              as follows:

              cdu31a=iobase,[irq[,is_pas_card]]

              Specifying an IRQ value of zero tells the driver that hardware
              interrupts aren't supported (as on some PAS cards).  If your card
              supports interrupts, you should use them as it cuts down on the CPU
              usage of the driver.

              The is_pas_card should be entered as 'PAS' if using a Pro Audio
              Spectrum card, and otherwise it should not be specified at all.

       The CDU-535 Sony Interface
              The syntax for this CD-ROM interface is:

              sonycd535=iobase[,irq]

              A zero can be used for the I/O base as a 'placeholder' if one wishes
              to specify an IRQ value.

       The GoldStar Interface
              The syntax for this CD-ROM interface is:

              gscd=iobase

       The ISP16 CD-ROM Interface
              Syntax:

              isp16=[iobase[,irq[,dma[,type]]]]

              (three integers and a string).  If the type is given as 'noisp16',
              the interface will not be configured.  Other recognized types are:
              'Sanyo", 'Sony', 'Panasonic' and 'Mitsumi'.

       The Mitsumi Standard Interface
              The syntax for this CD-ROM interface is:

              mcd=iobase,[irq[,wait_value]]

              The wait_value is used as an internal timeout value for people who
              are having problems with their drive, and may or may not be
              implemented depending on a compile-time #define.  The Mitsumi FX400
              is an IDE/ATAPI CD-ROM player and does not use the mcd driver.

       The Mitsumi XA/MultiSession Interface
              This is for the same hardware as above, but the driver has extended
              features.  Syntax:

              mcdx=iobase[,irq]

       The Optics Storage Interface
              The syntax for this type of card is:

              optcd=iobase

       The Phillips CM206 Interface
              The syntax for this type of card is:

              cm206=[iobase][,irq]

              The driver assumes numbers between 3 and 11 are IRQ values, and
              numbers between 0x300 and 0x370 are I/O ports, so you can specify
              one, or both numbers, in any order.  It also accepts 'cm206=auto' to
              enable autoprobing.

       The Sanyo Interface
              The syntax for this type of card is:

              sjcd=iobase[,irq[,dma_channel]]

       The SoundBlaster Pro Interface
              The syntax for this type of card is:

              sbpcd=iobase,type

              where type is one of the following (case sensitive) strings:
              'SoundBlaster', 'LaserMate', or 'SPEA'.  The I/O base is that of the
              CD-ROM interface, and not that of the sound portion of the card.

Ethernet Devices

       Different drivers make use of different parameters, but they all at least
       share having an IRQ, an I/O port base value, and a name.  In its most
       generic form, it looks something like this:

              ether=irq,iobase[,param_1[,...param_8]],name

              The first nonnumeric argument is taken as the name.  The param_n
              values (if applicable) usually have different meanings for each
              different card/driver.  Typical param_n values are used to specify
              things like shared memory address, interface selection, DMA channel
              and the like.

              The most common use of this parameter is to force probing for a
              second ethercard, as the default is to only probe for one.  This can
              be accomplished with a simple:

              ether=0,0,eth1

              Note that the values of zero for the IRQ and I/O base in the above
              example tell the driver(s) to autoprobe.

              The Ethernet-HowTo has extensive documentation on using multiple
              cards and on the card/driver-specific implementation of the param_n
              values where used.  Interested readers should refer to the section
              in that document on their particular card.

The Floppy Disk Driver

       There are many floppy driver options, and they are all listed in
       Documentation/floppy.txt (or drivers/block/README.fd for older kernels) in
       the Linux kernel source.  This information is taken directly from that
       file.

       floppy=mask,allowed_drive_mask
              Sets the bit mask of allowed drives to mask.  By default, only units
              0 and 1 of each floppy controller are allowed.  This is done because
              certain nonstandard hardware (ASUS PCI motherboards) mess up the
              keyboard when accessing units 2 or 3.  This option is somewhat
              obsoleted by the cmos option.

       floppy=all_drives
              Sets the bit mask of allowed drives to all drives.  Use this if you
              have more than two drives connected to a floppy controller.

       floppy=asus_pci
              Sets the bit mask to allow only units 0 and 1.  (The default)

       floppy=daring
              Tells the floppy driver that you have a well behaved floppy
              controller.  This allows more efficient and smoother operation, but
              may fail on certain controllers.  This may speed up certain
              operations.

       floppy=0,daring
              Tells the floppy driver that your floppy controller should be used
              with caution.

       floppy=one_fdc
              Tells the floppy driver that you have only floppy controller
              (default)

       floppy=two_fdc or floppy=address,two_fdc
              Tells the floppy driver that you have two floppy controllers.  The
              second floppy controller is assumed to be at address.  If address is
              not given, 0x370 is assumed.

       floppy=thinkpad
              Tells the floppy driver that you have a Thinkpad.  Thinkpads use an
              inverted convention for the disk change line.

       floppy=0,thinkpad
              Tells the floppy driver that you don't have a Thinkpad.

       floppy=drive,type,cmos
              Sets the cmos type of drive to type.  Additionally, this drive is
              allowed in the bit mask.  This is useful if you have more than two
              floppy drives (only two can be described in the physical cmos), or
              if your BIOS uses nonstandard CMOS types.  Setting the CMOS to 0 for
              the first two drives (default) makes the floppy driver read the
              physical cmos for those drives.

       floppy=unexpected_interrupts
              Print a warning message when an unexpected interrupt is received
              (default behavior)

       floppy=no_unexpected_interrupts or floppy=L40SX
              Don't print a message when an unexpected interrupt is received.
              This is needed on IBM L40SX laptops in certain video modes.  (There
              seems to be an interaction between video and floppy.  The unexpected
              interrupts only affect performance, and can safely be ignored.)

The Sound Driver

       The sound driver can also accept boot args to override the compiled in
       values.  This is not recommended, as it is rather complex.  It is described
       in the Linux kernel source file Documentation/sound/oss/README.OSS
       (drivers/sound/Readme.linux in older kernel versions).  It accepts a boot
       arg of the form:

              sound=device1[,device2[,device3...[,device10]]]

              where each deviceN value is of the following format 0xTaaaId and the
              bytes are used as follows:

              T - device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16,
              7=SB16-MPU401

              aaa - I/O address in hex.

              I - interrupt line in hex (i.e 10=a, 11=b, ...)

              d - DMA channel.

              As you can see it gets pretty messy, and you are better off to
              compile in your own personal values as recommended.  Using a boot
              arg of 'sound=0' will disable the sound driver entirely.

ISDN Drivers

       The ICN ISDN driver
              Syntax:

              icn=iobase,membase,icn_id1,icn_id2

              where icn_id1,icn_id2 are two strings used to identify the card in
              kernel messages.

       The PCBIT ISDN driver
              Syntax:

              pcbit=membase1,irq1[,membase2,irq2]

              where membaseN is the shared memory base of the N'th card, and irqN
              is the interrupt setting of the N'th card.  The default is IRQ 5 and
              membase 0xD0000.

       The Teles ISDN driver
              Syntax:

              teles=iobase,irq,membase,protocol,teles_id

              where iobase is the i/o port address of the card, membase is the
              shared memory base address of the card, irq is the interrupt channel
              the card uses, and teles_id is the unique ASCII string identifier.

Serial Port Drivers

       The RISCom/8 Multiport Serial Driver ('riscom8=')
              Syntax:

              riscom=iobase1[,iobase2[,iobase3[,iobase4]]]

              More details can be found in
              /usr/src/linux/Documentation/riscom8.txt.

       The DigiBoard Driver ('digi=')
              If this option is used, it should have precisely six parameters.
              Syntax:

              digi=status,type,altpin,numports,iobase,membase

              The parameters maybe given as integers, or as strings.  If strings
              are used, then iobase and membase should be given in hexadecimal.
              The integer arguments (fewer may be given) are in order: status
              (Enable(1) or Disable(0) this card), type (PC/Xi(0), PC/Xe(1),
              PC/Xeve(2), PC/Xem(3)), altpin (Enable(1) or Disable(0) alternate
              pin arrangement), numports (number of ports on this card), iobase
              (I/O Port where card is configured (in HEX)), membase (base of
              memory window (in HEX)).  Thus, the following two boot prompt
              arguments are equivalent:

              digi=E,PC/Xi,D,16,200,D0000
              digi=1,0,0,16,0x200,851968

              More details can be found in
              /usr/src/linux/Documentation/digiboard.txt.

       The Baycom Serial/Parallel Radio Modem
              Syntax:

              baycom=iobase,irq,modem

              There are precisely 3 parameters; for several cards, give several
              'baycom=' commands.  The modem parameter is a string that can take
              one of the values ser12, ser12*, par96, par96*.  Here the * denotes
              that software DCD is to be used, and ser12/par96 chooses between the
              supported modem types.  For more details, see the file
              Documentation/networking/baycom.txt (or drivers/net/README.baycom
              for older kernels) in the Linux kernel source.

       Soundcard radio modem driver
              Syntax:

              soundmodem=iobase,irq,dma[,dma2[,serio[,pario]]],0,mode

              All parameters except the last are integers; the dummy 0 is required
              because of a bug in the setup code.  The mode parameter is a string
              with syntax hw:modem, where hw is one of sbc, wss, wssfdx and modem
              is one of afsk1200, fsk9600.

The Line Printer Driver

       'lp='  Syntax:

              lp=0
              lp=auto
              lp=reset
              lp=port[,port...]

              You can tell the printer driver what ports to use and what ports not
              to use.  The latter comes in handy if you don't want the printer
              driver to claim all available parallel ports, so that other drivers
              (e.g., PLIP, PPA) can use them instead.

              The format of the argument is multiple port names.  For example,
              lp=none,parport0 would use the first parallel port for lp1, and
              disable lp0.  To disable the printer driver entirely, one can use
              lp=0.

       WDT500/501 driver
              Syntax:

              wdt=io,irq

Mouse Drivers

       'bmouse=irq'
              The busmouse driver only accepts one parameter, that being the
              hardware IRQ value to be used.

       'msmouse=irq'
              And precisely the same is true for the msmouse driver.

       ATARI mouse setup

              atamouse=threshold[,y-threshold]

              If only one argument is given, it is used for both x-threshold and
              y-threshold.  Otherwise, the first argument is the x-threshold, and
              the second the y-threshold.  These values must lie between 1 and 20
              (inclusive); the default is 2.

Video Hardware

       'no-scroll'
              This option tells the console driver not to use hardware scroll
              (where a scroll is effected by moving the screen origin in video
              memory, instead of moving the data).  It is required by certain
              Braille machines.

SEE ALSO top

       lilo.conf(5), klogd(8), lilo(8), mount(8), rdev(8)

       Large parts of this man page have been derived from the Boot Parameter
       HOWTO (version 1.0.1) written by Paul Gortmaker.  More information may be
       found in this (or a more recent) HOWTO.  An up-to-date source of
       information is /usr/src/linux/Documentation/kernel-parameters.txt.

COLOPHON top

       This page is part of release 3.45 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-12-16                        BOOTPARAM(7)


brk(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

BRK(2)                       Linux Programmer's Manual                      BRK(2)

NAME top

       brk, sbrk - change data segment size

SYNOPSIS top

       #include <unistd.h>

       int brk(void *addr);

       void *sbrk(intptr_t increment);

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

       brk(), sbrk():
           Since glibc 2.12:
               _BSD_SOURCE || _SVID_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       brk() and sbrk() change the location of the program break, which defines
       the end of the process's data segment (i.e., the program break is the first
       location after the end of the uninitialized data segment).  Increasing the
       program break has the effect of allocating memory to the process;
       decreasing the break deallocates memory.

       brk() sets the end of the data segment to the value specified by addr, when
       that value is reasonable, the system has enough memory, and the process
       does not exceed its maximum data size (see setrlimit(2)).

       sbrk() increments the program's data space by increment bytes.  Calling
       sbrk() with an increment of 0 can be used to find the current location of
       the program break.

RETURN VALUE top

       On success, brk() returns zero.  On error, -1 is returned, and errno is set
       to ENOMEM.  (But see Linux Notes below.)

       On success, sbrk() returns the previous program break.  (If the break was
       increased, then this value is a pointer to the start of the newly allocated
       memory).  On error, (void *) -1 is returned, and errno is set to ENOMEM.

CONFORMING TO top

       4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001.

NOTES top

       Avoid using brk() and sbrk(): the malloc(3) memory allocation package is
       the portable and comfortable way of allocating memory.

       Various systems use various types for the argument of sbrk().  Common are
       int, ssize_t, ptrdiff_t, intptr_t.

Linux Notes

       The return value described above for brk() is the behavior provided by the
       glibc wrapper function for the Linux brk() system call.  (On most other
       implementations, the return value from brk() is the same; this return value
       was also specified in SUSv2.)  However, the actual Linux system call
       returns the new program break on success.  On failure, the system call
       returns the current break.  The glibc wrapper function does some work
       (i.e., checks whether the new break is less than addr) to provide the 0 and
       -1 return values described above.

       On Linux, sbrk() is implemented as a library function that uses the brk()
       system call, and does some internal bookkeeping so that it can return the
       old break value.

SEE ALSO top

       execve(2), getrlimit(2), end(3), malloc(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                              BRK(2)


bsd_signal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

BSD_SIGNAL(3)                Linux Programmer's Manual               BSD_SIGNAL(3)

NAME top

       bsd_signal - signal handling with BSD semantics

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <signal.h>

       typedef void (*sighandler_t)(int);

       sighandler_t bsd_signal(int signum, sighandler_t handler);

DESCRIPTION top

       The bsd_signal() function takes the same arguments, and performs the same
       task, as signal(2).

       The difference between the two is that bsd_signal() is guaranteed to
       provide reliable signal semantics, that is: a) the disposition of the
       signal is not reset to the default when the handler is invoked; b) delivery
       of further instances of the signal is blocked while the signal handler is
       executing; and c) if the handler interrupts a blocking system call, then
       the system call is automatically restarted.  A portable application cannot
       rely on signal(2) to provide these guarantees.

RETURN VALUE top

       The bsd_signal() function returns the previous value of the signal handler,
       or SIG_ERR on error.

ERRORS top

       As for signal(2).

CONFORMING TO top

       4.2BSD, POSIX.1-2001.  POSIX.1-2008 removes the specification of
       bsd_signal(), recommending the use of sigaction(2) instead.

NOTES top

       Use of bsd_signal() should be avoided; use sigaction(2) instead.

       On modern Linux systems, bsd_signal() and signal(2) are equivalent.  But on
       older systems, signal(2) provided unreliable signal semantics; see
       signal(2) for details.

       The use of sighandler_t is a GNU extension; this type is only defined if
       the _GNU_SOURCE feature test macro is defined.

SEE ALSO top

       sigaction(2), signal(2), sysv_signal(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-03-15                       BSD_SIGNAL(3)


bsearch(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

BSEARCH(3)                   Linux Programmer's Manual                  BSEARCH(3)

NAME top

       bsearch - binary search of a sorted array

SYNOPSIS top

       #include <stdlib.h>

       void *bsearch(const void *key, const void *base,
                     size_t nmemb, size_t size,
                     int (*compar)(const void *, const void *));

DESCRIPTION top

       The bsearch() function searches an array of nmemb objects, the initial
       member of which is pointed to by base, for a member that matches the object
       pointed to by key.  The size of each member of the array is specified by
       size.

       The contents of the array should be in ascending sorted order according to
       the comparison function referenced by compar.  The compar routine is
       expected to have two arguments which point to the key object and to an
       array member, in that order, and should return an integer less than, equal
       to, or greater than zero if the key object is found, respectively, to be
       less than, to match, or be greater than the array member.

RETURN VALUE top

       The bsearch() function returns a pointer to a matching member of the array,
       or NULL if no match is found.  If there are multiple elements that match
       the key, the element returned is unspecified.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001, C89, C99.

EXAMPLE top

       The example below first sorts an array of structures using qsort(3), then
       retrieves desired elements using bsearch().

       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       struct mi {
           int nr;
           char *name;
       } months[] = {
           { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" },
           { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" },
           { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" }
       };

       #define nr_of_months (sizeof(months)/sizeof(months[0]))

       static int
       compmi(const void *m1, const void *m2)
       {
           struct mi *mi1 = (struct mi *) m1;
           struct mi *mi2 = (struct mi *) m2;
           return strcmp(mi1->name, mi2->name);
       }

       int
       main(int argc, char **argv)
       {
           int i;

           qsort(months, nr_of_months, sizeof(struct mi), compmi);
           for (i = 1; i < argc; i++) {
               struct mi key, *res;
               key.name = argv[i];
               res = bsearch(&key, months, nr_of_months,
                             sizeof(struct mi), compmi);
               if (res == NULL)
                   printf("'%s': unknown month\n", argv[i]);
               else
                   printf("%s: month #%d\n", res->name, res->nr);
           }
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       hsearch(3), lsearch(3), qsort(3), tsearch(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2003-11-01                          BSEARCH(3)


bstring(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

BSTRING(3)                   Linux Programmer's Manual                  BSTRING(3)

NAME top

       bcmp,  bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, mem-
       move, memset - byte string operations

SYNOPSIS top

       #include <string.h>

       int bcmp(const void *s1, const void *s2, int n);

       void bcopy(const void *src, void *dest, int n);

       void bzero(void *s, int n);

       void *memccpy(void *dest, const void *src, int c, size_t n);

       void *memchr(const void *s, int c, size_t n);

       int memcmp(const void *s1, const void *s2, size_t n);

       void *memcpy(void *dest, const void *src, size_t n);

       void *memfrob(void *s, size_t n);

       void *memmem(const void *needle, size_t needlelen,
                    const void *haystack, size_t haystacklen);

       void *memmove(void *dest, const void *src, size_t n);

       void *memset(void *s, int c, size_t n);

DESCRIPTION top

       The byte string functions perform operations on strings (byte arrays) that
       are not necessarily null-terminated.  See the individual man pages for
       descriptions of each function.

NOTES top

       The functions bcmp(), bcopy() and bzero() are obsolete.  Use memcmp(),
       memcpy() and memset() instead.

SEE ALSO top

       bcmp(3), bcopy(3), bzero(3), memccpy(3), memchr(3), memcmp(3), memcpy(3),
       memfrob(3), memmem(3), memmove(3), memset(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2002-01-20                          BSTRING(3)


btowc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

BTOWC(3)                     Linux Programmer's Manual                    BTOWC(3)

NAME top

       btowc - convert single byte to wide character

SYNOPSIS top

       #include <wchar.h>

       wint_t btowc(int c);

DESCRIPTION top

       The btowc() function converts c, interpreted as a multibyte sequence of
       length 1, starting in the initial shift state, to a wide character and
       returns it.  If c is EOF or not a valid multibyte sequence of length 1, the
       btowc() function returns WEOF.

RETURN VALUE top

       The btowc() function returns the wide character converted from the single
       byte c.  If c is EOF or not a valid multibyte sequence of length 1, it
       returns WEOF.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The behavior of btowc() depends on the LC_CTYPE category of the current
       locale.

       This function should never be used.  It does not work for encodings which
       have state, and unnecessarily treats single bytes differently from
       multibyte sequences.  Use either mbtowc(3) or the thread-safe mbrtowc(3)
       instead.

SEE ALSO top

       mbrtowc(3), mbtowc(3), wctob(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-22                            BTOWC(3)


btree(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

BTREE(3)                     Linux Programmer's Manual                    BTREE(3)

NAME top

       btree - btree database access method

SYNOPSIS top

       #include <sys/types.h>
       #include <db.h>

DESCRIPTION top

       Note well: This page documents interfaces provided in glibc up until
       version 2.1.  Since version 2.2, glibc no longer provides these interfaces.
       Probably, you are looking for the APIs provided by the libdb library
       instead.

       The routine dbopen(3) is the library interface to database files.  One of
       the supported file formats is btree files.  The general description of the
       database access methods is in dbopen(3), this manual page describes only
       the btree specific information.

       The btree data structure is a sorted, balanced tree structure storing
       associated key/data pairs.

       The btree access method specific data structure provided to dbopen(3) is
       defined in the <db.h> include file as follows:

           typedef struct {
               unsigned long flags;
               unsigned int  cachesize;
               int           maxkeypage;
               int           minkeypage;
               unsigned int  psize;
               int         (*compare)(const DBT *key1, const DBT *key2);
               size_t      (*prefix)(const DBT *key1, const DBT *key2);
               int           lorder;
           } BTREEINFO;

       The elements of this structure are as follows:

       flags  The flag value is specified by ORing any of the following values:

              R_DUP  Permit duplicate keys in the tree, that is, permit insertion
                     if the key to be inserted already exists in the tree.  The
                     default behavior, as described in dbopen(3), is to overwrite
                     a matching key when inserting a new key or to fail if the
                     R_NOOVERWRITE flag is specified.  The R_DUP flag is
                     overridden by the R_NOOVERWRITE flag, and if the
                     R_NOOVERWRITE flag is specified, attempts to insert duplicate
                     keys into the tree will fail.

                     If the database contains duplicate keys, the order of
                     retrieval of key/data pairs is undefined if the get routine
                     is used, however, seq routine calls with the R_CURSOR flag
                     set will always return the logical "first" of any group of
                     duplicate keys.

       cachesize
              A suggested maximum size (in bytes) of the memory cache.  This value
              is only advisory, and the access method will allocate more memory
              rather than fail.  Since every search examines the root page of the
              tree, caching the most recently used pages substantially improves
              access time.  In addition, physical writes are delayed as long as
              possible, so a moderate cache can reduce the number of I/O
              operations significantly.  Obviously, using a cache increases (but
              only increases) the likelihood of corruption or lost data if the
              system crashes while a tree is being modified.  If cachesize is 0
              (no size is specified) a default cache is used.

       maxkeypage
              The maximum number of keys which will be stored on any single page.
              Not currently implemented.

       minkeypage
              The minimum number of keys which will be stored on any single page.
              This value is used to determine which keys will be stored on
              overflow pages, that is, if a key or data item is longer than the
              pagesize divided by the minkeypage value, it will be stored on
              overflow pages instead of in the page itself.  If minkeypage is 0
              (no minimum number of keys is specified) a value of 2 is used.

       psize  Page size is the size (in bytes) of the pages used for nodes in the
              tree.  The minimum page size is 512 bytes and the maximum page size
              is 64K.  If psize is 0 (no page size is specified) a page size is
              chosen based on the underlying file system I/O block size.

       compare
              Compare is the key comparison function.  It must return an integer
              less than, equal to, or greater than zero if the first key argument
              is considered to be respectively less than, equal to, or greater
              than the second key argument.  The same comparison function must be
              used on a given tree every time it is opened.  If compare is NULL
              (no comparison function is specified), the keys are compared
              lexically, with shorter keys considered less than longer keys.

       prefix Prefix is the prefix comparison function.  If specified, this
              routine must return the number of bytes of the second key argument
              which are necessary to determine that it is greater than the first
              key argument.  If the keys are equal, the key length should be
              returned.  Note, the usefulness of this routine is very data-
              dependent, but, in some data sets can produce significantly reduced
              tree sizes and search times.  If prefix is NULL (no prefix function
              is specified), and no comparison function is specified, a default
              lexical comparison routine is used.  If prefix is NULL and a
              comparison routine is specified, no prefix comparison is done.

       lorder The byte order for integers in the stored database metadata.  The
              number should represent the order as an integer; for example, big
              endian order would be the number 4,321.  If lorder is 0 (no order is
              specified) the current host order is used.

       If the file already exists (and the O_TRUNC flag is not specified), the
       values specified for the arguments flags, lorder and psize are ignored in
       favor of the values used when the tree was created.

       Forward sequential scans of a tree are from the least key to the greatest.

       Space freed up by deleting key/data pairs from the tree is never reclaimed,
       although it is normally made available for reuse.  This means that the
       btree storage structure is grow-only.  The only solutions are to avoid
       excessive deletions, or to create a fresh tree periodically from a scan of
       an existing one.

       Searches, insertions, and deletions in a btree will all complete in O lg
       base N where base is the average fill factor.  Often, inserting ordered
       data into btrees results in a low fill factor.  This implementation has
       been modified to make ordered insertion the best case, resulting in a much
       better than normal page fill factor.

ERRORS top

       The btree access method routines may fail and set errno for any of the
       errors specified for the library routine dbopen(3).

BUGS top

       Only big and little endian byte order is supported.

SEE ALSO top

       dbopen(3), hash(3), mpool(3), recno(3)

       The Ubiquitous B-tree, Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979),
       121-138.

       Prefix B-trees, Bayer and Unterauer, ACM Transactions on Database Systems,
       Vol. 2, 1 (March 1977), 11-26.

       The Art of Computer Programming Vol. 3: Sorting and Searching, D.E. Knuth,
       1968, pp 471-480.

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-23                            BTREE(3)


byteorder(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

BYTEORDER(3)                 Linux Programmer's Manual                BYTEORDER(3)

NAME top

       htonl,  htons,  ntohl, ntohs - convert values between host and network byte
       order

SYNOPSIS top

       #include <arpa/inet.h>

       uint32_t htonl(uint32_t hostlong);

       uint16_t htons(uint16_t hostshort);

       uint32_t ntohl(uint32_t netlong);

       uint16_t ntohs(uint16_t netshort);

DESCRIPTION top

       The htonl() function converts the unsigned integer hostlong from host byte
       order to network byte order.

       The htons() function converts the unsigned short integer hostshort from
       host byte order to network byte order.

       The ntohl() function converts the unsigned integer netlong from network
       byte order to host byte order.

       The ntohs() function converts the unsigned short integer netshort from
       network byte order to host byte order.

       On the i386 the host byte order is Least Significant Byte first, whereas
       the network byte order, as used on the Internet, is Most Significant Byte
       first.

CONFORMING TO top

       POSIX.1-2001.

       Some systems require the inclusion of <netinet/in.h> instead of
       <arpa/inet.h>.

SEE ALSO top

       endian(3), gethostbyname(3), getservent(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-01-15                        BYTEORDER(3)


bzero(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

BZERO(3)                     Linux Programmer's Manual                    BZERO(3)

NAME top

       bzero - write zero-valued bytes

SYNOPSIS top

       #include <strings.h>

       void bzero(void *s, size_t n);

DESCRIPTION top

       The bzero() function sets the first n bytes of the area starting at s to
       zero (bytes containing '\0').

RETURN VALUE top

       None.

CONFORMING TO top

       4.3BSD.  This function is deprecated (marked as LEGACY in POSIX.1-2001):
       use memset(3) in new programs.  POSIX.1-2008 removes the specification of
       bzero().

SEE ALSO top

       memset(3), swab(3)

COLOPHON top

       This page is part of release 3.45 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                            BZERO(3)


cabs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CABS(3)                      Linux Programmer's Manual                     CABS(3)

NAME top

       cabs, cabsf, cabsl - absolute value of a complex number

SYNOPSIS top

       #include <complex.h>

       double cabs(double complex z);
       float cabsf(float complex z);
       long double cabsl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The cabs() function returns the absolute value of the complex number z.
       The result is a real number.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

NOTES top

       The function is actually an alias for hypot(a, b) (or, equivalently,
       sqrt(a*a + b*b)).

SEE ALSO top

       abs(3), cimag(3), hypot(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CABS(3)


cacheflush(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | COLOPHON The Linux Programming Interface

CACHEFLUSH(2)                Linux Programmer's Manual               CACHEFLUSH(2)

NAME top

       cacheflush - flush contents of instruction and/or data cache

SYNOPSIS top

       #include <asm/cachectl.h>

       int cacheflush(char *addr, int nbytes, int cache);

DESCRIPTION top

       cacheflush() flushes the contents of the indicated cache(s) for the user
       addresses in the range addr to (addr+nbytes-1).  cache may be one of:

       ICACHE Flush the instruction cache.

       DCACHE Write back to memory and invalidate the affected valid cache lines.

       BCACHE Same as (ICACHE|DCACHE).

RETURN VALUE top

       cacheflush() returns 0 on success or -1 on error.  If errors are detected,
       errno will indicate the error.

ERRORS top

       EFAULT Some or all of the address range addr to (addr+nbytes-1) is not
              accessible.

       EINVAL cache is not one of ICACHE, DCACHE, or BCACHE.

CONFORMING TO top

       This Linux-specific system call is only available on MIPS-based systems.
       It should not be used in programs intended to be portable.

BUGS top

       The current implementation ignores the addr and nbytes arguments.
       Therefore, the whole cache is always flushed.

COLOPHON top

       This page is part of release 3.45 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-05-26                       CACHEFLUSH(2)


cacos(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CACOS(3)                     Linux Programmer's Manual                    CACOS(3)

NAME top

       cacos, cacosf, cacosl - complex arc cosine

SYNOPSIS top

       #include <complex.h>

       double complex cacos(double complex z);
       float complex cacosf(float complex z);
       long double complex cacosl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The cacos() function calculates the complex arc cosine of z.  If
       y = cacos(z), then z = ccos(y).  The real part of y is chosen in the
       interval [0,pi].

       One has:

           cacos(z) = -i * clog(z + i * csqrt(1 - z * z))

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

EXAMPLE top

       /* Link with "-lm" */

       #include <complex.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           double complex z, c, f;
           double complex i = I;

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

           z = atof(argv[1]) + atof(argv[2]) * I;

           c = cacos(z);

           printf("cacos() = %6.3f %6.3f*i\n", creal(c), cimag(c));

           f = -i * clog(z + i * csqrt(1 - z * z));

           printf("formula = %6.3f %6.3f*i\n", creal(f), cimag(f));

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       ccos(3), clog(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2011-09-15                            CACOS(3)


cacosh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CACOSH(3)                    Linux Programmer's Manual                   CACOSH(3)

NAME top

       cacosh, cacoshf, cacoshl - complex arc hyperbolic cosine

SYNOPSIS top

       #include <complex.h>

       double complex cacosh(double complex z);
       float complex cacoshf(float complex z);
       long double complex cacoshl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The cacosh() function calculates the complex arc hyperpolic cosine of z.
       If y = cacosh(z), then z = ccosh(y).  The imaginary part of y is chosen in
       the interval [-pi,pi].  The real part of y is chosen nonnegative.

       One has:

           cacosh(z) = 2 * clog(csqrt((z + 1) / 2) + csqrt((z - 1) / 2))

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

EXAMPLE top

       /* Link with "-lm" */

       #include <complex.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           double complex z, c, f;

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

           z = atof(argv[1]) + atof(argv[2]) * I;

           c = cacosh(z);
           printf("cacosh() = %6.3f %6.3f*i\n", creal(c), cimag(c));

           f = 2 * clog(csqrt((z + 1)/2) + csqrt((z - 1)/2));
           printf("formula  = %6.3f %6.3f*i\n", creal(f2), cimag(f2));

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       acosh(3), cabs(3), ccosh(3), cimag(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2011-09-15                           CACOSH(3)


malloc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC(3)                    Linux Programmer's Manual                   MALLOC(3)

NAME top

       malloc, free, calloc, realloc - allocate and free dynamic memory

SYNOPSIS top

       #include <stdlib.h>

       void *malloc(size_t size);
       void free(void *ptr);
       void *calloc(size_t nmemb, size_t size);
       void *realloc(void *ptr, size_t size);

DESCRIPTION top

       The malloc() function allocates size bytes and returns a pointer to the
       allocated memory.  The memory is not initialized.  If size is 0, then
       malloc() returns either NULL, or a unique pointer value that can later be
       successfully passed to free().

       The free() function frees the memory space pointed to by ptr, which must
       have been returned by a previous call to malloc(), calloc() or realloc().
       Otherwise, or if free(ptr) has already been called before, undefined
       behavior occurs.  If ptr is NULL, no operation is performed.

       The calloc() function allocates memory for an array of nmemb elements of
       size bytes each and returns a pointer to the allocated memory.  The memory
       is set to zero.  If nmemb or size is 0, then calloc() returns either NULL,
       or a unique pointer value that can later be successfully passed to free().

       The realloc() function changes the size of the memory block pointed to by
       ptr to size bytes.  The contents will be unchanged in the range from the
       start of the region up to the minimum of the old and new sizes.  If the new
       size is larger than the old size, the added memory will not be initialized.
       If ptr is NULL, then the call is equivalent to malloc(size), for all values
       of size; if size is equal to zero, and ptr is not NULL, then the call is
       equivalent to free(ptr).  Unless ptr is NULL, it must have been returned by
       an earlier call to malloc(), calloc() or realloc().  If the area pointed to
       was moved, a free(ptr) is done.

RETURN VALUE top

       The malloc() and calloc() functions return a pointer to the allocated
       memory that is suitably aligned for any kind of variable.  On error, these
       functions return NULL.  NULL may also be returned by a successful call to
       malloc() with a size of zero, or by a successful call to calloc() with
       nmemb or size equal to zero.

       The free() function returns no value.

       The realloc() function returns a pointer to the newly allocated memory,
       which is suitably aligned for any kind of variable and may be different
       from ptr, or NULL if the request fails.  If size was equal to 0, either
       NULL or a pointer suitable to be passed to free() is returned.  If
       realloc() fails the original block is left untouched; it is not freed or
       moved.

CONFORMING TO top

       C89, C99.

NOTES top

       By default, Linux follows an optimistic memory allocation strategy.  This
       means that when malloc() returns non-NULL there is no guarantee that the
       memory really is available.  In case it turns out that the system is out of
       memory, one or more processes will be killed by the OOM killer.  For more
       information, see the description of /proc/sys/vm/overcommit_memory and
       /proc/sys/vm/oom_adj in proc(5), and the Linux kernel source file
       Documentation/vm/overcommit-accounting.

       Normally, malloc() allocates memory from the heap, and adjusts the size of
       the heap as required, using sbrk(2).  When allocating blocks of memory
       larger than MMAP_THRESHOLD bytes, the glibc malloc() implementation
       allocates the memory as a private anonymous mapping using mmap(2).
       MMAP_THRESHOLD is 128 kB by default, but is adjustable using mallopt(3).
       Allocations performed using mmap(2) are unaffected by the RLIMIT_DATA
       resource limit (see getrlimit(2)).

       To avoid corruption in multithreaded applications, mutexes are used
       internally to protect the memory-management data structures employed by
       these functions.  In a multithreaded application in which threads
       simultaneously allocate and free memory, there could be contention for
       these mutexes.  To scalably handle memory allocation in multithreaded
       applications, glibc creates additional memory allocation arenas if mutex
       contention is detected.  Each arena is a large region of memory that is
       internally allocated by the system (using brk(2) or mmap(2)), and managed
       with its own mutexes.

       The UNIX 98 standard requires malloc(), calloc(), and realloc() to set
       errno to ENOMEM upon failure.  Glibc assumes that this is done (and the
       glibc versions of these routines do this); if you use a private malloc
       implementation that does not set errno, then certain library routines may
       fail without having a reason in errno.

       Crashes in malloc(), calloc(), realloc(), or free() are almost always
       related to heap corruption, such as overflowing an allocated chunk or
       freeing the same pointer twice.

       Recent versions of Linux libc (later than 5.4.23) and glibc (2.x) include a
       malloc() implementation which is tunable via environment variables.  For
       details, see mallopt(3).

SEE ALSO top

       brk(2), mmap(2), alloca(3), malloc_get_state(3), malloc_info(3),
       malloc_trim(3), malloc_usable_size(3), mallopt(3), mcheck(3), mtrace(3),
       posix_memalign(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                           MALLOC(3)


canonicalize_file_name(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CANONICALIZE_FILE_NAME(3)    Linux Programmer's Manual   CANONICALIZE_FILE_NAME(3)

NAME top

       canonicalize_file_name -  return the canonicalized filename

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <stdlib.h>

       char *canonicalize_file_name(const char *path);

DESCRIPTION top

       The call canonicalize_file_name(path) is equivalent to the call
       realpath(path, NULL).

CONFORMING TO top

       The function is a GNU extension.

SEE ALSO top

       realpath(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2005-07-14           CANONICALIZE_FILE_NAME(3)


capabilities(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CAPABILITIES(7)              Linux Programmer's Manual             CAPABILITIES(7)

NAME top

       capabilities - overview of Linux capabilities

DESCRIPTION top

       For the purpose of performing permission checks, traditional UNIX
       implementations distinguish two categories of processes: privileged
       processes (whose effective user ID is 0, referred to as superuser or root),
       and unprivileged processes (whose effective UID is nonzero).  Privileged
       processes bypass all kernel permission checks, while unprivileged processes
       are subject to full permission checking based on the process's credentials
       (usually: effective UID, effective GID, and supplementary group list).

       Starting with kernel 2.2, Linux divides the privileges traditionally
       associated with superuser into distinct units, known as capabilities, which
       can be independently enabled and disabled.  Capabilities are a per-thread
       attribute.

Capabilities List

       The following list shows the capabilities implemented on Linux, and the
       operations or behaviors that each capability permits:

       CAP_AUDIT_CONTROL (since Linux 2.6.11)
              Enable and disable kernel auditing; change auditing filter rules;
              retrieve auditing status and filtering rules.

       CAP_AUDIT_WRITE (since Linux 2.6.11)
              Write records to kernel auditing log.

       CAP_BLOCK_SUSPEND (since Linux 3.5)
              Employ features that can block system suspend (epoll(7) EPOLLWAKEUP,
              /proc/sys/wake_lock).

       CAP_CHOWN
              Make arbitrary changes to file UIDs and GIDs (see chown(2)).

       CAP_DAC_OVERRIDE
              Bypass file read, write, and execute permission checks.  (DAC is an
              abbreviation of "discretionary access control".)

       CAP_DAC_READ_SEARCH
              Bypass file read permission checks and directory read and execute
              permission checks.

       CAP_FOWNER
              * Bypass permission checks on operations that normally require the
                file system UID of the process to match the UID of the file (e.g.,
                chmod(2), utime(2)), excluding those operations covered by
                CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH;
              * set extended file attributes (see chattr(1)) on arbitrary files;
              * set Access Control Lists (ACLs) on arbitrary files;
              * ignore directory sticky bit on file deletion;
              * specify O_NOATIME for arbitrary files in open(2) and fcntl(2).

       CAP_FSETID
              Don't clear set-user-ID and set-group-ID permission bits when a file
              is modified; set the set-group-ID bit for a file whose GID does not
              match the file system or any of the supplementary GIDs of the
              calling process.

       CAP_IPC_LOCK
              Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)).

       CAP_IPC_OWNER
              Bypass permission checks for operations on System V IPC objects.

       CAP_KILL
              Bypass permission checks for sending signals (see kill(2)).  This
              includes use of the ioctl(2) KDSIGACCEPT operation.

       CAP_LEASE (since Linux 2.4)
              Establish leases on arbitrary files (see fcntl(2)).

       CAP_LINUX_IMMUTABLE
              Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags (see
              chattr(1)).

       CAP_MAC_ADMIN (since Linux 2.6.25)
              Override Mandatory Access Control (MAC).  Implemented for the Smack
              Linux Security Module (LSM).

       CAP_MAC_OVERRIDE (since Linux 2.6.25)
              Allow MAC configuration or state changes.  Implemented for the Smack
              LSM.

       CAP_MKNOD (since Linux 2.4)
              Create special files using mknod(2).

       CAP_NET_ADMIN
              Perform various network-related operations:
              * interface configuration;
              * administration of IP firewall, masquerading, and accounting
              * modify routing tables;
              * bind to any address for transparent proxying;
              * set type-of-service (TOS)
              * clear driver statistics;
              * set promiscuous mode;
              * enabling multicasting;
              * use setsockopt(2) to set the following socket options: SO_DEBUG,
                SO_MARK, SO_PRIORITY (for a priority outside the range 0 to 6),
                SO_RCVBUFFORCE, and SO_SNDBUFFORCE.

       CAP_NET_BIND_SERVICE
              Bind a socket to Internet domain privileged ports (port numbers less
              than 1024).

       CAP_NET_BROADCAST
              (Unused)  Make socket broadcasts, and listen to multicasts.

       CAP_NET_RAW
              * use RAW and PACKET sockets;
              * bind to any address for transparent proxying.

       CAP_SETGID
              Make arbitrary manipulations of process GIDs and supplementary GID
              list; forge GID when passing socket credentials via UNIX domain
              sockets.

       CAP_SETFCAP (since Linux 2.6.24)
              Set file capabilities.

       CAP_SETPCAP
              If file capabilities are not supported: grant or remove any
              capability in the caller's permitted capability set to or from any
              other process.  (This property of CAP_SETPCAP is not available when
              the kernel is configured to support file capabilities, since
              CAP_SETPCAP has entirely different semantics for such kernels.)

              If file capabilities are supported: add any capability from the
              calling thread's bounding set to its inheritable set; drop
              capabilities from the bounding set (via prctl(2) PR_CAPBSET_DROP);
              make changes to the securebits flags.

       CAP_SETUID
              Make arbitrary manipulations of process UIDs (setuid(2),
              setreuid(2), setresuid(2), setfsuid(2)); make forged UID when
              passing socket credentials via UNIX domain sockets.

       CAP_SYS_ADMIN
              * Perform a range of system administration operations including:
                quotactl(2), mount(2), umount(2), swapon(2), swapoff(2),
                sethostname(2), and setdomainname(2);
              * perform privileged syslog(2) operations (since Linux 2.6.37,
                CAP_SYSLOG should be used to permit such operations);
              * perform VM86_REQUEST_IRQ vm86(2) command;
              * perform IPC_SET and IPC_RMID operations on arbitrary System V IPC
                objects;
              * perform operations on trusted and security Extended Attributes
                (see attr(5));
              * use lookup_dcookie(2);
              * use ioprio_set(2) to assign IOPRIO_CLASS_RT and (before Linux
                2.6.25) IOPRIO_CLASS_IDLE I/O scheduling classes;
              * forge UID when passing socket credentials;
              * exceed /proc/sys/fs/file-max, the system-wide limit on the number
                of open files, in system calls that open files (e.g., accept(2),
                execve(2), open(2), pipe(2));
              * employ CLONE_* flags that create new namespaces with clone(2) and
                unshare(2);
              * call perf_event_open(2);
              * access privileged perf event information;
              * call setns(2);
              * call fanotify_init(2);
              * perform KEYCTL_CHOWN and KEYCTL_SETPERM keyctl(2) operations;
              * perform madvise(2) MADV_HWPOISON operation;
              * employ the TIOCSTI ioctl(2) to insert characters into the input
                queue of a terminal other than the caller's controlling terminal.
              * employ the obsolete nfsservctl(2) system call;
              * employ the obsolete bdflush(2) system call;
              * perform various privileged block-device ioctl(2) operations;
              * perform various privileged file-system ioctl(2) operations;
              * perform administrative operations on many device drivers.

       CAP_SYS_BOOT
              Use reboot(2) and kexec_load(2).

       CAP_SYS_CHROOT
              Use chroot(2).

       CAP_SYS_MODULE
              Load and unload kernel modules (see init_module(2) and
              delete_module(2)); in kernels before 2.6.25: drop capabilities from
              the system-wide capability bounding set.

       CAP_SYS_NICE
              * Raise process nice value (nice(2), setpriority(2)) and change the
                nice value for arbitrary processes;
              * set real-time scheduling policies for calling process, and set
                scheduling policies and priorities for arbitrary processes
                (sched_setscheduler(2), sched_setparam(2));
              * set CPU affinity for arbitrary processes (sched_setaffinity(2));
              * set I/O scheduling class and priority for arbitrary processes
                (ioprio_set(2));
              * apply migrate_pages(2) to arbitrary processes and allow processes
                to be migrated to arbitrary nodes;
              * apply move_pages(2) to arbitrary processes;
              * use the MPOL_MF_MOVE_ALL flag with mbind(2) and move_pages(2).

       CAP_SYS_PACCT
              Use acct(2).

       CAP_SYS_PTRACE
              Trace arbitrary processes using ptrace(2); apply get_robust_list(2)
              to arbitrary processes.

       CAP_SYS_RAWIO
              Perform I/O port operations (iopl(2) and ioperm(2)); access
              /proc/kcore; employ the FIBMAP ioctl(2) operation.

       CAP_SYS_RESOURCE
              * Use reserved space on ext2 file systems;
              * make ioctl(2) calls controlling ext3 journaling;
              * override disk quota limits;
              * increase resource limits (see setrlimit(2));
              * override RLIMIT_NPROC resource limit;
              * override maximum number of consoles on console allocation;
              * override maximum number of keymaps;
              * allow more than 64hz interrupts from the real-time clock;
              * raise msg_qbytes limit for a System V message queue above the
                limit in /proc/sys/kernel/msgmnb (see msgop(2) and msgctl(2));
              * override the /proc/sys/fs/pipe-size-max limit when setting the
                capacity of a pipe using the F_SETPIPE_SZ fcntl(2) command.
              * use F_SETPIPE_SZ to increase the capacity of a pipe above the
                limit specified by /proc/sys/fs/pipe-max-size;
              * override /proc/sys/fs/mqueue/queues_max limit when creating POSIX
                message queues (see mq_overview(7));
              * employ prctl(2) PR_SET_MM operation.

       CAP_SYS_TIME
              Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-
              time (hardware) clock.

       CAP_SYS_TTY_CONFIG
              Use vhangup(2); employ various privileged ioctl(2) operations on
              virtual terminals.

       CAP_SYSLOG (since Linux 2.6.37)

       *  Perform privileged syslog(2) operations.  See syslog(2) for information
          on which operations require privilege.

       *  View kernel addresses exposed via /proc and other interfaces when
          /proc/sys/kernel/kptr_restrict has the value 1.  (See the discussion of
          the kptr_restrict in proc(5).)

       CAP_WAKE_ALARM (since Linux 3.0)
          Trigger something that will wake up the system (set CLOCK_REALTIME_ALARM
          and CLOCK_BOOTTIME_ALARM timers).

Past and Current Implementation

       A full implementation of capabilities requires that:

       1. For all privileged operations, the kernel must check whether the thread
          has the required capability in its effective set.

       2. The kernel must provide system calls allowing a thread's capability sets
          to be changed and retrieved.

       3. The file system must support attaching capabilities to an executable
          file, so that a process gains those capabilities when the file is
          executed.

       Before kernel 2.6.24, only the first two of these requirements are met;
       since kernel 2.6.24, all three requirements are met.

Thread Capability Sets

       Each thread has three capability sets containing zero or more of the above
       capabilities:

       Permitted:
              This is a limiting superset for the effective capabilities that the
              thread may assume.  It is also a limiting superset for the
              capabilities that may be added to the inheritable set by a thread
              that does not have the CAP_SETPCAP capability in its effective set.

              If a thread drops a capability from its permitted set, it can never
              reacquire that capability (unless it execve(2)s either a set-user-
              ID-root program, or a program whose associated file capabilities
              grant that capability).

       Inheritable:
              This is a set of capabilities preserved across an execve(2).  It
              provides a mechanism for a process to assign capabilities to the
              permitted set of the new program during an execve(2).

       Effective:
              This is the set of capabilities used by the kernel to perform
              permission checks for the thread.

       A child created via fork(2) inherits copies of its parent's capability
       sets.  See below for a discussion of the treatment of capabilities during
       execve(2).

       Using capset(2), a thread may manipulate its own capability sets (see
       below).

File Capabilities

       Since kernel 2.6.24, the kernel supports associating capability sets with
       an executable file using setcap(8).  The file capability sets are stored in
       an extended attribute (see setxattr(2)) named security.capability.  Writing
       to this extended attribute requires the CAP_SETFCAP capability.  The file
       capability sets, in conjunction with the capability sets of the thread,
       determine the capabilities of a thread after an execve(2).

       The three file capability sets are:

       Permitted (formerly known as forced):
              These capabilities are automatically permitted to the thread,
              regardless of the thread's inheritable capabilities.

       Inheritable (formerly known as allowed):
              This set is ANDed with the thread's inheritable set to determine
              which inheritable capabilities are enabled in the permitted set of
              the thread after the execve(2).

       Effective:
              This is not a set, but rather just a single bit.  If this bit is
              set, then during an execve(2) all of the new permitted capabilities
              for the thread are also raised in the effective set.  If this bit is
              not set, then after an execve(2), none of the new permitted
              capabilities is in the new effective set.

              Enabling the file effective capability bit implies that any file
              permitted or inheritable capability that causes a thread to acquire
              the corresponding permitted capability during an execve(2) (see the
              transformation rules described below) will also acquire that
              capability in its effective set.  Therefore, when assigning
              capabilities to a file (setcap(8), cap_set_file(3), cap_set_fd(3)),
              if we specify the effective flag as being enabled for any
              capability, then the effective flag must also be specified as
              enabled for all other capabilities for which the corresponding
              permitted or inheritable flags is enabled.

Transformation of Capabilities During execve()

       During an execve(2), the kernel calculates the new capabilities of the
       process using the following algorithm:

           P'(permitted) = (P(inheritable) & F(inheritable)) |
                           (F(permitted) & cap_bset)

           P'(effective) = F(effective) ? P'(permitted) : 0

           P'(inheritable) = P(inheritable)    [i.e., unchanged]

       where:

           P         denotes the value of a thread capability set before the
                     execve(2)

           P'        denotes the value of a capability set after the execve(2)

           F         denotes a file capability set

           cap_bset  is the value of the capability bounding set (described
                     below).

Capabilities and execution of programs by root

       In order to provide an all-powerful root using capability sets, during an
       execve(2):

       1. If a set-user-ID-root program is being executed, or the real user ID of
          the process is 0 (root) then the file inheritable and permitted sets are
          defined to be all ones (i.e., all capabilities enabled).

       2. If a set-user-ID-root program is being executed, then the file effective
          bit is defined to be one (enabled).

       The upshot of the above rules, combined with the capabilities
       transformations described above, is that when a process execve(2)s a set-
       user-ID-root program, or when a process with an effective UID of 0
       execve(2)s a program, it gains all capabilities in its permitted and
       effective capability sets, except those masked out by the capability
       bounding set.  This provides semantics that are the same as those provided
       by traditional UNIX systems.

Capability bounding set

       The capability bounding set is a security mechanism that can be used to
       limit the capabilities that can be gained during an execve(2).  The
       bounding set is used in the following ways:

       * During an execve(2), the capability bounding set is ANDed with the file
         permitted capability set, and the result of this operation is assigned to
         the thread's permitted capability set.  The capability bounding set thus
         places a limit on the permitted capabilities that may be granted by an
         executable file.

       * (Since Linux 2.6.25) The capability bounding set acts as a limiting
         superset for the capabilities that a thread can add to its inheritable
         set using capset(2).  This means that if a capability is not in the
         bounding set, then a thread can't add this capability to its inheritable
         set, even if it was in its permitted capabilities, and thereby cannot
         have this capability preserved in its permitted set when it execve(2)s a
         file that has the capability in its inheritable set.

       Note that the bounding set masks the file permitted capabilities, but not
       the inherited capabilities.  If a thread maintains a capability in its
       inherited set that is not in its bounding set, then it can still gain that
       capability in its permitted set by executing a file that has the capability
       in its inherited set.

       Depending on the kernel version, the capability bounding set is either a
       system-wide attribute, or a per-process attribute.

       Capability bounding set prior to Linux 2.6.25

       In kernels before 2.6.25, the capability bounding set is a system-wide
       attribute that affects all threads on the system.  The bounding set is
       accessible via the file /proc/sys/kernel/cap-bound.  (Confusingly, this bit
       mask parameter is expressed as a signed decimal number in
       /proc/sys/kernel/cap-bound.)

       Only the init process may set capabilities in the capability bounding set;
       other than that, the superuser (more precisely: programs with the
       CAP_SYS_MODULE capability) may only clear capabilities from this set.

       On a standard system the capability bounding set always masks out the
       CAP_SETPCAP capability.  To remove this restriction (dangerous!), modify
       the definition of CAP_INIT_EFF_SET in include/linux/capability.h and
       rebuild the kernel.

       The system-wide capability bounding set feature was added to Linux starting
       with kernel version 2.2.11.

       Capability bounding set from Linux 2.6.25 onward

       From Linux 2.6.25, the capability bounding set is a per-thread attribute.
       (There is no longer a system-wide capability bounding set.)

       The bounding set is inherited at fork(2) from the thread's parent, and is
       preserved across an execve(2).

       A thread may remove capabilities from its capability bounding set using the
       prctl(2) PR_CAPBSET_DROP operation, provided it has the CAP_SETPCAP
       capability.  Once a capability has been dropped from the bounding set, it
       cannot be restored to that set.  A thread can determine if a capability is
       in its bounding set using the prctl(2) PR_CAPBSET_READ operation.

       Removing capabilities from the bounding set is only supported if file
       capabilities are compiled into the kernel.  In kernels before Linux 2.6.33,
       file capabilities were an optional feature configurable via the
       CONFIG_SECURITY_FILE_CAPABILITIES option.  Since Linux 2.6.33, the
       configuration option has been removed and file capabilities are always part
       of the kernel.  When file capabilities are compiled into the kernel, the
       init process (the ancestor of all processes) begins with a full bounding
       set.  If file capabilities are not compiled into the kernel, then init
       begins with a full bounding set minus CAP_SETPCAP, because this capability
       has a different meaning when there are no file capabilities.

       Removing a capability from the bounding set does not remove it from the
       thread's inherited set.  However it does prevent the capability from being
       added back into the thread's inherited set in the future.

Effect of User ID Changes on Capabilities

       To preserve the traditional semantics for transitions between 0 and nonzero
       user IDs, the kernel makes the following changes to a thread's capability
       sets on changes to the thread's real, effective, saved set, and file system
       user IDs (using setuid(2), setresuid(2), or similar):

       1. If one or more of the real, effective or saved set user IDs was
          previously 0, and as a result of the UID changes all of these IDs have a
          nonzero value, then all capabilities are cleared from the permitted and
          effective capability sets.

       2. If the effective user ID is changed from 0 to nonzero, then all
          capabilities are cleared from the effective set.

       3. If the effective user ID is changed from nonzero to 0, then the
          permitted set is copied to the effective set.

       4. If the file system user ID is changed from 0 to nonzero (see
          setfsuid(2)) then the following capabilities are cleared from the
          effective set: CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
          CAP_FOWNER, CAP_FSETID, CAP_LINUX_IMMUTABLE (since Linux 2.2.30),
          CAP_MAC_OVERRIDE, and CAP_MKNOD (since Linux 2.2.30).  If the file
          system UID is changed from nonzero to 0, then any of these capabilities
          that are enabled in the permitted set are enabled in the effective set.

       If a thread that has a 0 value for one or more of its user IDs wants to
       prevent its permitted capability set being cleared when it resets all of
       its user IDs to nonzero values, it can do so using the prctl(2)
       PR_SET_KEEPCAPS operation.

Programmatically adjusting capability sets

       A thread can retrieve and change its capability sets using the capget(2)
       and capset(2) system calls.  However, the use of cap_get_proc(3) and
       cap_set_proc(3), both provided in the libcap package, is preferred for this
       purpose.  The following rules govern changes to the thread capability sets:

       1. If the caller does not have the CAP_SETPCAP capability, the new
          inheritable set must be a subset of the combination of the existing
          inheritable and permitted sets.

       2. (Since kernel 2.6.25) The new inheritable set must be a subset of the
          combination of the existing inheritable set and the capability bounding
          set.

       3. The new permitted set must be a subset of the existing permitted set
          (i.e., it is not possible to acquire permitted capabilities that the
          thread does not currently have).

       4. The new effective set must be a subset of the new permitted set.

The "securebits" flags: establishing a capabilities-only environment

       Starting with kernel 2.6.26, and with a kernel in which file capabilities
       are enabled, Linux implements a set of per-thread securebits flags that can
       be used to disable special handling of capabilities for UID 0 (root).
       These flags are as follows:

       SECBIT_KEEP_CAPS
              Setting this flag allows a thread that has one or more 0 UIDs to
              retain its capabilities when it switches all of its UIDs to a
              nonzero value.  If this flag is not set, then such a UID switch
              causes the thread to lose all capabilities.  This flag is always
              cleared on an execve(2).  (This flag provides the same functionality
              as the older prctl(2) PR_SET_KEEPCAPS operation.)

       SECBIT_NO_SETUID_FIXUP
              Setting this flag stops the kernel from adjusting capability sets
              when the threads's effective and file system UIDs are switched
              between zero and nonzero values.  (See the subsection Effect of User
              ID Changes on Capabilities.)

       SECBIT_NOROOT
              If this bit is set, then the kernel does not grant capabilities when
              a set-user-ID-root program is executed, or when a process with an
              effective or real UID of 0 calls execve(2).  (See the subsection
              Capabilities and execution of programs by root.)

       Each of the above "base" flags has a companion "locked" flag.  Setting any
       of the "locked" flags is irreversible, and has the effect of preventing
       further changes to the corresponding "base" flag.  The locked flags are:
       SECBIT_KEEP_CAPS_LOCKED, SECBIT_NO_SETUID_FIXUP_LOCKED, and
       SECBIT_NOROOT_LOCKED.

       The securebits flags can be modified and retrieved using the prctl(2)
       PR_SET_SECUREBITS and PR_GET_SECUREBITS operations.  The CAP_SETPCAP
       capability is required to modify the flags.

       The securebits flags are inherited by child processes.  During an
       execve(2), all of the flags are preserved, except SECBIT_KEEP_CAPS which is
       always cleared.

       An application can use the following call to lock itself, and all of its
       descendants, into an environment where the only way of gaining capabilities
       is by executing a program with associated file capabilities:

           prctl(PR_SET_SECUREBITS,
                   SECBIT_KEEP_CAPS_LOCKED |
                   SECBIT_NO_SETUID_FIXUP |
                   SECBIT_NO_SETUID_FIXUP_LOCKED |
                   SECBIT_NOROOT |
                   SECBIT_NOROOT_LOCKED);

CONFORMING TO top

       No standards govern capabilities, but the Linux capability implementation
       is based on the withdrawn POSIX.1e draft standard; see
       <http://wt.tuxomania.net/publications/posix.1e/>.

NOTES top

       Since kernel 2.5.27, capabilities are an optional kernel component, and can
       be enabled/disabled via the CONFIG_SECURITY_CAPABILITIES kernel configura-
       tion option.

       The /proc/PID/task/TID/status file can be used to view the capability sets
       of a thread.  The /proc/PID/status file shows the capability sets of a
       process's main thread.

       The libcap package provides a suite of routines for setting and getting
       capabilities that is more comfortable and less likely to change than the
       interface provided by capset(2) and capget(2).  This package also provides
       the setcap(8) and getcap(8) programs.  It can be found at
       <http://www.kernel.org/pub/linux/libs/security/linux-privs>.

       Before kernel 2.6.24, and since kernel 2.6.24 if file capabilities are not
       enabled, a thread with the CAP_SETPCAP capability can manipulate the capa-
       bilities of threads other than itself.  However, this is only theoretically
       possible, since no thread ever has CAP_SETPCAP in either of these cases:

       * In the pre-2.6.25 implementation the system-wide capability bounding set,
         /proc/sys/kernel/cap-bound, always masks out this capability, and this
         can not be changed without modifying the kernel source and rebuilding.

       * If file capabilities are disabled in the current implementation, then
         init starts out with this capability removed from its per-process bound-
         ing set, and that bounding set is inherited by all other processes cre-
         ated on the system.

SEE ALSO top

       capget(2), prctl(2), setfsuid(2), cap_clear(3), cap_copy_ext(3),
       cap_from_text(3), cap_get_file(3), cap_get_proc(3), cap_init(3),
       capgetp(3), capsetp(3), libcap(3), credentials(7), pthreads(7), getcap(8),
       setcap(8)

       include/linux/capability.h in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2012-12-09                     CAPABILITIES(7)


capget(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CAPGET(2)                    Linux Programmer's Manual                   CAPGET(2)

NAME top

       capget, capset - set/get capabilities of thread(s)

SYNOPSIS top

       #include <sys/capability.h>

       int capget(cap_user_header_t hdrp, cap_user_data_t datap);

       int capset(cap_user_header_t hdrp, const cap_user_data_t datap);

DESCRIPTION top

       As of Linux 2.2, the power of the superuser (root) has been partitioned
       into a set of discrete capabilities.  Each thread has a set of effective
       capabilities identifying which capabilities (if any) it may currently
       exercise.  Each thread also has a set of inheritable capabilities that may
       be passed through an execve(2) call, and a set of permitted capabilities
       that it can make effective or inheritable.

       These two functions are the raw kernel interface for getting and setting
       thread capabilities.  Not only are these system calls specific to Linux,
       but the kernel API is likely to change and use of these functions (in
       particular the format of the cap_user_*_t types) is subject to extension
       with each kernel revision, but old programs will keep working.

       The portable interfaces are cap_set_proc(3) and cap_get_proc(3); if
       possible you should use those interfaces in applications.  If you wish to
       use the Linux extensions in applications, you should use the easier-to-use
       interfaces capsetp(3) and capgetp(3).

Current details

       Now that you have been warned, some current kernel details.  The structures
       are defined as follows.

           #define _LINUX_CAPABILITY_VERSION_1  0x19980330
           #define _LINUX_CAPABILITY_U32S_1     1

           #define _LINUX_CAPABILITY_VERSION_2  0x20071026
           #define _LINUX_CAPABILITY_U32S_2     2

           typedef struct __user_cap_header_struct {
              __u32 version;
              int pid;
           } *cap_user_header_t;

           typedef struct __user_cap_data_struct {
              __u32 effective;
              __u32 permitted;
              __u32 inheritable;
           } *cap_user_data_t;

       effective, permitted, inheritable are bitmasks of the capabilities defined
       in capability(7).  Note the CAP_* values are bit indexes and need to be
       bit-shifted before ORing into the bit fields.  To define the structures for
       passing to the system call you have to use the struct
       __user_cap_header_struct and struct __user_cap_data_struct names because
       the typedefs are only pointers.

       Kernels prior to 2.6.25 prefer 32-bit capabilities with version
       _LINUX_CAPABILITY_VERSION_1, and kernels 2.6.25+ prefer 64-bit capabilities
       with version _LINUX_CAPABILITY_VERSION_2.  Note, 64-bit capabilities use
       datap[0] and datap[1], whereas 32-bit capabilities use only datap[0].

       Another change affecting the behavior of these system calls is kernel
       support for file capabilities (VFS capability support).  This support is
       currently a compile time option (added in kernel 2.6.24).

       For capget() calls, one can probe the capabilities of any process by
       specifying its process ID with the hdrp->pid field value.

With VFS Capability Support

       VFS Capability support creates a file-attribute method for adding
       capabilities to privileged executables.  This privilege model obsoletes
       kernel support for one process asynchronously setting the capabilities of
       another.  That is, with VFS support, for capset() calls the only permitted
       values for hdrp->pid are 0 or getpid(2), which are equivalent.

Without VFS Capability Support

       When the kernel does not support VFS capabilities, capset() calls can
       operate on the capabilities of the thread specified by the pid field of
       hdrp when that is nonzero, or on the capabilities of the calling thread if
       pid is 0.  If pid refers to a single-threaded process, then pid can be
       specified as a traditional process ID; operating on a thread of a
       multithreaded process requires a thread ID of the type returned by
       gettid(2).  For capset(), pid can also be: -1, meaning perform the change
       on all threads except the caller and init(8); or a value less than -1, in
       which case the change is applied to all members of the process group whose
       ID is -pid.

       For details on the data, see capabilities(7).

RETURN VALUE top

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

       The calls will fail with the error EINVAL, and set the version field of
       hdrp to the kernel preferred value of _LINUX_CAPABILITY_VERSION_?  when an
       unsupported version value is specified.  In this way, one can probe what
       the current preferred capability revision is.

ERRORS top

       EFAULT Bad memory address.  hdrp must not be NULL.  datap may be NULL only
              when the user is trying to determine the preferred capability
              version format supported by the kernel.

       EINVAL One of the arguments was invalid.

       EPERM  An attempt was made to add a capability to the Permitted set, or to
              set a capability in the Effective or Inheritable sets that is not in
              the Permitted set.

       EPERM  The caller attempted to use capset() to modify the capabilities of a
              thread other than itself, but lacked sufficient privilege.  For
              kernels supporting VFS capabilities, this is never permitted.  For
              kernels lacking VFS support, the CAP_SETPCAP capability is required.
              (A bug in kernels before 2.6.11 meant that this error could also
              occur if a thread without this capability tried to change its own
              capabilities by specifying the pid field as a nonzero value (i.e.,
              the value returned by getpid(2)) instead of 0.)

       ESRCH  No such thread.

CONFORMING TO top

       These system calls are Linux-specific.

NOTES top

       The portable interface to the capability querying and setting functions is
       provided by the libcap library and is available here:
       <http://www.kernel.org/pub/linux/libs/security/linux-privs>

SEE ALSO top

       clone(2), gettid(2), capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                           CAPGET(2)


carg(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CARG(3)                      Linux Programmer's Manual                     CARG(3)

NAME top

       carg, cargf, cargl - calculate the complex argument

SYNOPSIS top

       #include <complex.h>

       double carg(double complex z);
       float cargf(float complex z);
       long double cargl(long double complex z);

       Link with -lm.

DESCRIPTION top

       A complex number can be described by two real coordinates.  One may use
       rectangular coordinates and gets

           z = x + I * y

       where x = creal(z) and y = cimag(z).

       Or one may use polar coordinates and gets

           z = r * cexp(I * a)

       where r = cabs(z) is the "radius", the "modulus", the absolute value of z,
       and a = carg(z) is the "phase angle", the argument of z.

       One has:

           tan(carg(z)) = cimag(z) / creal(z)

RETURN VALUE top

       The return value is the range of [-pi,pi].

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CARG(3)


casin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CASIN(3)                     Linux Programmer's Manual                    CASIN(3)

NAME top

       casin, casinf, casinl - complex arc sine

SYNOPSIS top

       #include <complex.h>

       double complex casin(double complex z);
       float complex casinf(float complex z);
       long double complex casinl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The casin() function calculates the complex arc sine of z.  If
       y = casin(z), then z = csin(y).  The real part of y is chosen in the
       interval [-pi/2,pi/2].

       One has:

           casin(z) = -i clog(iz + csqrt(1 - z * z))

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       clog(3), csin(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CASIN(3)


casinh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CASINH(3)                    Linux Programmer's Manual                   CASINH(3)

NAME top

       casinh, casinhf, casinhl - complex arc sine hyperbolic

SYNOPSIS top

       #include <complex.h>

       double complex casinh(double complex z);
       float complex casinhf(float complex z);
       long double complex casinhl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The casinh() function calculates the complex arc hyperbolic sine of z.  If
       y = casinh(z), then z = csinh(y).  The imaginary part of y is chosen in the
       interval [-pi/2,pi/2].

       One has:

           casinh(z) = clog(z + csqrt(z * z + 1))

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       asinh(3), cabs(3), cimag(3), csinh(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                           CASINH(3)


catan(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CATAN(3)                     Linux Programmer's Manual                    CATAN(3)

NAME top

       catan, catanf, catanl - complex arc tangents

SYNOPSIS top

       #include <complex.h>

       double complex catan(double complex z);
       float complex catanf(float complex z);
       long double complex catanl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The catan() function calculates the complex arc tangent of z.  If
       y = catan(z), then z = ctan(y).  The real part of y is chosen in the
       interval [-pi/2,pi/2].

       One has:

           catan(z) = (clog(1 + i * z) - clog(1 - i * z)) / (2 * i)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

EXAMPLE top

       /* Link with "-lm" */

       #include <complex.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           double complex z, c, f;
           double complex i = I;

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

           z = atof(argv[1]) + atof(argv[2]) * I;

           c = catan(z);
           printf("catan() = %6.3f %6.3f*i\n", creal(c), cimag(c));

           f = (clog(1 + i * z) - clog(1 - i * z)) / (2 * i);
           printf("formula = %6.3f %6.3f*i\n", creal(f2), cimag(f2));

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       ccos(3), clog(3), ctan(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2011-09-15                            CATAN(3)


catanh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CATANH(3)                    Linux Programmer's Manual                   CATANH(3)

NAME top

       catanh, catanhf, catanhl - complex arc tangents hyperbolic

SYNOPSIS top

       #include <complex.h>

       double complex catanh(double complex z);
       float complex catanhf(float complex z);
       long double complex catanhl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The catanh() function calculates the complex arc hyperbolic tangent of z.
       If y = catanh(z), then z = ctanh(y).  The imaginary part of y is chosen in
       the interval [-pi/2,pi/2].

       One has:

           catanh(z) = 0.5 * (clog(1 + z) - clog(1 - z))

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

EXAMPLE top

       /* Link with "-lm" */

       #include <complex.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           double complex z, c, f;

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

           z = atof(argv[1]) + atof(argv[2]) * I;

           c = catanh(z);
           printf("catanh() = %6.3f %6.3f*i\n", creal(c), cimag(c));

           f = 0.5 * (clog(1 + z) - clog(1 - z));
           printf("formula  = %6.3f %6.3f*i\n", creal(f2), cimag(f2));

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       atanh(3), cabs(3), cimag(3), ctanh(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2011-09-15                           CATANH(3)


catopen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ENVIRONMENT | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CATOPEN(3)                   Linux Programmer's Manual                  CATOPEN(3)

NAME top

       catopen, catclose - open/close a message catalog

SYNOPSIS top

       #include <nl_types.h>

       nl_catd catopen(const char *name, int flag);

       int catclose(nl_catd catalog);

DESCRIPTION top

       The function catopen() opens a message catalog and returns a catalog
       descriptor.  The descriptor remains valid until catclose() or execve(2).
       If a file descriptor is used to implement catalog descriptors then the
       FD_CLOEXEC flag will be set.

       The argument name specifies the name of the message catalog to be opened.
       If name specifies and absolute path (i.e., contains a '/'), then name
       specifies a pathname for the message catalog.  Otherwise, the environment
       variable NLSPATH is used with name substituted for %N (see locale(7)).  It
       is unspecified whether NLSPATH will be used when the process has root
       privileges.  If NLSPATH does not exist in the environment, or if a message
       catalog cannot be opened in any of the paths specified by it, then an
       implementation defined path is used.  This latter default path may depend
       on the LC_MESSAGES locale setting when the flag argument is NL_CAT_LOCALE
       and on the LANG environment variable when the flag argument is 0.  Changing
       the LC_MESSAGES part of the locale may invalidate open catalog descriptors.

       The flag argument to catopen() is used to indicate the source for the
       language to use.  If it is set to NL_CAT_LOCALE then it will use the
       current locale setting for LC_MESSAGES.  Otherwise it will use the LANG
       environment variable.

       The function catclose() closes the message catalog identified by catalog.
       It invalidates any subsequent references to the message catalog defined by
       catalog.

RETURN VALUE top

       The function catopen() returns a message catalog descriptor of type nl_catd
       on success.  On failure, it returns (nl_catd) -1 and sets errno to indicate
       the error.  The possible error values include all possible values for the
       open(2) call.

       The function catclose() returns 0 on success, or -1 on failure.

ENVIRONMENT top

       LC_MESSAGES
              May be the source of the LC_MESSAGES locale setting, and thus
              determine the language to use if flag is set to NL_CAT_LOCALE.

       LANG   The language to use if flag is 0.

CONFORMING TO top

       POSIX.1-2001.  It is unclear what the source was for the constants
       MCLoadBySet and MCLoadAll (see below).

NOTES top

       The above is the POSIX.1-2001 description.  The glibc value for
       NL_CAT_LOCALE is 1.  (Compare MCLoadAll below.)  The default path varies,
       but usually looks at a number of places below /usr/share/locale.

Linux Notes

       These functions are available for Linux since libc 4.4.4c.  In the case of
       linux libc4 and libc5, the catalog descriptor nl_catd is a mmap(2)'ed area
       of memory and not a file descriptor.  The flag argument to catopen() should
       be either MCLoadBySet (=0) or MCLoadAll (=1).  The former value indicates
       that a set from the catalog is to be loaded when needed, whereas the latter
       causes the initial call to catopen() to load the entire catalog into
       memory.  The default search path varies, but usually looks at a number of
       places below /etc/locale and /usr/lib/locale.

SEE ALSO top

       catgets(3), setlocale(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2001-12-14                          CATOPEN(3)


catgets(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CATGETS(3)                   Linux Programmer's Manual                  CATGETS(3)

NAME top

       catgets - get message from a message catalog

SYNOPSIS top

       #include <nl_types.h>

       char *catgets(nl_catd catalog, int set_number, int message_number,
                     const char *message);

DESCRIPTION top

       catgets() reads the message message_number, in set set_number, from the
       message catalog identified by catalog, where catalog is a catalog
       descriptor returned from an earlier call to catopen(3).  The fourth
       argument message points to a default message string which will be returned
       by catgets() if the identified message catalog is not currently available.
       The message-text is contained in an internal buffer area and should be
       copied by the application if it is to be saved or modified.  The return
       string is always terminated with a null byte.

RETURN VALUE top

       On success, catgets() returns a pointer to an internal buffer area
       containing the null-terminated message string.  On failure, catgets()
       returns the value message.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       These functions are only available in libc.so.4.4.4c and above.  The Jan
       1987 X/Open Portability Guide specifies a more subtle error return: message
       is returned if the message catalog specified by catalog is not available,
       while an empty string is returned when the message catalog is available but
       does not contain the specified message.  These two possible error returns
       seem to be discarded in SUSv2 in favor of always returning message.

SEE ALSO top

       catopen(3), setlocale(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    1998-08-09                          CATGETS(3)


des_crypt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

DES_CRYPT(3)                 Linux Programmer's Manual                DES_CRYPT(3)

NAME top

       des_crypt,  ecb_crypt,  cbc_crypt,  des_setparity,  DES_FAILED  -  fast DES
       encryption

SYNOPSIS top

       #include <rpc/des_crypt.h>

       int ecb_crypt(char *key, char *data, unsigned datalen,
                     unsigned mode);

       int cbc_crypt(char *key, char *data, unsigned datalen,
                     unsigned mode, char *ivec);

       void des_setparity(char *key);

       int DES_FAILED(int status);

DESCRIPTION top

       ecb_crypt() and cbc_crypt() implement the NBS DES (Data Encryption
       Standard).  These routines are faster and more general purpose than
       crypt(3).  They also are able to utilize DES hardware if it is available.
       ecb_crypt() encrypts in ECB (Electronic Code Book) mode, which encrypts
       blocks of data independently.  cbc_crypt() encrypts in CBC (Cipher Block
       Chaining) mode, which chains together successive blocks.  CBC mode protects
       against insertions, deletions and substitutions of blocks.  Also,
       regularities in the clear text will not appear in the cipher text.

       Here is how to use these routines.  The first argument, key, is the 8-byte
       encryption key with parity.  To set the key's parity, which for DES is in
       the low bit of each byte, use des_setparity().  The second argument, data,
       contains the data to be encrypted or decrypted.  The third argument,
       datalen, is the length in bytes of data, which must be a multiple of 8.
       The fourth argument, mode, is formed by ORing together some things.  For
       the encryption direction OR in either DES_ENCRYPT or DES_DECRYPT.  For
       software versus hardware encryption, OR in either DES_HW or DES_SW.  If
       DES_HW is specified, and there is no hardware, then the encryption is
       performed in software and the routine returns DESERR_NOHWDEVICE.  For
       cbc_crypt(), the argument ivec is the 8-byte initialization vector for the
       chaining.  It is updated to the next initialization vector upon return.

RETURN VALUE top

       DESERR_NONE         No error.
       DESERR_NOHWDEVICE   Encryption succeeded, but done in software instead of
                           the requested hardware.
       DESERR_HWERROR      An error occurred in the hardware or driver.
       DESERR_BADPARAM     Bad argument to routine.

       Given a result status stat, the macro DES_FAILED(stat) is false only for
       the first two statuses.

VERSIONS top

       These routines are present in libc 4.6.27 and later, and in glibc 2.1 and
       later.

CONFORMING TO top

       4.3BSD.  Not in POSIX.1-2001.

SEE ALSO top

       des(1), crypt(3), xcrypt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-05-18                        DES_CRYPT(3)


cbrt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CBRT(3)                      Linux Programmer's Manual                     CBRT(3)

NAME top

       cbrt, cbrtf, cbrtl - cube root function

SYNOPSIS top

       #include <math.h>

       double cbrt(double x);
       float cbrtf(float x);
       long double cbrtl(long double x);

       Link with -lm.

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

       cbrt():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       cbrtf(), cbrtl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOUCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The cbrt() function returns the (real) cube root of x.  This function
       cannot fail; every representable real value has a representable real cube
       root.

RETURN VALUE top

       These functions return the cube root of x.

       If x is +0, -0, positive infinity, negative infinity, or NaN, x is
       returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       pow(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                             CBRT(3)


cciss(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

CCISS(4)                     Linux Programmer's Manual                    CCISS(4)

NAME top

       cciss - HP Smart Array block driver

SYNOPSIS top

       modprobe cciss [ cciss_allow_hpsa=1 ]

DESCRIPTION top

       cciss is a block driver for older HP Smart Array RAID controllers.

Options

       cciss_allow_hpsa=1: This option prevents the cciss driver from attempting
       to drive any controllers that the hpsa(4) driver is capable of controlling,
       which is to say, the cciss driver is restricted by this option to the
       following controllers:

           Smart Array 5300
           Smart Array 5i
           Smart Array 532
           Smart Array 5312
           Smart Array 641
           Smart Array 642
           Smart Array 6400
           Smart Array 6400 EM
           Smart Array 6i
           Smart Array P600
           Smart Array P400i
           Smart Array E200i
           Smart Array E200
           Smart Array E200i
           Smart Array E200i
           Smart Array E200i
           Smart Array E500

Supported Hardware

       The cciss driver supports the following Smart Array boards:

           Smart Array 5300
           Smart Array 5i
           Smart Array 532
           Smart Array 5312
           Smart Array 641
           Smart Array 642
           Smart Array 6400
           Smart Array 6400 U320 Expansion Module
           Smart Array 6i
           Smart Array P600
           Smart Array P800
           Smart Array E400
           Smart Array P400i
           Smart Array E200
           Smart Array E200i
           Smart Array E500
           Smart Array P700m
           Smart Array P212
           Smart Array P410
           Smart Array P410i
           Smart Array P411
           Smart Array P812
           Smart Array P712m
           Smart Array P711m

Configuration Details

       To configure HP Smart Array controllers, use the HP Array Configuration
       Utility (either hpacuxe(8) or hpacucli(8)) or the Offline ROM-based
       Configuration Utility (ORCA) run from the Smart Array's option ROM at boot
       time.

FILES top

Device Nodes

       The device naming scheme is as follows:

       Major numbers:

           104     cciss0
           105     cciss1
           106     cciss2
           105     cciss3
           108     cciss4
           109     cciss5
           110     cciss6
           111     cciss7

       Minor numbers:

           b7 b6 b5 b4 b3 b2 b1 b0
           |----+----| |----+----|
                |           |
                |           +-------- Partition ID (0=wholedev, 1-15 partition)
                |
                +-------------------- Logical Volume number

       The device naming scheme is:

           /dev/cciss/c0d0         Controller 0, disk 0, whole device
           /dev/cciss/c0d0p1       Controller 0, disk 0, partition 1
           /dev/cciss/c0d0p2       Controller 0, disk 0, partition 2
           /dev/cciss/c0d0p3       Controller 0, disk 0, partition 3

           /dev/cciss/c1d1         Controller 1, disk 1, whole device
           /dev/cciss/c1d1p1       Controller 1, disk 1, partition 1
           /dev/cciss/c1d1p2       Controller 1, disk 1, partition 2
           /dev/cciss/c1d1p3       Controller 1, disk 1, partition 3

Files in /proc

       The files /proc/driver/cciss/cciss[0-9]+ contain information about the
       configuration of each controller.  For example:

           $ cd /proc/driver/cciss
           $ ls -l
           total 0
           -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss0
           -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss1
           -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss2
           $ cat cciss2
           cciss2: HP Smart Array P800 Controller
           Board ID: 0x3223103c
           Firmware Version: 7.14
           IRQ: 16
           Logical drives: 1
           Current Q depth: 0
           Current # commands on controller: 0
           Max Q depth since init: 1
           Max # commands on controller since init: 2
           Max SG entries since init: 32
           Sequential access devices: 0

           cciss/c2d0:   36.38GB       RAID 0

Files in /sys

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
              Displays the SCSI INQUIRY page 0 model for logical drive Y of
              controller X.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
              Displays the SCSI INQUIRY page 0 revision for logical drive Y of
              controller X.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
              Displays the SCSI INQUIRY page 83 serial number for logical drive Y
              of controller X.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
              Displays the SCSI INQUIRY page 0 vendor for logical drive Y of
              controller X.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
              A symbolic link to /sys/block/cciss!cXdY.

       /sys/bus/pci/devices/<dev>/ccissX/rescan
              When this file is written to, the driver rescans the controller to
              discover any new, removed, or modified logical drives.

       /sys/bus/pci/devices/<dev>/ccissX/resettable
              A value of 1 displayed in this file indicates that the
              "reset_devices=1" kernel parameter (used by kdump) is honored by
              this controller.  A value of 0 indicates that the "reset_devices=1"
              kernel parameter will not be honored.  Some models of Smart Array
              are not able to honor this parameter.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
              Displays the 8-byte LUN ID used to address logical drive Y of
              controller X.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
              Displays the RAID level of logical drive Y of controller X.

       /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
              Displays the usage count (number of opens) of logical drive Y of
              controller X.

SCSI tape drive and medium changer support

       SCSI sequential access devices and medium changer devices are supported and
       appropriate device nodes are automatically created (e.g., /dev/st0,
       /dev/st1, etc.; see st(4) for more details.)  You must enable "SCSI tape
       drive support for Smart Array 5xxx" and "SCSI support" in your kernel
       configuration to be able to use SCSI tape drives with your Smart Array 5xxx
       controller.

       Additionally, note that the driver will not engage the SCSI core at init
       time.  The driver must be directed to dynamically engage the SCSI core via
       the /proc file-system entry, which the "block" side of the driver creates
       as /proc/driver/cciss/cciss* at run time.  This is because at driver init
       time, the SCSI core may not yet be initialized (because the driver is a
       block driver) and attempting to register it with the SCSI core in such a
       case would cause a hang.  This is best done via an initialization script
       (typically in /etc/init.d, but could vary depending on distribution).  For
       example:

           for x in /proc/driver/cciss/cciss[0-9]*
           do
               echo "engage scsi" > $x
           done

       Once the SCSI core is engaged by the driver, it cannot be disengaged
       (except by unloading the driver, if it happens to be linked as a module.)

       Note also that if no sequential access devices or medium changers are
       detected, the SCSI core will not be engaged by the action of the above
       script.

Hot plug support for SCSI tape drives

       Hot plugging of SCSI tape drives is supported, with some caveats.  The
       cciss driver must be informed that changes to the SCSI bus have been made.
       This may be done via the /proc file system.  For example:

           echo "rescan" > /proc/scsi/cciss0/1

       This causes the driver to:

              1. query the adapter about changes to the physical SCSI buses and/or
                 fibre channel arbitrated loop, and

              2. make note of any new or removed sequential access devices or
                 medium changers.

       The driver will output messages indicating which devices have been added or
       removed and the controller, bus, target and lun used to address each
       device.  The driver then notifies the SCSI midlayer of these changes.

       Note that the naming convention of the /proc file-system entries contains a
       number in addition to the driver name (e.g., "cciss0" instead of just
       "cciss", which you might expect).

       Note: Only sequential access devices and medium changers are presented as
       SCSI devices to the SCSI midlayer by the cciss driver.  Specifically,
       physical SCSI disk drives are not presented to the SCSI midlayer.  The only
       disk devices that are presented to the kernel are logical drives that the
       array controller constructs from regions on the physical drives.  The
       logical drives are presented to the block layer (not to the SCSI midlayer).
       It is important for the driver to prevent the kernel from accessing the
       physical drives directlyi, since these drives are used by the array
       controller to construct the logical drives.

SCSI error handling for tape drives and medium changers

       The Linux SCSI midlayer provides an error-handling protocol that is
       initiated whenever a SCSI command fails to complete within a certain amount
       of time (which can vary depending on the command).  The cciss driver
       participates in this protocol to some extent.  The normal protocol is a
       four-step process:

       *  First, the device is told to abort the command.

       *  If that doesn't work, the device is reset.

       *  If that doesn't work, the SCSI bus is reset.

       *  If that doesn't work the host bus adapter is reset.

       The cciss driver is a block driver as well as a SCSI driver and only the
       tape drives and medium changers are presented to the SCSI midlayer
       Furthermore, unlike more straightforward SCSI drivers, disk I/O continues
       through the block side during the SCSI error-recovery process Therefore,
       the cciss driver implements only the first two of these actions, aborting
       the command, and resetting the device.  Note also that most tape drives
       will not oblige in aborting commands, and sometimes it appears they will
       not even obey a reset command, though in most circumstances they will.  If
       the command cannot be aborted and the device cannot be reset, the device
       will be set offline.

       In the event that the error-handling code is triggered and a tape drive is
       successfully reset or the tardy command is successfully aborted, the tape
       drive may still not allow I/O to continue until some command is issued that
       positions the tape to a known position.  Typically you must rewind the tape
       (by issuing mt -f /dev/st0 rewind for example) before I/O can proceed again
       to a tape drive that was reset.

SEE ALSO          top
       cciss_vol_status(8), hpsa(4), hpacucli(8), hpacuxe(8),

       <http://cciss.sf.net>, and Documentation/blockdev/cciss.txt and Documenta-
       tion/ABI/testing/sysfs-bus-pci-devices-cciss in the Linux kernel source
       tree

COLOPHON          top
       This page is part of release 3.45 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                               2012-08-05                            CCISS(4)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


ccos(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CCOS(3)                      Linux Programmer's Manual                     CCOS(3)

NAME top

       ccos, ccosf, ccosl - complex cosine function

SYNOPSIS top

       #include <complex.h>

       double complex ccos(double complex z);
       float complex ccosf(float complex z);
       long double complex ccosl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The complex cosine function is defined as:

           ccos(z) = (exp(i * z) + exp(-i * z)) / 2

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), cacos(3), csin(3), ctan(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CCOS(3)


ccosh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CCOSH(3)                     Linux Programmer's Manual                    CCOSH(3)

NAME top

       ccosh, ccoshf, ccoshl - complex hyperbolic cosine

SYNOPSIS top

       #include <complex.h>

       double complex ccosh(double complex z);
       float complex ccoshf(float complex z);
       long double complex ccoshl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The complex hyperbolic cosine function is defined as:

           ccosh(z) = (exp(z)+exp(-z))/2

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), cacosh(3), csinh(3), ctanh(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CCOSH(3)


ceil(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CEIL(3)                      Linux Programmer's Manual                     CEIL(3)

NAME top

       ceil,  ceilf,  ceill  -  ceiling function: smallest integral value not less
       than argument

SYNOPSIS top

       #include <math.h>

       double ceil(double x);
       float ceilf(float x);
       long double ceill(long double x);

       Link with -lm.

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

       ceilf(), ceill():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions return the smallest integral value that is not less than x.

       For example, ceil(0.5) is 1.0, and ceil(-0.5) is 0.0.

RETURN VALUE top

       These functions return the ceiling of x.

       If x is integral, +0, -0, NaN, or infinite, x itself is returned.

ERRORS top

       No errors occur.  POSIX.1-2001 documents a range error for overflows, but
       see NOTES.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

NOTES top

       SUSv2 and POSIX.1-2001 contain text about overflow (which might set errno
       to ERANGE, or raise an FE_OVERFLOW exception).  In practice, the result
       cannot overflow on any current machine, so this error-handling stuff is
       just nonsense.  (More precisely, overflow can happen only when the maximum
       value of the exponent is smaller than the number of mantissa bits.  For the
       IEEE-754 standard 32-bit and 64-bit floating-point numbers the maximum
       value of the exponent is 128 (respectively, 1024), and the number of
       mantissa bits is 24 (respectively, 53).)

       The integral value returned by these functions may be too large to store in
       an integer type (int, long, etc.).  To avoid an overflow, which will
       produce undefined results, an application should perform a range check on
       the returned value before assigning it to an integer type.

SEE ALSO top

       floor(3), lrint(3), nearbyint(3), rint(3), round(3), trunc(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             CEIL(3)


cerf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | AVAILABILITY | SEE ALSO | COLOPHON The Linux Programming Interface

CERF(3)                      Linux Programmer's Manual                     CERF(3)

NAME top

       cerf, cerff, cerfl, cerfc, cerfcf, cerfcl - complex error function

SYNOPSIS top

       #include <complex.h>

       double complex cerf(double complex z);
       float complex cerff(float complex z);
       long double complex cerfl(long double complex z);

       double complex cerfc(double complex z);
       float complex cerfcf(float complex z);
       long double complex cerfcl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The (unimplemented) function cerf() is the complex version of the error
       function.  erf(z) = 2/sqrt(pi) * integral from 0 to z of exp(-t*t) dt.  The
       function cerfc() is defined as cerfc(z) = 1-cerf(z).

CONFORMING TO top

       The function names are reserved for future use in C99.

AVAILABILITY top

       Not yet in glibc, as at version 2.12.

SEE ALSO top

       erf(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-12                             CERF(3)


cexp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CEXP(3)                      Linux Programmer's Manual                     CEXP(3)

NAME top

       cexp, cexpf, cexpl - complex exponential function

SYNOPSIS top

       #include <complex.h>

       double complex cexp(double complex z);
       float complex cexpf(float complex z);
       long double complex cexpl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The function calculates e (2.71828..., the base of natural logarithms)
       raised to the power of z.

       One has:

           cexp(I * z) = ccos(z) + I * csin(z)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), cexp2(3), clog(3), cpow(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CEXP(3)


cexp2(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | AVAILABILITY | SEE ALSO | COLOPHON The Linux Programming Interface

CEXP2(3)                     Linux Programmer's Manual                    CEXP2(3)

NAME top

       cexp2, cexp2f, cexp2l - base-2 exponent of a complex number

SYNOPSIS top

       #include <complex.h>

       double complex cexp2(double complex z);
       float complex cexp2f(float complex z);
       long double complex cexp2l(long double complex z);

       Link with -lm.

DESCRIPTION top

       The function returns 2 raised to the power of z.

CONFORMING TO top

       These function names are reserved for future use in C99.

AVAILABILITY top

       Not yet in glibc, as at version 2.8.

SEE ALSO top

       cabs(3), cexp(3), clog10(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-07                            CEXP2(3)


termios(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TERMIOS(3)                   Linux Programmer's Manual                  TERMIOS(3)

NAME top

       termios,  tcgetattr,  tcsetattr,  tcsendbreak,  tcdrain,  tcflush,  tcflow,
       cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed -
       get and set terminal attributes, line control, get and set baud rate

SYNOPSIS top

       #include <termios.h>
       #include <unistd.h>

       int tcgetattr(int fd, struct termios *termios_p);

       int tcsetattr(int fd, int optional_actions,
                     const struct termios *termios_p);

       int tcsendbreak(int fd, int duration);

       int tcdrain(int fd);

       int tcflush(int fd, int queue_selector);

       int tcflow(int fd, int action);

       void cfmakeraw(struct termios *termios_p);

       speed_t cfgetispeed(const struct termios *termios_p);

       speed_t cfgetospeed(const struct termios *termios_p);

       int cfsetispeed(struct termios *termios_p, speed_t speed);

       int cfsetospeed(struct termios *termios_p, speed_t speed);

       int cfsetspeed(struct termios *termios_p, speed_t speed);

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

       cfsetspeed(), cfmakeraw(): _BSD_SOURCE

DESCRIPTION top

       The termios functions describe a general terminal interface that is
       provided to control asynchronous communications ports.

The termios structure

       Many of the functions described here have a termios_p argument that is a
       pointer to a termios structure.  This structure contains at least the
       following members:

           tcflag_t c_iflag;      /* input modes */
           tcflag_t c_oflag;      /* output modes */
           tcflag_t c_cflag;      /* control modes */
           tcflag_t c_lflag;      /* local modes */
           cc_t     c_cc[NCCS];   /* special characters */

       The values that may be assigned to these fields are described below.  In
       the case of the first four bit-mask fields, the definitions of some of the
       associated flags that may be set are only exposed if a specific feature
       test macro (see feature_test_macros(7)) is defined, as noted in brackets
       ("[]").

       In the descriptions below, "not in POSIX" means that the value is not
       specified in POSIX.1-2001, and "XSI" means that the value is specified in
       POSIX.1-2001 as part of the XSI extension.

       c_iflag flag constants:

       IGNBRK Ignore BREAK condition on input.

       BRKINT If IGNBRK is set, a BREAK is ignored.  If it is not set but BRKINT
              is set, then a BREAK causes the input and output queues to be
              flushed, and if the terminal is the controlling terminal of a
              foreground process group, it will cause a SIGINT to be sent to this
              foreground process group.  When neither IGNBRK nor BRKINT are set, a
              BREAK reads as a null byte ('\0'), except when PARMRK is set, in
              which case it reads as the sequence \377 \0 \0.

       IGNPAR Ignore framing errors and parity errors.

       PARMRK If IGNPAR is not set, prefix a character with a parity error or
              framing error with \377 \0.  If neither IGNPAR nor PARMRK is set,
              read a character with a parity error or framing error as \0.

       INPCK  Enable input parity checking.

       ISTRIP Strip off eighth bit.

       INLCR  Translate NL to CR on input.

       IGNCR  Ignore carriage return on input.

       ICRNL  Translate carriage return to newline on input (unless IGNCR is set).

       IUCLC  (not in POSIX) Map uppercase characters to lowercase on input.

       IXON   Enable XON/XOFF flow control on output.

       IXANY  (XSI) Typing any character will restart stopped output.  (The
              default is to allow just the START character to restart output.)

       IXOFF  Enable XON/XOFF flow control on input.

       IMAXBEL
              (not in POSIX) Ring bell when input queue is full.  Linux does not
              implement this bit, and acts as if it is always set.

       IUTF8 (since Linux 2.6.4)
              (not in POSIX) Input is UTF8; this allows character-erase to be
              correctly performed in cooked mode.

       c_oflag flag constants defined in POSIX.1:

       OPOST  Enable implementation-defined output processing.

       The remaining c_oflag flag constants are defined in POSIX.1-2001, unless
       marked otherwise.

       OLCUC  (not in POSIX) Map lowercase characters to uppercase on output.

       ONLCR  (XSI) Map NL to CR-NL on output.

       OCRNL  Map CR to NL on output.

       ONOCR  Don't output CR at column 0.

       ONLRET Don't output CR.

       OFILL  Send fill characters for a delay, rather than using a timed delay.

       OFDEL  (not in POSIX) Fill character is ASCII DEL (0177).  If unset, fill
              character is ASCII NUL ('\0').  (Not implemented on Linux.)

       NLDLY  Newline delay mask.  Values are NL0 and NL1.  [requires _BSD_SOURCE
              or _SVID_SOURCE or _XOPEN_SOURCE]

       CRDLY  Carriage return delay mask.  Values are CR0, CR1, CR2, or CR3.
              [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]

       TABDLY Horizontal tab delay mask.  Values are TAB0, TAB1, TAB2, TAB3 (or
              XTABS).  A value of TAB3, that is, XTABS, expands tabs to spaces
              (with tab stops every eight columns).  [requires _BSD_SOURCE or
              _SVID_SOURCE or _XOPEN_SOURCE]

       BSDLY  Backspace delay mask.  Values are BS0 or BS1.  (Has never been
              implemented.)  [requires _BSD_SOURCE or _SVID_SOURCE or
              _XOPEN_SOURCE]

       VTDLY  Vertical tab delay mask.  Values are VT0 or VT1.

       FFDLY  Form feed delay mask.  Values are FF0 or FF1.  [requires _BSD_SOURCE
              or _SVID_SOURCE or _XOPEN_SOURCE]

       c_cflag flag constants:

       CBAUD  (not in POSIX) Baud speed mask (4+1 bits).  [requires _BSD_SOURCE or
              _SVID_SOURCE]

       CBAUDEX
              (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD.
              [requires _BSD_SOURCE or _SVID_SOURCE]

              (POSIX says that the baud speed is stored in the termios structure
              without specifying where precisely, and provides cfgetispeed() and
              cfsetispeed() for getting at it.  Some systems use bits selected by
              CBAUD in c_cflag, other systems use separate fields, for example,
              sg_ispeed and sg_ospeed.)

       CSIZE  Character size mask.  Values are CS5, CS6, CS7, or CS8.

       CSTOPB Set two stop bits, rather than one.

       CREAD  Enable receiver.

       PARENB Enable parity generation on output and parity checking for input.

       PARODD If set, then parity for input and output is odd; otherwise even
              parity is used.

       HUPCL  Lower modem control lines after last process closes the device (hang
              up).

       CLOCAL Ignore modem control lines.

       LOBLK  (not in POSIX) Block output from a noncurrent shell layer.  For use
              by shl (shell layers).  (Not implemented on Linux.)

       CIBAUD (not in POSIX) Mask for input speeds.  The values for the CIBAUD
              bits are the same as the values for the CBAUD bits, shifted left
              IBSHIFT bits.  [requires _BSD_SOURCE or _SVID_SOURCE] (Not
              implemented on Linux.)

       CMSPAR (not in POSIX) Use "stick" (mark/space) parity (supported on certain
              serial devices): if PARODD is set, the parity bit is always 1; if
              PARODD is not set, then the parity bit is always 0).  [requires
              _BSD_SOURCE or _SVID_SOURCE]

       CRTSCTS
              (not in POSIX) Enable RTS/CTS (hardware) flow control.  [requires
              _BSD_SOURCE or _SVID_SOURCE]

       c_lflag flag constants:

       ISIG   When any of the characters INTR, QUIT, SUSP, or DSUSP are received,
              generate the corresponding signal.

       ICANON Enable canonical mode (described below).

       XCASE  (not in POSIX; not supported under Linux) If ICANON is also set,
              terminal is uppercase only.  Input is converted to lowercase, except
              for characters preceded by \.  On output, uppercase characters are
              preceded by \ and lowercase characters are converted to uppercase.
              [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]

       ECHO   Echo input characters.

       ECHOE  If ICANON is also set, the ERASE character erases the preceding
              input character, and WERASE erases the preceding word.

       ECHOK  If ICANON is also set, the KILL character erases the current line.

       ECHONL If ICANON is also set, echo the NL character even if ECHO is not
              set.

       ECHOCTL
              (not in POSIX) If ECHO is also set, terminal special characters
              other than TAB, NL, START, and STOP are echoed as ^X, where X is the
              character with ASCII code 0x40 greater than the special character.
              For example, character 0x08 (BS) is echoed as ^H.  [requires
              _BSD_SOURCE or _SVID_SOURCE]

       ECHOPRT
              (not in POSIX) If ICANON and ECHO are also set, characters are
              printed as they are being erased.  [requires _BSD_SOURCE or
              _SVID_SOURCE]

       ECHOKE (not in POSIX) If ICANON is also set, KILL is echoed by erasing each
              character on the line, as specified by ECHOE and ECHOPRT.  [requires
              _BSD_SOURCE or _SVID_SOURCE]

       DEFECHO
              (not in POSIX) Echo only when a process is reading.  (Not
              implemented on Linux.)

       FLUSHO (not in POSIX; not supported under Linux) Output is being flushed.
              This flag is toggled by typing the DISCARD character.  [requires
              _BSD_SOURCE or _SVID_SOURCE]

       NOFLSH Disable flushing the input and output queues when generating signals
              for the INT, QUIT, and SUSP characters.

       TOSTOP Send the SIGTTOU signal to the process group of a background process
              which tries to write to its controlling terminal.

       PENDIN (not in POSIX; not supported under Linux) All characters in the
              input queue are reprinted when the next character is read.  (bash(1)
              handles typeahead this way.)  [requires _BSD_SOURCE or _SVID_SOURCE]

       IEXTEN Enable implementation-defined input processing.  This flag, as well
              as ICANON must be enabled for the special characters EOL2, LNEXT,
              REPRINT, WERASE to be interpreted, and for the IUCLC flag to be
              effective.

       The c_cc array defines the terminal special characters.  The symbolic
       indices (initial values) and meaning are:

       VDISCARD
              (not in POSIX; not supported under Linux; 017, SI, Ctrl-O) Toggle:
              start/stop discarding pending output.  Recognized when IEXTEN is
              set, and then not passed as input.

       VDSUSP (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) Delayed
              suspend character (DSUSP): send SIGTSTP signal when the character is
              read by the user program.  Recognized when IEXTEN and ISIG are set,
              and the system supports job control, and then not passed as input.

       VEOF   (004, EOT, Ctrl-D) End-of-file character (EOF).  More precisely:
              this character causes the pending tty buffer to be sent to the
              waiting user program without waiting for end-of-line.  If it is the
              first character of the line, the read(2) in the user program returns
              0, which signifies end-of-file.  Recognized when ICANON is set, and
              then not passed as input.

       VEOL   (0, NUL) Additional end-of-line character (EOL).  Recognized when
              ICANON is set.

       VEOL2  (not in POSIX; 0, NUL) Yet another end-of-line character (EOL2).
              Recognized when ICANON is set.

       VERASE (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) Erase character
              (ERASE).  This erases the previous not-yet-erased character, but
              does not erase past EOF or beginning-of-line.  Recognized when
              ICANON is set, and then not passed as input.

       VINTR  (003, ETX, Ctrl-C, or also 0177, DEL, rubout) Interrupt character
              (INTR).  Send a SIGINT signal.  Recognized when ISIG is set, and
              then not passed as input.

       VKILL  (025, NAK, Ctrl-U, or Ctrl-X, or also @) Kill character (KILL).
              This erases the input since the last EOF or beginning-of-line.
              Recognized when ICANON is set, and then not passed as input.

       VLNEXT (not in POSIX; 026, SYN, Ctrl-V) Literal next (LNEXT).  Quotes the
              next input character, depriving it of a possible special meaning.
              Recognized when IEXTEN is set, and then not passed as input.

       VMIN   Minimum number of characters for noncanonical read (MIN).

       VQUIT  (034, FS, Ctrl-\) Quit character (QUIT).  Send SIGQUIT signal.
              Recognized when ISIG is set, and then not passed as input.

       VREPRINT
              (not in POSIX; 022, DC2, Ctrl-R) Reprint unread characters
              (REPRINT).  Recognized when ICANON and IEXTEN are set, and then not
              passed as input.

       VSTART (021, DC1, Ctrl-Q) Start character (START).  Restarts output stopped
              by the Stop character.  Recognized when IXON is set, and then not
              passed as input.

       VSTATUS
              (not in POSIX; not supported under Linux; status request: 024, DC4,
              Ctrl-T).  Status character (STATUS).  Display status information at
              terminal, including state of foreground process and amount of CPU
              time it has consumed.  Also sends a SIGINFO signal (not supported on
              Linux) to the foreground process group.

       VSTOP  (023, DC3, Ctrl-S) Stop character (STOP).  Stop output until Start
              character typed.  Recognized when IXON is set, and then not passed
              as input.

       VSUSP  (032, SUB, Ctrl-Z) Suspend character (SUSP).  Send SIGTSTP signal.
              Recognized when ISIG is set, and then not passed as input.

       VSWTCH (not in POSIX; not supported under Linux; 0, NUL) Switch character
              (SWTCH).  Used in System V to switch shells in shell layers, a
              predecessor to shell job control.

       VTIME  Timeout in deciseconds for noncanonical read (TIME).

       VWERASE
              (not in POSIX; 027, ETB, Ctrl-W) Word erase (WERASE).  Recognized
              when ICANON and IEXTEN are set, and then not passed as input.

       An individual terminal special character can be disabled by setting the
       value of the corresponding c_cc element to _POSIX_VDISABLE.

       The above symbolic subscript values are all different, except that VTIME,
       VMIN may have the same value as VEOL, VEOF, respectively.  In noncanonical
       mode the special character meaning is replaced by the timeout meaning.  For
       an explanation of VMIN and VTIME, see the description of noncanonical mode
       below.

Retrieving and changing terminal settings

       tcgetattr() gets the parameters associated with the object referred by fd
       and stores them in the termios structure referenced by termios_p.  This
       function may be invoked from a background process; however, the terminal
       attributes may be subsequently changed by a foreground process.

       tcsetattr() sets the parameters associated with the terminal (unless
       support is required from the underlying hardware that is not available)
       from the termios structure referred to by termios_p.  optional_actions
       specifies when the changes take effect:

       TCSANOW
              the change occurs immediately.

       TCSADRAIN
              the change occurs after all output written to fd has been
              transmitted.  This function should be used when changing parameters
              that affect output.

       TCSAFLUSH
              the change occurs after all output written to the object referred by
              fd has been transmitted, and all input that has been received but
              not read will be discarded before the change is made.

Canonical and noncanonical mode

       The setting of the ICANON canon flag in c_lflag determines whether the
       terminal is operating in canonical mode (ICANON set) or noncanonical mode
       (ICANON unset).  By default, ICANON set.

       In canonical mode:

       * Input is made available line by line.  An input line is available when
         one of the line delimiters is typed (NL, EOL, EOL2; or EOF at the start
         of line).  Except in the case of EOF, the line delimiter is included in
         the buffer returned by read(2).

       * Line editing is enabled (ERASE, KILL; and if the IEXTEN flag is set:
         WERASE, REPRINT, LNEXT).  A read(2) returns at most one line of input; if
         the read(2) requested fewer bytes than are available in the current line
         of input, then only as many bytes as requested are read, and the
         remaining characters will be available for a future read(2).

       In noncanonical mode input is available immediately (without the user
       having to type a line-delimiter character), and line editing is disabled.
       The settings of MIN (c_cc[VMIN]) and TIME (c_cc[VTIME]) determine the
       circumstances in which a read(2) completes; there are four distinct cases:

       * MIN == 0; TIME == 0: If data is available, read(2) returns immediately,
         with the lesser of the number of bytes available, or the number of bytes
         requested.  If no data is available, read(2) returns 0.

       * MIN > 0; TIME == 0: read(2) blocks until the lesser of MIN bytes or the
         number of bytes requested are available, and returns the lesser of these
         two values.

       * MIN == 0; TIME > 0: TIME specifies the limit for a timer in tenths of a
         second.  The timer is started when read(2) is called.  read(2) returns
         either when at least one byte of data is available, or when the timer
         expires.  If the timer expires without any input becoming available,
         read(2) returns 0.

       * MIN > 0; TIME > 0: TIME specifies the limit for a timer in tenths of a
         second.  Once an initial byte of input becomes available, the timer is
         restarted after each further byte is received.  read(2) returns either
         when the lesser of the number of bytes requested or MIN byte have been
         read, or when the inter-byte timeout expires.  Because the timer is only
         started after the initial byte becomes available, at least one byte will
         be read.

Raw mode

       cfmakeraw() sets the terminal to something like the "raw" mode of the old
       Version 7 terminal driver: input is available character by character,
       echoing is disabled, and all special processing of terminal input and
       output characters is disabled.  The terminal attributes are set as follows:

           termios_p->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP
                           | INLCR | IGNCR | ICRNL | IXON);
           termios_p->c_oflag &= ~OPOST;
           termios_p->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
           termios_p->c_cflag &= ~(CSIZE | PARENB);
           termios_p->c_cflag |= CS8;

Line control

       tcsendbreak() transmits a continuous stream of zero-valued bits for a
       specific duration, if the terminal is using asynchronous serial data
       transmission.  If duration is zero, it transmits zero-valued bits for at
       least 0.25 seconds, and not more that 0.5 seconds.  If duration is not
       zero, it sends zero-valued bits for some implementation-defined length of
       time.

       If the terminal is not using asynchronous serial data transmission,
       tcsendbreak() returns without taking any action.

       tcdrain() waits until all output written to the object referred to by fd
       has been transmitted.

       tcflush() discards data written to the object referred to by fd but not
       transmitted, or data received but not read, depending on the value of
       queue_selector:

       TCIFLUSH
              flushes data received but not read.

       TCOFLUSH
              flushes data written but not transmitted.

       TCIOFLUSH
              flushes both data received but not read, and data written but not
              transmitted.

       tcflow() suspends transmission or reception of data on the object referred
       to by fd, depending on the value of action:

       TCOOFF suspends output.

       TCOON  restarts suspended output.

       TCIOFF transmits a STOP character, which stops the terminal device from
              transmitting data to the system.

       TCION  transmits a START character, which starts the terminal device
              transmitting data to the system.

       The default on open of a terminal file is that neither its input nor its
       output is suspended.

Line speed

       The baud rate functions are provided for getting and setting the values of
       the input and output baud rates in the termios structure.  The new values
       do not take effect until tcsetattr() is successfully called.

       Setting the speed to B0 instructs the modem to "hang up".  The actual bit
       rate corresponding to B38400 may be altered with setserial(8).

       The input and output baud rates are stored in the termios structure.

       cfgetospeed() returns the output baud rate stored in the termios structure
       pointed to by termios_p.

       cfsetospeed() sets the output baud rate stored in the termios structure
       pointed to by termios_p to speed, which must be one of these constants:

            B0
            B50
            B75
            B110
            B134
            B150
            B200
            B300
            B600
            B1200
            B1800
            B2400
            B4800
            B9600
            B19200
            B38400
            B57600
            B115200
            B230400

       The zero baud rate, B0, is used to terminate the connection.  If B0 is
       specified, the modem control lines shall no longer be asserted.  Normally,
       this will disconnect the line.  CBAUDEX is a mask for the speeds beyond
       those defined in POSIX.1 (57600 and above).  Thus, B57600 & CBAUDEX is
       nonzero.

       cfgetispeed() returns the input baud rate stored in the termios structure.

       cfsetispeed() sets the input baud rate stored in the termios structure to
       speed, which must be specified as one of the Bnnn constants listed above
       for cfsetospeed().  If the input baud rate is set to zero, the input baud
       rate will be equal to the output baud rate.

       cfsetspeed() is a 4.4BSD extension.  It takes the same arguments as
       cfsetispeed(), and sets both input and output speed.

RETURN VALUE top

       cfgetispeed() returns the input baud rate stored in the termios structure.

       cfgetospeed() returns the output baud rate stored in the termios structure.

       All other functions return:

       0      on success.

       -1     on failure and set errno to indicate the error.

       Note that tcsetattr() returns success if any of the requested changes could
       be successfully carried out.  Therefore, when making multiple changes it
       may be necessary to follow this call with a further call to tcgetattr() to
       check that all changes have been performed successfully.

CONFORMING TO top

       tcgetattr(), tcsetattr(), tcsendbreak(), tcdrain(), tcflush(), tcflow(),
       cfgetispeed(), cfgetospeed(), cfsetispeed(), and cfsetospeed() are
       specified in POSIX.1-2001.

       cfmakeraw() and cfsetspeed() are nonstandard, but available on the BSDs.

NOTES top

       UNIX V7 and several later systems have a list of baud rates where after the
       fourteen values B0, ..., B9600 one finds the two constants EXTA, EXTB
       ("External A" and "External B").  Many systems extend the list with much
       higher baud rates.

       The effect of a nonzero duration with tcsendbreak() varies.  SunOS
       specifies a break of duration * N seconds, where N is at least 0.25, and
       not more than 0.5.  Linux, AIX, DU, Tru64 send a break of duration
       milliseconds.  FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
       duration.  Under Solaris and UnixWare, tcsendbreak() with nonzero duration
       behaves like tcdrain().

SEE ALSO top

       stty(1), console_ioctl(4), tty_ioctl(4), setserial(8)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-08                          TERMIOS(3)


cfree(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CFREE(3)                     Linux Programmer's Manual                    CFREE(3)

NAME top

       cfree - free allocated memory

SYNOPSIS top

       #include <stdlib.h>

       /* In SunOS 4 */
       int cfree(void *ptr);

       /* In glibc or FreeBSD libcompat */
       void cfree(void *ptr);

       /* In SCO OpenServer */
       void cfree(char *ptr, unsigned num, unsigned size);

       /* In Solaris watchmalloc.so.1 */
       void cfree(void *ptr, size_t nelem, size_t elsize);

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

       cfree(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       This function should never be used.  Use free(3) instead.

1-arg cfree

       In glibc, the function cfree() is a synonym for free(3), "added for
       compatibility with SunOS".

       Other systems have other functions with this name.  The declaration is
       sometimes in <stdlib.h> and sometimes in <malloc.h>.

3-arg cfree

       Some SCO and Solaris versions have malloc libraries with a 3-argument
       cfree(), apparently as an analog to calloc(3).

       If you need it while porting something, add

           #define cfree(p, n, s) free((p))

       to your file.

       A frequently asked question is "Can I use free(3) to free memory allocated
       with calloc(3), or do I need cfree()?"  Answer: use free(3).

       An SCO manual writes: "The cfree routine is provided for compliance to the
       iBCSe2 standard and simply calls free.  The num and size arguments to cfree
       are not used."

RETURN VALUE top

       The SunOS version of cfree() (which is a synonym for free(3)) returns 1 on
       success and 0 on failure.  In case of error, errno is set to EINVAL: the
       value of ptr was not a pointer to a block previously allocated by one of
       the routines in the malloc(3) family.

CONFORMING TO top

       The 3-argument version of cfree() as used by SCO conforms to the iBCSe2
       standard: Intel386 Binary Compatibility Specification, Edition 2.

SEE ALSO top

       malloc(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-07-26                            CFREE(3)


man-pages changelog

2.00 2.01 2.02 2.03 2.04 2.05 2.06 2.07 2.08 2.09 2.10 2.11 2.12 2.13 2.14 2.15 2.16 2.17 2.18 2.19 2.20 2.21 2.22 2.23 2.24 2.25 2.26 2.27 2.28 2.29 2.30 2.31 2.32 2.33 2.34 2.35 2.36 2.37 2.38 2.39 2.40 2.41 2.42 2.43 2.44 2.45 2.46 2.47 2.48 2.49 2.50 2.51 2.52 2.53 2.54 2.55 2.56 2.57 2.58 2.59 2.60 2.61 2.62 2.63 2.64 2.65 2.66 2.67 2.68 2.69 2.70 2.71 2.72 2.73 2.74 2.75 2.76 2.77 2.78 2.79 2.80 3.00 3.01 3.02 3.03 3.04 3.05 3.06 3.07 3.08 3.09 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 3.20 3.21 3.22 3.23 3.24 3.25 3.26 3.27 3.28 3.29 3.30 3.31 3.32 3.33 3.34 3.35 3.36 3.37 3.38 3.39 3.40 3.41 3.42 3.43 3.44 3.45

top

==================== Changes in man-pages-2.00 ====================

Released: 2004-12-16

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alberto Bertogli
Anand Kumria
Andrey Kiselev
Andries Brouwer
Chris Green
Branden Robinson
Emmanuel Colbus
Enrico Zini
Eric Estievenart
Fabian Kreutz
Florian Weimer
Jan Kuznik
Joey (Martin) Schulze
Johannes Berg
John V. Belmonte
Karel Kulhavy
Luis Javier Merino MorÃ¡n
Martin Pool
Richard Kreckel
Vasya Pupkin

Apologies if I missed anyone!

Global changes
--------------

Various pages
    Fabian Kreutz
        Many math pages had their synopses compressed, as per suggestion
        from Fabian Kreutz.

Various pages
    Fabian Kreutz / aeb
        Many minor content and formatting bug fixes were made to the math
        pages, following suggestions from Fabian Kreutz (who recently
        translated many of the 1.70 math pages into German) and
        Andries Brouwer.

Various pages
    mtk
        For consistency, all instances of "super-user" were changed
        to the more common "superuser".

Various pages
    Vasya Pupkin / mtk
        After a note from Vasya Pupkin, I added <errno.h> to the SYNOPSIS
        of several Section 2 pages using the _syscallN() macros.

        In addition:
            -- erroneous semicolons at the end of _syscallN() were removed
               on various pages.

            -- types such as "uint" in syscallN() declarations were changed
               to "unsigned int", etc.

            -- various other minor breakages in the synopses were fixed.

        The affected pages are:

                getdents.2
                gettid.2
                llseek.2
                mmap2.2
                modify_ldt.2
                pivot_root.2
                quotactl.2
                readdir.2
                sysctl.2
                syslog.2
                tkill.2

Typographical or grammatical errors have been corrected in several
other places.

Changes to individual pages
---------------------------

bind.2
    Florian Weimer
        Added 'const' to declaration of 'my_addr' in prototype.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239762.

fcntl.2
    Martin Pool
        Added O_NOATIME to list of flags that can be changed via F_SETFL.
    mtk/aeb
        Noted F_GETOWN bug after suggestion from aeb.
        See also:
        http://marc.theaimsgroup.com/?l=linux-kernel&m=108380640603164&w=2

getrlimit.2
    mtk
        Material on getrusage.2 has been separated out into its own page.
        Rewrote discussion on RLIMIT_MEMLOCK to incorporate kernel
        2.6.9 changes.
        Added note on RLIMIT_CPU error in older kernels.
        Added RLIMIT_SIGPENDING.
        Also made a few other minor changes.

getrusage.2
    mtk
        This page is new(ish) -- it was created by splitting
        getrlimit.2.

        Repaired note on SIGCHLD behavior to note that the
        POSIX non-conformance has been fixed in 2.6.9.

kill.2
    Modified after suggestion from Emmanuel Colbus
        Changed wording of sentence under NOTES describing
        when signals can be sent to init(1).

mlock.2
munlock.2
mlockall.2
munlockall.2
        These have been consolidated into a single mlock.2 page.
        In the process, much duplication was eliminated
        and new information was added about RLIMIT_MEMLOCK
        and the changes in memory locking in kernel 2.6.9,

mmap.2
    mtk
        Added cross-ref to setrlimit(2) concerning memory locking limits.
    Eric Estievenart
        Note that MAP_FIXED replaces existing mappings

msgctl.2
    mtk
        Substantial language and formatting clean-ups.
        Added msqid_ds and ipc_perm structure definitions.

msgget.2
    mtk
        Substantial language and formatting clean-ups.
        Added notes on /proc files.

msgop.2
    mtk
        Substantial language and formatting clean-ups.
        Added notes on /proc files.

open.2
    Martin Pool
        Added O_NOATIME (new in Linux 2.6.8)
    mtk
        Reordered list of 'flags' description alphabetically

personality.2
    2004-11-03 applied patch from Martin Schulze

semctl.2
    mtk
        Substantial language and formatting clean-ups.
        Rewrote semun text.
        Added semid_ds and ipc_perm structure definitions.

semget.2
    mtk
        Substantial language and formatting clean-ups.
        Added notes on /proc files.
        Rewrote BUGS note about semget()'s failure to initialize
        semaphore values.

semop.2
    mtk
        Substantial language and formatting clean-ups.
        Added notes on /proc files.

shmctl.2
    mtk
        Substantial language and formatting clean-ups.
        Updated shmid_ds structure definitions.
        Added information on SHM_DEST and SHM_LOCKED flags.
        Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
        since kernel 2.6.9.
        Added notes on 2.6.9 RLIMIT_MEMLOCK changes.
        Added RLIMIT_SIGPENDING (new in Linux 2.6.8)

shmget.2
    mtk
        Substantial language and formatting clean-ups.
        Added notes on /proc files.

shmop.2
    mtk
        Substantial language and formatting clean-ups.
        Changed wording and placement of sentence regarding attachment
        of segments marked for destruction.

sigaction.2
    mtk
        Added mention of SIGCONT under SA_NOCLDSTOP.
        Added SA_NOCLDWAIT.
        Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
        Noted that CLD_CONTINUED is supported since Linux 2.6.9.
        Added SI_TKILL (new in Linux 2.4.19).
        Other minor changes.

signal.2
    mtk
        Removed text on ignoring SIGCHLD; replaced with pointer
        to sigaction.2.

sigwaitinfo.2
    After bug report from Andrey Kiselev
        Fixed prototype: "timeout" --> "*timeout"
        as per: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=222145

stat.2
    Enrico Zini
        Added text to clarify that S_IS*() macros should be applied to
        st_mode field.
        as per: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=249698

swapon.2
    After Debian bug report from Anand Kumria
        Added "no swap space signature" to EINVAL error.
    mtk
        Added EINVAL error for swapoff() ("not currently a swap area").
        Added EBUSY error for swapon().
        A few formatting fixes.

times.2
    mtk
        In Linux 2.6, the return value of times changed; it is no
        longer time since boot, but rather:

            boot_time + 2^32 / HZ - 300

        Repaired note on SIGCHLD behavior to note that the
        POSIX non-conformance has been fixed in 2.6.9.
        Some formatting fixes.

undocumented.2
    After bug report from Johannes Berg
        Changed
            .TH UNIMPLEMENTED
        to:
            .TH UNDOCUMENTED
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=220741

wait.2
    mtk
        Added waitid(2).
        Added WCONTINUED and WIFCONTINUED (new in 2.6.10).
        Added text on SA_NOCLDSTOP.
        Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior.
        Much other text rewritten.

wait4.2
    mtk
        Rewrote this page, removing much duplicated information,
        and replacing with pointers to wait.2.
    Luis Javier Merino MorÃ¡n / mtk
        CONFORMING TO said "SVr4, POSIX".  Changed to "4.3BSD"

waitid.2
    mtk
        New link to wait.2

assert.3
    After bug report from Branden Robinson
        The assert() failure message goes to stderr not stdout.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=284814

ctime.3
    mtk
        Noted that 0 in tm_mday is interpreted to mean the last day
        of the preceding month.

getnameinfo.3
    http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=229618
        getnameinfo() does not set errno, it returns a non-zero
        value indicating the error.
    mtk
        added EAI_OVERFLOW error

killpg.3
    mtk
        Minor changes to SEE ALSO and CONFORMING TO.

lseek64.3
    aeb
        New page by Andries Brouwer

tzset.3
    Richard Kreckel
        Change "NULL" to "empty" when talking about the value of TZ.
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=601

printf.3
    After bug report from Jan Kuznik
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=205736
        Fixed bad realloc() use in snprintf() example

realpath.3
    mtk
        Added discussion of resolved_path == NULL.

random.4
    After bug report from John V. Belmonte
        Updated init and quit scripts to reflect kernel 2.4/2.6 reality
        (Scripts taken from drivers/char/random.c)
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=247779

proc.5
    mtk
        Updated description of /proc/loadavg to include
        nr_running(), nr_threads, last_pid.

        rtsig-max and rtsig-nr went away in 2.6.8

        updated statm, and fixed error in order of list

boot.7
    applied patch from Martin Schulze

capabilities.7
    mtk
        Added O_NOATIME for CAP_FOWNER

netdevice.7
    Karel Kulhavy and AEB
        Formatting fix after note from Karel Kulhavy and AEB, plus a
        few wording fixes.

signal.7
    mtk
        /proc/sys/kernel/rtsig-* were superseded by RLIMIT_SIGPENDING
        in kernel 2.6.8.

tcp.7
    mtk/aeb
        Updated details of interaction of TCP_CORK and TCP_NODELAY.
top
==================== Changes in man-pages-2.01 ====================

Released: 2004-12-20

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Carsten Hey
Johannes Berg
Joshua Kwan
Marek Habersack
Martin Schulze
Matthew Dempsky
Matthew Gregan
Pedro Zorzenon Neto
Tony Crawford

Apologies if I missed anyone!

Global changes
--------------

accept.2
close.2
send.2
setsid.2
socket.2
closedir.3
initgroups.3
mkstemp.3
opendir.3
readdir.3
telldir.3
    Matthew Dempsky, mtk
        triggered by http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=283179
        The wording describing how errno is set was fixed up in these pages.

Typographical or grammatical errors have been corrected in several
other places.

Changes to individual pages
---------------------------

sendfile.2
    mtk
        Adjusted descriptions of argument file types to be closer to
        2.6 reality.
        Wording and formatting changes.

ctan.3
ctanh.3
    Tony Crawford
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=270817
        Formulae on the pages should be T = S / C not T = C / S.

errno.3
    Martin Schulze, mtk
        Removed errno declaration from prototype, added notes
        on historical need for this declaration.
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=174175

aio_return.3
    as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=224953
        Changed erroneous "aio_return(2)" to "aio_return(3)".

posix_openpt.3
    mtk
        New by mtk

ptsname.3
    mtk
        Added description of ptsname_r().
        Added ERRORS.

ptsname_r.3
    mtk
        New link to ptsname.3.

shm_open.3
    Matthew Gregan
        add <fcntl.h> to synopsis
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=271243

strcasecmp.3
    Marek Habersack
            .SH "CONFORMING TO"
            -BSD 4.4
            +BSD 4.4, SUSv3
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=234443

strfry.3
    Joshua Kwan
        Added _GNU_SOURCE to prototype
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=213538

strftime.3
    Cartsen Hey
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=276248

        Changed range for "%S" from 0..61 to 0..60.

        SUSv3 says 0..60.  I think the manual page probably says
        0..61, because that's what SUSv2 said.
        (Some other implementations' man pages also say 0..61 --
        e.g., Solaris 8 & 9, Tru64 5.1B; FreeBSD 5.1 says 0..60.)

        The glibc manual currently says 0..60.

        Given that SUSv3 says 0..60, I've changed the
        manual page to also say this:

            -The second as a decimal number (range 00 to 61).
            +The second as a decimal number (range 00 to 60).
            +(The range is up to 60 to allow for occasional leap seconds.)

sysconf.3
    Johannes Berg
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=226974
        -.BR POSIX2_FORT_RUN " - " _SC_2_FORT_DEV
        +.BR POSIX2_FORT_DEV " - " _SC_2_FORT_DEV

system.3
    Pedro Zorzenon
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=242638
        Noted use of _XOPEN_SOURCE to get macros from <stdlib.h>
        for wait(2).

    mtk
        Changed name of argument from 'string' to 'command' (like POSIX).

        Noted that glibc does nowadays explicitly check for the existence
        of the shell if 'command' is NULL, rather than the older behavior
        of assuming the shell exists and always returning 1 if
        'command' is NULL.

        Other wording and formatting clean-ups.

undocumented.3
    Remove some functions names that *are* documented.
top
==================== Changes in man-pages-2.02 ====================

Released: 2005-04-14

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Branden Robinson
Colin Watson
David Lloyd
Gordon Jin
Heikki Orsila
Jamie Lokier
Johan Walles
Kai Makisara
Marko Kohtala
Martin Pool
Martin (Joey) Schulze
Matthias Lang
Michael Haardt
Michael MÃ¼hlebach
Mike Frysinger
Sasa Stevanovic
Serguei Leontiev

Apologies if I missed anyone!

Global changes
--------------

ctime.3
tzselect.8
zdump.8
zic.8
    Martin (Joey) Schulze
        Removed SEE ALSO reference to nonexistent newctime(3).
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=236884

Typographical or grammatical errors have been corrected in several
other places.

Changes to individual pages
---------------------------

clone.2
    mtk
        Noted the PID caching behavior of NPTL's getpid()
        wrapper under BUGS.

        Added futex(2), set_thread_area(2), set_tid_address(2),
        tkill(2) under SEE ALSO.

epoll_ctl.2
epoll_create.2
    Marko Kohtala  / mtk
        Improved various error descriptions.

epoll_wait.2
    David Lloyd / Mike Frysinger, Marko Kohtala
        Added EINTR to errors.

fcntl.2
    Jamie Lokier / mtk
        Improved discussion of F_SETOWN and F_SETSIG with respect to
        multi-threaded programs.
        Generally cleaned up the discussion of F_SETOWN.

        Updated CONFORMING TO to note that F_GETOWN and F_SETOWN are
        now in POSIX.

link.2
    mtk
        Noted discrepancy between Linux and POSIX.1 when oldpath
        is a symbolic link.
        See: http://bugs.linuxbase.org/show_bug.cgi?id=367
        and: http://www.opengroup.org/austin/mailarchives/ag/msg08152.html

    Michael Haardt / mtk
        Clarified EXDEV error description: it isn't possible to link
        across mount points, even if the mount points refer to the same
        file system.

mincore.2
    mtk, after note from Gordon Jin
        Updated ERRORS.

pipe.2
    As per message from Serguei Leontiev
        Removed SVr2, AT&T, and BSD from CONFORMING TO, since
        a pipe on those systems is actually bidirectional.
        (Pipes are implemented as STREAMS on the former, and
        sockets on the latter.)

posix_fadvise.2
    mtk
        Noted kernel version where posix_fadvise() appeared and
        noted bug in handling of 'len' in kernels < 2.6.6.

rename.2
    Michael Haardt
        Clarified EXDEV error description: it isn't possible to rename
        a file across mount points, even if the mount points refer to
        the same file system.

semop.2
    mtk
        Noted kernel version numbers for semtimedop().

setitimer.2
    Matthias Lang, mtk
        Noted MAX_SEC_IN_JIFFIES ceiling.
        Added note about treatment of out-of-range tv_usec values.

sigqueue.2
    Johan Walles, Martin (Joey) Schulze
        Added sigqueue.2 to SEE ALSO.

times.2
    mtk
        Added notes on non-standard behavior: Linux allows 'buf' to
        be NULL, but POSIX.1 doesn't specify this and it's non-portable.

uselib.2
    Andries Brouwer
        Improved DESCRIPTION; clarified distinction between
        EACCES and ENOEXEC.

bcopy.3
    Heikki Orsila
        bcopy() handles overlapping case, but memcpy() does not,
        so for consistency memmove() should be also mentioned.

getmntent_r.3
    Martin (Joey) Schulze
        New link to man3/getmntent.3.

memcpy.3
    Small wording change after suggestion from Sasa Stevanovic.

strcasestr.3
    mtk
        Created as link to strstr.3.

strftime.3
    mtk
        Noted that SUSv2 allowed a range of 00 to 61 for %S specifier.

strstr.3
    mtk
        Added description of strcasestr().

random.4
    aeb
        Improved description of read from /dev/urandom.

st.4
    Kai Makisara
        Substantial updates.

man.7
    Martin Schulze
    Branden Robinson
    Colin Watson
        Mention the .URL macro more verbosely.
top
==================== Changes in man-pages-2.03 ====================

Released: 2005-06-02

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Joey (Martin) Schulze
Johannes Nicolai
Justin Pryzby
Klaus Ethgen
Pavel Heimlich
Ross Boylan
Vincent Fourmond

Apologies if I missed anyone!

Global changes
--------------

console.4
console_ioctl.4
mouse.4
tty.4
vcs.4
    Pavel Heimlich
        Change `ttys(4)' to `ttyS(4)'.

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

clone.2
    mtk
        Substantially enhanced discussion of CLONE_THREAD.

        Added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED.

        Other minor fixes.

execve.2
    aeb
        Noted effect of ptracing when execing a set-UID program.

fcntl.2
    Johannes Nicolai / mtk
        Noted F_SETOWN bug for socket file descriptor in Linux 2.4
        and earlier.

        Added text on permissions required to send signal to owner.

flock.2
    mtk
        Noted that lock conversions are not atomic.

getrusage.2
    mtk
        ru_nswap has never contained useful information.
        Kernel 2.6.6 clarified that with a patch
        ("[PATCH] eliminate nswap and cnswap").  See also:
        http://www.ussg.iu.edu/hypermail/linux/kernel/0404.1/0720.html

kill.2
    mtk
        Clarified wording of the 'pid == -1' case.

mount.2
    mtk
        Added MNT_EXPIRE, plus a few other tidy-ups.

sched_setaffinity.2
    mtk
        Added text to note that sched_setaffinity() will migrate the
        affected process to one of the specified CPUs if necessary.

        Added a NOTE to point out that the affinity mask is actually a
        per-thread attribute that can be adjusted independently for
        each thread in a thread group.

shmctl.2
    mtk
        Noted aberrant Linux behavior with respect to new attaches to a
        segment that has already been marked for deletion.

        Noted changes in permissions required for SHM_LOCK/SHM_UNLOCK.

wait.2
    mtk
        Noted that the __W* flags can't be used with waitid().

confstr.3
    mtk
        Added _CS_GNU_LIBC_VERSION and _CS_GNU_LIBPTHREAD_VERSION.

hosts.5
    Ross Boylan / Martin Schulze
        various changes as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=304242

proc.5
    mtk
        Minor changes to discussion of /proc/PID/stat signal fields.
        Added 'rt_priority' and 'policy' to /proc/PID/stat.

capabilities.7
    mtk
        1,$s/inherited/inheritable/g

regex.7
    Vincent Fourmond / Joey (Martin) Schulze
        Removed discussion of `[[:<:]]' and `[[:>:]]' since they do
        not seem to be in the glibc implementation.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666

tzselect.8
    Joey (Martin) Schulze / Klaus Ethgen
        The default zoneinfo directory is now /usr/share/zoneinfo.
        (was: /usr/local/etc/zoneinfo)
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267471
top
==================== Changes in man-pages-2.04 ====================

Released: 2005-06-21

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Baurjan Ismagulov
Dave Love
Dieter Brueggemann
Geoff Clare
Guido Trotter
kabloom
Kevin Ryde
Justin Pryzby
Mike Furr
Olivier Croquette
Olivier Guilyardi
Peter Cordes
Philipp Spitzer
Tanaka Akira
Thierry Excoffier
Thomas Hood
Vincent Lefevre
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        For consistency across pages:

            1,$s/nonzero/non-zero/g

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

pthreads.7
    mtk
        An overview of the Linux implementations of POSIX threads.

Changes to individual pages
---------------------------

_exit.2
    mtk
        Various minor changes.

epoll_ctl.2
    Mike Furr
        BUGS: In kernels < 2.6.9, EPOLL_CTL_DEL required a non-NULL
        'event', even though this argument is ignored.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306517

flock.2
    mtk / Kevin Ryde
        Clarified semantics of relationship between flock() locks
        and open file entries and file descriptors.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=291121

getitimer.2
    Olivier Croquette, Thierry Excoffier
        Noted the existence of the short sleep bug (up to 1 jiffy).

getrlimit.2
    mtk
        RLIMIT_RSS only has affect "in 2.4.x", not "in 2.4 and later".

getrusage.2
    Geoff Clare
        Since Linux 2.6, the ru_nvcsw and ru_nivcsw fields are used.

nice.2
    mtk / Guido Trotter
        Rewrote description of return value.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=296183

open.2
    Walter Harms
        O_DIRECT needs _GNU_SOURCE.
    mtk
        O_ASYNC works for pipes and FIFOs in Linux 2.6.
        Various minor fixes.

atexit.3
    mtk
        Various minor changes.

exit.3
    mtk
        Various minor changes.

getopt.3
    mtk / Philipp Spitzer
        Fix description of return value.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=308359

hsearch.3
    mtk
        Changed (char *) to (void *) in example.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=313607

log1p.3
    Justin Pryzby
        Make log(3) SEE ALSO log1p(3),
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=309578

makecontext.3
    Tanaka Akira
        Fix description of RETURN VALUE for makecontext(),
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=311800

on_exit.3
    mtk
        Various minor changes.

rand.3
    kabloom
        Small fix to a code example,
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=194842

realpath.3
    mtk / Thomas Hood
        When specifying resolved_path as NULL, realpath()
        will (still) only allocate up to PATH_MAX bytes.
        Plus other minor changes.
        See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239424

rcmd.3
    Dave Love
        The required header file for these functions on Linux is <netdb.h>,
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=311680

scanf.3
    Olivier Guilyardi
        Arg for %p is a pointer to _a pointer to_ void,
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=263109

stdin.3
    Vincent Lefevre
        freopen() can change the descriptors associated with
        stdin/stdout/stderr, as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295859

strerror.3
    Baurjan Ismagulov
        strerror_r(3) requires #define _XOPEN_SOURCE 600,
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=290880

sysconf.3
    Peter Cordes / mtk
        Fix typo: "_SC_2_DEV" should be "_SC_2_C_DEV".

proc.5
    mtk
        Added pointers under /proc/sys/net to tcp.7 and ip.7.

ip.7
    mtk
        Various wording and formatting fixes.
        Reordered /proc/sys/net/ipv4/ip_* file descriptions alphabetically.

tcp.7
    Dieter Brueggemann / mtk
        Fixes to the discussion of SIOCATMARK and tcp_stdurg.
    mtk
        Various wording and formatting fixes.
        Incorporated some new /proc/sys/net/ipv4/tcp_* file descriptions
        from the 2.6.12 source file Documentation/networking/ip-sysctl.txt.
top
==================== Changes in man-pages-2.05 ====================

Released: 2005-06-27

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

A Costa
Andries Brouwer
Bas Zoetekouw
Dan Jacobson
Delian Krustev
Dora Anna Volgyesi
Martin (Joey) Schulze
Ove Kaaven

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.  (Special thanks to A Costa.)

Changes to individual pages
---------------------------

_exit.2
    mtk / aeb
        Reversed 2.04 introduction of the term "process termination
        function".

close.2
    mtk
        Clarified what type of lock close() affects.
        Minor formatting changes.

dup.2
    mtk
        Consistent use of terms "open file description",
        "file status flags", and "file descriptor flags".
        Removed mention of lock sharing -- it was not accurate.
        Minor formatting fixes.

fcntl.2
    mtk
        Consistent use of terms "open file description",
        "file status flags", and "file descriptor flags".
        Some rewriting of discussion of file descriptor flags
        Under F_DUPFD, replaced some text duplicated in dup.2
        with a cross ref to dup.2
        Minor wording and formatting fixes.

fpclassify.3
    mtk / Martin (Joey) Schulze / Bas Zoetekouw
        The return value of isinf() changed in glibc 2.02
        to differentiate positive and negative infinity.
        See: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=285765

getgid.2
getuid.2
    Delian Krustev
        Remove confusing text describing real and effective IDs.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=285852

getitimer.2
    mtk
        The short sleep bug (up to 1 jiffy) that was newly noted in
        man-pages-2.04 has just been fixed in 2.6.12.

getpriority.2
    mtk
        Changed range documented in main text from -20..20 to -20..19.
        Noted that the range is -20..20 on some systems.

open.2
    mtk / aeb
        Clarification of term "open file description" along with
        explanation of what information it maintains.
        Other wording improvements.
        Various minor wording changes.

atexit.3
    mtk / aeb
        Reversed 2.04 introduction of the term "process termination
        function".
    mtk
        Noted use of atexit() for establishing function to be invoked on
        shared library unload.
        Noted that atexit()-registered functions are not invoked on
        abnormal termination.
        Formatting fixes.

exit.3
    mtk / aeb
        Reversed 2.04 introduction of the term "process termination
        function".
    mtk
        Minor rewording and formatting changes.

getloadavg.3
    mtk
        Added #define _BSD_SOURCE to prototype.

log2.3
    Martin (Joey) Schulze
        Add ERANGE error.

readdir.3
    mtk
        Added definition of Linux dirent structure.
        Some formatting cleanups.

strtod.3
    Dora Anna Volgyesi / mtk
        strtold() and strtof() need _ISOC99_SOURCE or _XOPEN_SOURCE=600
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=246668

tdestroy.3
    mtk
        New link to tsearch.3.

tsearch.3
    mtk
        Added tdestroy to .TH line.

mem.4
    mtk
        Change "chown root:mem /dev/mem" to "chown root:kmem /dev/mem".

null.4
    mtk
        Change "chown root:mem /dev/null /dev/zero" to
        "chown root:root /dev/null /dev/zero".

vcs.4
    Dan Jacobson / Martin (Joey) Schulze
        Replaced "selection(1)" by "gpm(8)" under SEE ALSO
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=253515

signal.7
    Ove Kaaven
        SA_SIGACTION should be SA_SIGINFO
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=305369

urn.7
    mtk
        New link to uri.7
top
==================== Changes in man-pages-2.06 ====================

Released: 2005-07-15

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andries Brouwer
Bhavesh P Davda
Clau Weber
Dov Murik
David Lloyd
Frederik Deweerdt
Justin Pryzby
Lars Wirzenius
Martin Pool
Mike Frysinger
Petter Reinholdtsen
Steven Murdoch
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Many uses of hyphens and dashes were corrected.

New pages
---------

canonicalize_file_name.3
    Walter Harms / mtk

Removed Pages
-------------

sstk.2
    mtk
        AFAIK, this system call has never actually done anything (other
        than be a stub) on any Unix.

Changes to individual pages
---------------------------

accept.2
    mtk
        Various wording and formatting fixes.

bind.2
    mtk
        Minor formatting changes

clone.2
    mtk
        Various minor wording improvements; some formatting fixes

connect.2
    mtk
        Various wording and formatting fixes.

epoll_create.2
    Bhavesh P Davda
        s/positive/non-negative/      [for file descriptor]

getrlimit.2
    mtk
        Documented RLIMIT_MSGQUEUE limit.
        RLIMIT_RSS ceased to have any effect in 2.4 in kernel 2.4.30.
        (It already didn't have any effect in 2.2.x and 2.6.x.)
        s/MADVISE_WILLNEED/MADV_WILLNEED/

listen.2
    mtk
        Removed historic comment on BSD backlog ceiling.
        Minor wording and formatting changes.

semop.2
    mtk
        Added BUG: in some circumstances, a process that is
        waiting for a semaphore to become zero is not not woken
        up when the value does actually reach zero.
        http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
        http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2

socket.2
    mtk
        Various minor wording improvements

umask.2
    mtk
        Added mkdir(2) to discussion, made term "file mode creation
        mask" clearer.
        Various, mostly small, wording changes

errno.3
    Martin Pool
        Change description for ESTALE
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=237344

fgetgrent.3
getgrent.3
getgrent_r.3
    David Lloyd
        Added SEE ALSO putgrent(3)
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=211336

getgrent.3
getgrnam.3
getpwent.3
getpwnam.3
    Lars Wirzenius / mtk
        Replace mention of /etc/{passwd,group} by references to
        "passwd/group database", and LDAP and NIS.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=316117
    mtk
        Miscellaneous wording improvements
        Consistent DESCRIPTION and ERRORS wording across these pages.

getnameinfo.3
    mtk
        Relocate misplaced text describing gai_strerror().

getnetent.3
    Petter Reinholdtsen
        s/endservent/endnetent/
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=316517

getspnam.3
    Lars Wirzenius / mtk
        Replace mention of /etc/shadow by references to
        "shadow password database", and LDAP and NIS.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=316117
    mtk, Claus Weber
        Miscellaneous wording improvements
        Consistent DESCRIPTION wording vis-a-vis getpwnam.3 etc.

hsearch.3
    Frederik Deweerdt
        Fix hsearch_r() prototype

scanf.3
    Justin Pryzby / mtk
        Fix description of RETURN VALUE
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=317037
    mtk
        various parts substantially rewritten; added description of
        %n$ form; various text incorporated from the GNU C library
        documentation ((C) The Free Software Foundation).

shm_open.3
    mtk
        Modified details of how user and group ownership of a new
        object are set.
        Various minor wording and formatting cleanups.

elf.5
    Mike Frysinger
        tweaked the short description to include definition of 'ELF'
        add ELFOSABI_NONE to the ELFOSABI_ list
        tweak/add more machines to EM_ list for ehdr->e_machine
        fix indenting to be consistent
        tweak the display of the ELF_ST_* macros
        document the Elf_Dyn structure

proc.5
    mtk
        Updated discussion of /proc/stat.
        Added text on the /proc/sys/fs/mqueue/* files.

ip.7
    Steven Murdoch
        Change protocol in UDP prototype.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=182635

tcp.7
    Dov Murik
        The first sentence under NOTES about SO_KEEPALIVE and SIGPIPE
        makes no grammatical sense (and possibly also no technical sense).
        It has been removed.
top
==================== Changes in man-pages-2.07 ====================

Released: 2005-07-19

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Mike Frysinger

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        The terms "set-user-ID" and "set-group-ID" are now used
        consistently (no abbreviations) across all manual pages.

Various pages
    mtk
        Consistent use of "saved set-user-ID" and "saved set-group-ID"
        (no more "saved user ID", "saved effective UID",
        saved group ID", etc.)

Various pages
    mtk
        Global fixes in textual descriptions:

            uid --> UID
            gid --> GID
            pid --> PID
            id --> ID

Various pages
    mtk
        Consistent use of st_atime, st_ctime, st_mtime, with
        explanatory text, instead of atime/ctime/mtime.

Various pages
    mtk
        Classical BSD versions are now always named x.yBSD (formerly
        there was a mix of x.yBSD and BSD x.y).

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

setresuid.2
    mtk
        Some rewording.

stat.2
    Mike Frysinger
        Improve description of st_dev and st_rdev.
    mtk
        Various wording and formatting improvements.

truncate.2
    mtk
        Some formatting fixes
top
==================== Changes in man-pages-2.08 ====================

Released: 2005-09-21

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Adrian Bunk
Alain PORTAL
Andrew Pimlott
Andries Brouwer
Baurzhan Ismagulov
Bernhard R. Link
Bodo Stroesser
David N. Welton
Dov Murik
Heikki Orsila
Hasso Tepper
Hrvoje Niksic
Justin Pryzby
Ludovic Courtes
Mike Frysinger
Nicolas François
Norbert Buchmuller
Paul Brook
Ramiro Aceves
Tommy Pettersson
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        RFC references are now always written as "RFC\ nnn"
        (not "RFC nnn" or "RFCnnn").

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

du.1
    Mike Frysinger
        To get an effect like "-h", BLOCKSIZE must start with "human",
        not "HUMAN".

time.1
    Mike Frysinger
        s/standard output/standard error/

clone.2
    Paul Brook / mtk
        Fix small error in description of CLONE_PARENT_SETTID

connect.2
    Heikki Orsila
        Add EINTR error
        See http://lkml.org/lkml/2005/7/12/254

getpriority.2
    mtk
        Expanded discussion of relationship between user and kernel
        representations of the nice value.

        Added discussion of RLIMIT_NICE and a cross reference to
        getrlimit.2 under the description of the EACCES error.

        Noted 2.6.12 change in credentials checking for setpriority().

getrlimit.2
    mtk
        Added description of RLIMIT_RTPRIO

        Added description of RLIMIT_NICE

mmap.2
    mtk
        Noted bug in MAP_POPULATE for kernels before 2.6.7.

mremap.2
    mtk
        Added _GNU_SOURCE to prototype.
        Rewrote description of MREMAP_MAYMOVE.
        Rewrote description of EAGAIN error.
        Added discussion of resizing of memory locks.
        Added entries to SEE ALSO.
        Some formatting fixes.

msgctl.2
    mtk
        Added IPC_INFO, MSG_INFO, MSG_STAT descriptions.

nanosleep.2
    Baurzhan Ismagulov
        Add to prototype: define _POSIX_C_SOURCE 199309
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=314435

nice.2
    mtk
        Added sentence noting that range of the nice value is described
        in getpriority.2.
        Added cross-reference to setrlimit(2) for discussion on
        RLIMIT_NICE.

outb.2
    David N. Welton / Justin Pryzby / mtk
        Clarified the order of value and port arguments;
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=263756

pause.2
    mtk
        Added SEE ALSO for sigsuspend.2
        Some formatting fixes.

poll.2
    Tommy Pettersson
        nfds should be prototyped as nfds_t
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=322934

    mtk
        Some wording and formatting improvements.

prctl.2
    mtk
        Since kernel 2.6.13 PR_SET_DUMPABLE can also have the value 2.

rand.3
    Hrvoje Niksic / mtk
        Remove misleading text describing FreeBSD's sranddev() function.
        As per debian bug 328629

readv.2
    mtk / Walter harms
        Added LINUX NOTES on trickery performed by glibc when
        vector size exceeds IOV_MAX.

        Formatting clean-ups.

remap_file_pages.2
    mtk
        Added text to note that start and size are both rounded downward.

sched_setparam.2
    mtk
        Modified discussion of privileges; added pointer to
        sched_setscheduler.2 for a discussion of privileges and
        resource limits.

sched_setscheduler.2
    mtk
        Modified discussion of privileges; added discussion of RLIMIT_RTPRIO.

semctl.2
    mtk
        Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.

shmctl.2
    mtk
        Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.

sigaction.2
    mtk
        Split sigpending(), sigprocmask(), and sigsuspend() out
        into separate new pages.

        Other minor changes

    mtk
        NOTES: described SA_NODEFER / sa_mask bug which was present in
                all kernels up to and including 2.6.13.
        See http://marc.theaimsgroup.com/?l=linux-kernel&m=112360948603171&w=2
        and http://marc.theaimsgroup.com/?l=linux-kernel&m=112362164911432&w=2
        List:       linux-kernel
        Subject:    Signal handling possibly wrong
        From:       Bodo Stroesser
        Date:       2005-08-09 17:44:06

signal.2
    mtk
        Updated SEE ALSO to reflect splitting of sigaction.2 into
        sigaction.2, sigsuspend.2, sigpending.2, sigprocmask.2

sigpending.2
    mtk
        New page created by splitting out from sigaction.2
        Changed CONFORMING TO.

sigprocmask.2
    mtk
        New page created by splitting out from sigaction.2
        Added text on effect of NULL for 'set' argument.
        Added text noting effect of ignoring SIGBUS, SIGFPE, SIGILL,
                and SIGSEGV.
        Noted that sigprocmask() can't be used in multithreaded process.
        Fixed EINVAL error diagnostic.
        Changed CONFORMING TO.

sigsuspend.2
    mtk
        New page created by splitting out from sigaction.2
        Added NOTES on usage.
        Added new text to DESCRIPTION.
        Changed CONFORMING TO.

stat.2
    Mike Frysinger
        Improve st_blocks description.

carg.3
    Ramiro Aceves / aeb
        Change:
                One has carg(z) = atan(creal(z) / cimag(z))
        to:
                One has tan(carg(z)) = cimag(z) / creal(z)

        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=326720

cmsg.3
    mtk
        s/SOL_TCP/IPPROTO_TCP/          (POSIX standard name)

dlopen.3
    Alain Portal
        s/-nostartupfiles/-nostartfiles/

getaddrinfo.3
    mtk
        Nowadays (since 2.3.4) glibc only sets the first ai_canonname
        field if AI_CANONNAME was specified (the current behavior
        is all that SUSv3 requires).

        1,$s/PF_/AF_/g

        Added descriptions of AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
        and AI_NUMERICSERV.

        Some wording and formatting fixes.

getpwnam.3
    Bernhard R. Link / mtk
        Add NOTES text describing relationship of pw_dir and HOME and
        pointing out that applications should preferentially inspect HOME.

inet.3
    Mike Frysinger
        Mention "little endian" and "big endian".
        Added note about octal and hex interpretation of
             numbers-and-dots notation.

rpc.3
    mtk / Ludovic Courtes
        Commented out references to rpc_secure(3) -- we don't currently
        have such a page in the man-pages set.
        In response to http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=325115

setenv.3
    mtk
        glibc 2.3.4 fixed the "name contains '='" bug.

strnlen.3
    Mike Frysinger
        Added "#define _GNU_SOURCE" to prototype.

initrd.4
    Norbert Buchmuller / mtk
        Added text noting that the use or real-root-dev for changing
        the root device is obsolete, in favor of pivot root.
        (However, the page still needs to be rewritten to actually
        describe the pivot_root method...)
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=323621

proc.5
    mtk
        Improve text describing /proc/sys/fs/mqueue/* files.

        Describe /proc/sys/fs/suid_dumpable (new in 2.6.13).

        Added placeholder mention of /proc/zoneinfo (new in 2.6.13).
        More needs to be said about this file.

        Repaired earlier cut and paste mistake which resulted
        in part of the text of this page being duplicated.

utmp.5
    Mike Frysinger
        Added text on biarch details for ut_session and ut_tv.

capabilities.7
    mtk
        Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE.

ip.7
    mtk / Andrew Pimlott
        Add a couple of words to make it clear that port is a 16-bit number.
        Reformat long source lines (no text changed).

        s/SOL_IP/IPPROTO_IP/            (POSIX standard name)

    Hasso Tepper
        Fix discussion of IPC_RECVTTL / IP_TTL.

signal.7
    mtk
        Updated SEE ALSO to reflect splitting of sigaction.2 into
        sigaction.2, sigsuspend.2, sigpending.2, sigprocmask.2.

socket.7
    mtk
        Clarified details of use of SO_PEERCRED.

tcp.7
    mtk
        s/SOL_TCP/IPPROTO_TCP/          (POSIX standard name)
        s/SOL_IP/IPPROTO_IP/            (POSIX standard name)

udp.7
    mtk
        Added description of UDP_CORK socket option.

        s/SOL_UDP/IPPROTO_UDP/          (POSIX standard name)
        s/SOL_IP/IPPROTO_IP/            (POSIX standard name)
top
==================== Changes in man-pages-2.09 ====================

Released: 2005-10-13

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Justin Pryzby
Peter Chubb
Samuel Thibault
Tomas Pospisek
Trond Myklebust

Apologies if I missed anyone!

Global changes
--------------

ptsname.3
getpt.3
unlockpt.3
openpty.3
posix_openpt.3
grantpt.3
pts.4
tty_ioctl.4
    mtk
        Added SEE ALSO for new pty.7 page.

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

pty.7
    mtk
        Overview of Unix 98 and BSD pseudo-terminals.

Changes to individual pages
---------------------------

ldd.1
    mtk
        Remove "-V" option (fix from Fedora man-pages-2.07-7).

fcntl.2
    Peter Chubb / Trond Myklebust / mtk
        Since kernel 2.6.10, a read lease can only be placed on a
        file descriptor that is opened read-only.
        See the following LKML thread of Aug 2005
        ("fcntl(F GETLEASE) semantics??"):
        http://marc.theaimsgroup.com/?l=linux-kernel&m=112371777712197&w=2
        http://marc.theaimsgroup.com/?l=linux-kernel&m=112374818213000&w=2
        http://marc.theaimsgroup.com/?l=linux-kernel&m=112376335305284&w=2
        http://marc.theaimsgroup.com/?l=linux-kernel&m=112377294030092&w=2

mprotect.2
    mtk
        Add new text to ENOMEM error.

mremap.2
    mtk
        Added description of MREMAP_FIXED and 'new_address' argument
        under NOTES.
        Revised text of EINVAL error.

read.2
    Samuel Thibault / mtk
        read() can fail with EINVAL when using O_DIRECT
    mtk
        Added open(2) to SEE ALSO.

shmget.2
    mtk
        s/int/size_t/ for type of 'size' argument (fix from
        Fedora man-pages-2.07-7).

write.2
    Samuel Thibault / mtk
        write() can fail with EINVAL when using O_DIRECT

atanh.3
    mtk
        Fix: s/acosh/atanh/ (fix from Fedora man-pages-2.07-7).

fopen.3
    mtk
        Improved "a+" description (fix from Fedora man-pages-2.07-7).

getrpcent.3
    mtk
        s/getrpcent/setrpcent/ (fix from Fedora man-pages-2.07-7).

stdio.3
    mtk / Justin Pryzby
        Removed references to fropen() and fwopen(), which are
        BSDisms that don't appear in glibc.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=331174

strftime.3
    mtk
        Typo fix: %Ry ==> %Ey [SUSv3 mentions...] (fix from
        Fedora man-pages-2.07-7).

nsswitch.conf.5
    mtk
        s/network/networks/ (fix from Fedora man-pages-2.07-7).

proc.5
    mtk
        Added description of /proc/sys/vm/legacy_va_layout.

socket.7
    mtk
        Update description of SO_RCVLOWAT and SO_SNDLOWAT.
        (fix derived from Fedora man-pages-2.07-7).
top
==================== Changes in man-pages-2.10 ====================

Released: 2005-10-19

Global changes
--------------

The changes in this release consist *solely* of formatting fixes, with
the aim bringing greater consistency to the manual pages according to
the following rules:

-- Function name references should *always* be followed by
   parentheses, "()" (possibly containing a manual page section
   number).

-- The parentheses following a function name should *not* be
   formatted.  Thus, for example, instead of:

       .B name()

   one should write:

       .BR name ()

Much of the change was automated using two scripts:
add_parens_for_own_funcs.sh and unformat_parens.sh.
For the (possible) benefit of downstream manual page maintainers and
translators, I have placed these scripts in a new subdirectory 'scripts'.

NOTE THE FOLLOWING POINTS WELL:

-- These scripts provide a computer-assisted solution to the above
   two goals.  However, they are not perfect, and their output should
   be scanned by a human.  (To see what changes the two scripts
   *would* make, without making them, use the "-n" command line option.)

-- The scripts do not fix all instances that violate the above rules:
   some manual fixes are required.  Two further scripts are provided
   to help find remaining instances of function names without
   following "()": find_dots_no_parens.sh and find_slashes_no_parens.sh.

The following changes were made:

-- add_parens_for_own_funcs.sh was applied to the pages in Sections
   2 and 3.

-- unformat_parens.sh was applied to pages in Sections 2, 3, 4, and 7
   (the only sections where such changes were required).

-- further changes (not so very many) were performed by hand.
   (found places to fix with the assistance of find_dots_no_parens.sh
   and find_slashes_no_parens.sh).
top
==================== Changes in man-pages-2.11 ====================

Released: 2005-10-24

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain PORTAL

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        Most instances of the constant "NULL" are not formatted (bolded) in
        man pages, but a few are.  For consistency, formatting on "NULL" has
        been removed where it occurred.

        Many minor formatting fixes were made.

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

getrlimit.2
    mtk
        Added EINVAL error for rlim_cur > rlim_max when calling setrlimit().

path_resolution.2
    mtk
        Repaired discussion of capabilities and file system UID, which
        mistakenly had involved exec() in the discussion.

prctl.2
    mtk
        Removed text saying there is no library interface.  There
        is nowadays.

mkfifo.3
    mtk
        Minor change to RETURN VALUE text.

sk98lin.4
    Alain Portal
        Formatting fixes.

capabilities.7
    mtk
        Minor changes.
top
==================== Changes in man-pages-2.12 ====================

Released: 2005-10-31

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Akihiro MOTOKI
Andries Brouwer
Brian M. Carlson
herbert
Martin Landers
Michael Benedict

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

mlock.2
    mtk
        Reworded text around PAGESIZE, noting also that
        sysconf(_SC_PAGESIZE) can be used.

path_resolution.2
    mtk / aeb
        Removed words "as well" (added in 2.11) from the phrase
        "and it gets these last five capabilities if its fsuid is 0 as well"
        since there are (unusual) situations in which fsuid can be 0 while
        the effective UID is not.

        Reworked (cut down) discussion of capabilities, moving part of
        it into capabilities.7

setresuid.2
    mtk
        Add text to note that setresuid() always modifies the file
        system UID, and setresgid() likewise always modifies the file
        system GID.

shmget.2
    mtk
        Added (brief) description of SHM_HUGETLB.

sigaltstack.2
    mtk / Martin Landers
        Noted that ss_sp is automatically aligned by the kernel.

byteorder.3
    Brian M. Carlson  / herbert
        Change <netinet/in.h> to <arpa/inet.h> in prototype; add text
        explaining that some systems need the former header.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=265244

capabilities.7
    mtk
        Reworked part of the discussion of exec() and capabilities.
        Added sub-section "Effect of User ID Changes on Capabilities".
        Reworked discussion of CAP_SYS_ADMIN and file-max.
top
==================== Changes in man-pages-2.13 ====================

Released: 2005-11-03

This release consists entirely of formatting and typographical fixes.

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Various pages
    mtk
        Function and page cross references that were italicized were
        made bold (which is how the majority of function and page
        cross references were already done).

Various pages
    mtk
        Instances of things like "NULL-terminated string" were changed to
        "null-terminated string".

Various pages
    mtk
        Pathnames, structures, arguments, and <header-files> that were
        bold were changed to italics.

Various pages
    mtk
        Instances of the constant "NULL" that were bold-faced were made
        unformatted (which is how most instances of "NULL" were already
        formatted.)
top
==================== Changes in man-pages-2.14 ====================

Released: 2005-11-17

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Angelo
Avery Pennarun
Justin Pryzby
Martin (Joey) Schulze
Stefan BrÃ¼ns
Volker Reichelt

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

rexec.3
    mtk / Justin Pryzby
        This page is taken as is from the FreeBSD 5.4 distribution.
        (Not checked against Linux reality, but likely things are
        the same.)
        See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=336875

Changes to individual pages
---------------------------

arch_prctl.2
    mtk
        Updated discussion about lack of prototype in glibc.

execve.2
    mtk
        Improved description of E2BIG error: it relates to the sum
        of the bytes in both environment and argument list.

fcntl.2
    mtk
        Clarified parts of the discussion of file leases,
        noting effect of open(O_NONBLOCK), interruption
        by signal handler, or termination by signal in
        lease breaker.  In response to
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=339037

stat.2
    mtk / Stefan BrÃ¼ns
        Added LINUX NOTES describing nanosecond timestamps.

frexp.3
    Volker Reichelt / mtk
        Fixed to point out that that frexp() returns a number whose
        *absolute* value is >= 0.5 and < 1.  Amended the example
        program to demonstrate this.

open.2
    mtk / Avery Pennarun
        Add EWOULDBLOCK error for file leases.
        In response to
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=339037

putenv.3
    mtk
        Although the glibc implementation returns -1 on error (and some
        other man pages (e.g., the BSDs) also document that value for
        error returns), SUSv3 merely says "non-zero" (and this is
        what manual pages on many implementations also say).

posix_memalign.3
    mtk
        Formerly, the page said that all systems declare memalign() in
        <malloc.h>.  In fact, many declare it in <stdlib.h>.

strtok.3
    mtk
        Almost a complete rewrite after Angelo pointed out
        that the existing page was deficient.

sd.4
    Martin Schulze
        Remove SEE ALSO for nonexistent scsi.4.

proc.5
    mtk
        Updated discussion of /proc/sys/kernel/pid_max.

signal.7
    mtk
        Added pthreads.7 to SEE ALSO.

ld.so.8
    mtk
        Fix typo: s/LD_DEBUG_OUTPUT/LD_PROFILE_OUTPUT/
top
==================== Changes in man-pages-2.15 ====================

Released: 2005-11-30

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
James Vega
Malcolm Scott
Senthil Kumar

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

sigvec.3 -- for details, see below.

sigset.3 -- for details, see below.

Changes to individual pages
---------------------------

kill.2
    mtk
        Added text describing the 2.6.[0-7] EPERM bug that occurred
        when sending signals to a process group.

sigaction.2
    mtk
        Noted that si_signo is unused on Linux.

sigpending.2
    mtk
        Added BUGS noting wrapper function problem that existed
        in glibc versions <= 2.2.1.

sigpause.2
    mtk
        Moved to section 3; see also sigpause.3 below.

sigsetops.3
    mtk
        Added a GLIBC NOTES section describing sigisemptyset(),
        sigandset(), and sigorset().

sigvec.2
sigblock.2
    mtk
        These pages have been deleted, and replaced by a new sigvec.3
        man page that more fully describes the BSD signal API.

siggetmask.2
sigmask.2
sigsetmask.2
    mtk
        These links to the now-deleted sigblock.2 have been also been
        deleted.  They are replaced by corresponding links in Section 3:
        sigmask.3, sigsetmask.3, siggetmask.3.

sigvec.3
    mtk
        This new page is provides a fuller description of the
        BSD signal API than was provided in the now-deleted sigvec.2
        and sigblock.2.

sigblock.3
siggetmask.3
sigmask.3
sigsetmask.3
    mtk
        Created as links to sigvec.3.

sigpause.3
    mtk
        Moved here from Section 2.

        Some minor wording fixes; clarified System V origins of
        X/Open flavor of this function.

sigset.3
    mtk
        New page describing the System V signal API: sigset(), sighold(),
        sigrelse(), sigignore().

strftime.3
    James Vega
        Add further text clarifying that %+ specifier is not supported in
        glibc2.
    mtk
        Added GLIBC NOTES section describing optional 'flag' and 'width'
        components of conversion specifiers.
        Some wording changes to bring terminology closer to SUSv3.
        Added an example program.

vm86old.2
    mtk / aeb
        Add as new link to vm86.2.

intro.7
    mtk
        Added a few words to reflect the fact that several of the section
        7 pages provide overviews of various topics.

signal.7
    mtk
        Added some SEE ALSO entries.

socket.7
    Senthil Kumar / mtk
        Added text noting that select()/poll() do not respect SO_RCVLOWAT.

udp.7
    Malcolm Scott
        s/tcp_socket/udp_socket/ in example
        Fixes http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=340927
top
==================== Changes in man-pages-2.16 ====================

Released: 2005-12-02

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alan Stern
Andries Brouwer
Urs Thuermann

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

HOWTOHELP
    Urs Thuermann
        Added instructions for finding maintainer in Debian package.

poll.2
    mtk
        Added NOTES about INFTIM constant provided on some other
        implementations.

shmop.2
    Alan Stern
        The -1 error return of shmat() should be cast "(void *)".

strftime.3
    aeb
        Remove junk text (actually intended as source code comment
        in page).

ip.7
    Urs Thuermann
        Fix a typo: s/SOCK_RAW/SOCK_PACKET/

packet.7
    Urs Thuermann
        Clarification: s%SOCK_PACKET%PF_INET/SOCK_PACKET%
top
==================== Changes in man-pages-2.17 ====================

Released: 2005-12-13

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Justin Pryzby
Michael Haardt
Urs Thuermann
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

fmemopen.3
    Walter Harms / mtk
        New documentation for the glibc-specific fmemopen() and
        open_memstream().  Based on glibc info page.

pipe.7
    mtk (with prompting and suggestions for improvements by
    Michael Haardt)
        New page providing overview of pipes and FIFOs.

Changes to individual pages
---------------------------

HOWTOHELP
    mtk
        Added notes on how to write example programs for manual pages.

fork.2
    mtk
        Added pointers to examples of fork() in wait.2 and pipe.2.

pipe.2
    mtk
        Added an example program.
        Added SEE ALSO for new pipe.7 page.

wait.2
    mtk
        Added example program demonstrating use of fork() and waitpid().

carg.3
    Justin Pryzby
        Delete line that should have been deleted when applying
        2.08 fix for this page.

getaddrinfo.3
    mtk
        Rearranged EAI_* list alphabetically.

inet.3
    mtk
        Added GLIBC NOTES describing feature test macros required
        to expose declaration of inet_aton().

open_memstream.3
    mtk
        New link to new fmemopen.3.

fifo.4
    mtk
        Added SEE ALSO for new pipe.7 page.

environ.5
    mtk
        Removed BROWSER, since it seems not in fact to be common.

socket.7
    Urs Thuermann
        Added documentation of SO_TIMESTAMP.

tcp.7
    mtk
        Noted 200 millisecond ceiling imposed on TCP_CORK.

udp.7
    mtk
        Rearranged options into something approximating alphabetical order.
top
==================== Changes in man-pages-2.18 ====================

Released: 2005-12-15

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Justin Pryzby
Karsten Sperling
Martin (Joey) Schulze
Mike Frysinger
Stefan Puiu

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

bind.2
    mtk
        Added mention of AF_INET6 address family.
        Added discussion of sockaddr structure and an example in the
        Unix domain.

recv.2
    mtk
        Put 'flags' list in alphabetical order.

send.2
    mtk
        Added cross-reference from discussion of MSG_MORE to UDP_CORK
        in udp(7).

        Put 'flags' list in alphabetical order.

err.3
    mtk
        Added CONFORMING TO section noting that these are
        non-standard BSDisms.

errno.3
    Justin Pryzby
        Added SEE ALSO for err.3.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306867

gethostbyname.3
    Martin (Joey) Schulze / mtk
        Added references to nsswitch.conf(5); remove cross references
        to resolv+(8).
        See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=308397

perror.3
    Justin Pryzby
        Added SEE ALSO for err.3 .
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306867

resolver.3
    mtk / Martin (Joey) Schulze
        Remove cross references to resolv+(8); add cross references to
        resolv.conf(5).
        See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=214892

        Added SEE ALSO entry for resolver(5);
        see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=251122

strerror.3
    mtk / Stefan Puiu
        Rewrote and extended the discussion of the two flavors of
        strerror_r(), and added some additional information on
        strerror().
    Justin Pryzby
        Added SEE ALSO for err.3, as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306867

elf.5
    Mike Frysinger
        Fix three typos in identifier names.

operator.7
    Karsten Sperling
        The + operator should be in the list of unary operators.

raw.7
    mtk
        Small wording changes around discussion of SO_BSDCOMPAT.
        Fixed a couple of wording errors elsewhere.
        Reformatted some long lines.

socket.7
    mtk, after a note by Stefan Puiu
        Updated discussion of SO_BSDCOMPAT.

        Reformatted some long lines.

        Noted the Linux-specific feature whereby setsockopt() doubles
        the value given for SO_SNDBUF and SO_RCVBUF.

        Noted kernel-imposed minimum values for SO_SNDBUF and SO_RCVBUF.

udp.7
    mtk, after a note by Stefan Puiu
        Updated discussion of SO_BSDCOMPAT.

unix.7
    mtk
        Added new (UN)SUPPORTED FEATURES section in which it is noted
        that Unix domain sockets do not support MSG_OOB or MSG_MORE.

        Noted details of SO_SNBUF and SO_RCVBUF support for
        Unix domain sockets.
top
==================== Changes in man-pages-2.19 ====================

Released: 2005-12-23

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Walter Harms
Stefan Puiu

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

HOWTOHELP
    mtk
        Minor changes.

bind.2
    Stefan Puiu / mtk
        Remove text under EINVAL error: "This may change in the future:
        see linux/unix/sock.c for details."  This behavior has been
        unchanged for a long time, and seems unlikely to change.

        Add EADDRINUSE to errors.

send.2
    aeb
        Add cmsg(3) to SEE ALSO.

fopen.3
    Walter Harms / mtk
        Added description of 'x' mode character (exclusive open).

pipe.7
    mtk / aeb
        Some wording changes to description of pipes.
top
==================== Changes in man-pages-2.20 ====================

Released: 2006-01-03

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

sigaltstack.2
    mtk
        Added some text to explain the usual scenario in which
        sigaltstack() is employed.

getloadavg.3
    mtk
        Noted that this function is available since glibc 2.2.

strcpy.3
    mtk
        s/nulls/null bytes/

capabilities.7
    mtk
        Noted that capability bounding set appeared with kernel 2.2.11.

arp.7
icmp.7
ip.7
ipv6.7
netdevice.7
packet.7
raw.7
rtnetlink.7
socket.7
tcp.7
unix.7
udp.7
    mtk
        The only changes to these pages have been for formatting:
            -- Structure definitions were changed to K&R style
            -- Some long source lines were broken to fit into ~70
               character lines.
        No changes were made to the content of these pages (yet...).
top
==================== Changes in man-pages-2.21 ====================

Released: 2006-01-16

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Falk Hueffner
Mike Frysinger
Senthil Kumar
Stefan Puiu

Apologies if I missed anyone!

Global changes
--------------

dd.1 cp.1
truncate.2 gethostname.2 lseek.2 listxattr.2 readlink.2
sysfs.2 stat.2 ustat.2 uname.2 getdomainname.2
argz_add.3 asprintf.3 confstr.3 bstring.3 bzero.3 dlopen.3 fwide.3
gethostbyname.3 getline.3 getlogin.3 getnameinfo.3 getpass.3 hsearch.3
perror.3 printf.3 readdir.3 scanf.3 stpcpy.3 strdup.3 strfmon.3
strftime.3 string.3 strptime.3 sysconf.3 termios.3 ttyname.3
dsp56k.4 tty_ioctl.4
elf.5 proc.5 termcap.5
charsets.7 unix.7
    mtk
        Various pages use inconsistent terms for 'null byte' (which
        is the C99/SUSv3 term for the '\0' character).

        To rectify this the following changes were made in the above
        pages:

            Replace 'zero byte' with 'null byte'.
            Replace 'null character' with 'null byte'.
            Replace 'nulls' with 'null bytes'.
            Replace 'NUL-terminated' by 'null-terminated'.
            Replace 'NUL' by 'null byte'.
            Replace 'terminating NUL' by 'terminating null byte'.
            Replace 'final NUL' by 'terminating null byte'.
            Replace 'NUL character' by 'null byte'.

Various pages
    mtk
        Replace "SysV"/"SYSV" by "System V".

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

capget.2
    mtk
        Noted bug that could wrongly cause EPERM in unprivileged
        capset() with 'pid' field == getpid().

epoll_ctl.2
    mtk
        Noted that EPOLLONESHOT was added in 2.6.2.

gethostname.2
    mtk
        Added GLIBC NOTES describing operation of glibc's
        gethostname() wrapper function.

mmap.2
    mtk / Mike Frysinger
        Clarify relationship between mmap2(2) and mmap64(3).
    mtk
        A few other small rewordings.

mmap64.3
    Mike Frysinger
        New link to mmap.2.

open.2
    mtk
        Added BUG noting that O_ASYNC can't be enabled via
        open(): fcntl() must be used for this purpose.

recv.2
    Stefan Puiu
        Relocate misplaced discussion of MSG_DONTWAIT.

dlopen.3
    mtk
        Rewrote discussion of dlopen() 'flag' argument;
        added descriptions of RTLD_NOLOAD, RTLD_DELETE,
        and RTLD_DEEPBIND.

        Noted use of atexit() to register a function that is
        automatically called when a library is unloaded.

fmemopen.3
    mtk
        Rewrote substantial parts of the page, and relicensed under GPL.

fseeko.3
    Mike Frysinger
        Add RETURN VALUE section.

getopt.3
    mtk
        Noted historical use of <stdio.h> to declare getopt().

qsort.3
    mtk / Falk Hueffner
        Clarify how strcmp() should be used as the 'compar'
        function by providing an example.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348072

proc.5
    mtk
        Noted that /proc/mounts is pollable since kernel 2.6.15.

        Documented /proc/PID/task.

        Noted that the contents of /proc/PID/{cwd,exe,fd,root,task}
        are not available if the main thread has terminated.

    Senthil Kumar
        Add pointer to random(4) for description of files under
        /proc/sys/kernel/random.

udp.7
    Stefan Puiu / mtk
        Small rewording of discussion of SO_BSDCOMPAT
        (add cross-ref to socket(7)).
top
==================== Changes in man-pages-2.22 ====================

Released: 2006-02-02

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andre Noll
Andries Brouwer
Colin Tuckley
Stefan Puiu
Thomas Hood
Thorsten Kukuk
Walter Harms

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

mmap.2
    aeb / mtk
        Noted that portable applications should specify fd as -1
        when using MAP_ANONYMOUS.
        Some rewriting of description of MAP_ANONYMOUS.

rt_sigreturn.2
    Thorsten Kukuk
        New link to sigreturn.2.

rt_sigsuspend.2
    mtk
        New link to sigsuspend.2.

waitid.2
    mtk
        Noted that waitid() does not set infop->si_uid field on
        most other implementations.

getopt.3
    Walter harms / mtk
        Make clear that when calling getopt_long() and there are no
        short options, then 'optstring' should be "", not NULL.

openpty.3
    Thomas Hood / mtk
        In glibc 2.0.92, openpty() was modified to preferably open
        Unix 98 ptys instead of BSD ptys.

qsort.3
    mtk
        Small rewording under EXAMPLES.

strtol.3
strtoul.3
    Stefan Puiu
        s/string must begin/string may begin/

proc.5
    mtk
        Documented inotify files under /proc/sys/fs/inotify:
        max_queued_events, max_user_instances, and max_user_watches.
top
==================== Changes in man-pages-2.23 ====================

Released: 2006-02-10

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
Britton Leo Kerin
Dan Jacobson
Justin Pryzby
Luc Van Oostenryck
Kurt Wall
Martin (Joey) Schulze
Matthias Andree
Robert Love
Samuel Thibault
Urs Thuermann

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

inotify_init.2
inotify_add_watch.2
inotify_rm_watch.2
    Robert Love, with some additions by mtk.
        New pages describing the inotify API.

mbind.2
get_mempolicy.2
set_mempolicy.2
    Andi Kleen, with additional work by mtk
        New pages describing the NUMA memory allocation policy API.
        Drawn from the set at ftp://ftp.suse.com/pub/people/ak/numa.

rtc.4
    Urs Thuermann, with additional work by mtk
        New page describing the real-time clock driver.

inotify.7
    mtk
        Overview of the inotify API.

Changes to individual pages
---------------------------

clone.2
    Andi Kleen
        On x86, clone() should not be called through vsyscall,
        but directly through "int $0x80".

fcntl.2
    mtk
        Small wording changes.

        Added cross-ref to inotify.7 under the description of dnotify.

kill.2
    mtk / Britton Leo Kerin
        Small wording change under NOTES to clarify
        what happens when a process sends a signal to itself.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=350236

mlock.2
    mtk / Matthias Andree
        Added BUGS txt on interaction between MCL_FUTURE and
        RLIMIT_MEMLOCK.
        See the following LKML thread:
        http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
        "Rationale for RLIMIT_MEMLOCK"

msgop.2
    mtk / Samuel Thibault
        Rewrote declaration of 'msgp' to be "void *" in response
        to http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=350884
        Various other wording fixes.

open.2
    mtk
        Clarify distinction between "file creation flags" and
        "file status flags".

read.2
    Justin Pryzby
        Add SEE ALSO for pread(2).
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351873

sched_setaffinity.2
    mtk
        Major rewrite.

select.2
    mtk
        Added return types to prototypes for FD_SET(), FD_CLR(),
        FD_ZERO, and FD_ISSET().
        Other minor wording changes.

read.2
    mtk
        Add SEE ALSO for pwrite(2).
        (Analogous with read.2 change above.)

errno.3
    Kurt Wall / mtk
        Add Linux specific errors to this page.

localeconv.3
    mtk
        Added cross-ref to locale.7 for 'struct lconv' defn.
        Other minor wording changes.
    Martin (Joey) Schulze
        Added SEE ALSO refs for nl_langinfo.3
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351831

scanf.3
    mtk / Justin Pryzby
        Minor formatting & wording fixes.

setlocale.3
    Martin (Joey) Schulze
        Added SEE ALSO refs for nl_langinfo.3
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351831

proc.5
    mtk
        Migrated description of inotify files to the new inotify.7 page.

ascii.7
    Dan Jacobson / mtk
        Add text describing characters 001 to 037.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=342173

locale.7
    mtk
        Minor wording and formatting changes.
top
==================== Changes in man-pages-2.24 ====================

Released: 2006-02-17

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Joerg Habenicht
Luc Van Oostenryck
Mike Frysinger
Samuel Thibault

Apologies if I missed anyone!

New pages
---------

get_kernel_syms.2
create_module.2
delete_module.2
init_module.2
query_module.2
    FSF / mtk (with assistance of Luc Van Oostenryck)
        man-pages finally gets pages for these system calls, several
        of which are obsolete in Linux 2.6.
        Took the old GPLed pages dated 1996 and made a number of
        clean-ups and minor additions.

Global changes
--------------

various pages
    mtk
        Change "file name" to "filename"
        Change "path name" to "pathname"

stpncpy.3
strstr.3
strcmp.3
toupper.3
strlen.3
stpcpy.3
puts.3
strdup.3
strtok.3
isalpha.3
strspn.3
gets.3
strpbrk.3
    mtk after a suggestion from Samuel Thibault
        Added SEE ALSO pointers to wide character equivalent functions
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351996

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

clone.2
    mtk
        Remove duplicate CLONE_STOPPED text.
        Commented out crufty text describing EINVAL error
        for the now obsolete CLONE_DETACHED flag.
        Under CLONE_SIGHAND, noted that 'flags' must also include
        CLONE_VM if CLONE_SIGHAND is specified.

fcntl.2
    mtk
        Under ERRORS: Separate out EAGAIN error for locking mmaped files.

inotify_add_watch.2
    mtk
        Minor wording fix.

msgop.2
    mtk
        Documented the EAGAIN error for msgrcv().

fnmatch.3
    Mike Frysinger / mtk
        Expand explanation of FNM_PATHNAME.

lockf.3
    Joerg Habenicht / mtk
        Fix up discussion of EAGAIN/EACCESS errors.
top
==================== Changes in man-pages-2.25 ====================

Released: 2006-03-02

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

James Peach
Krzysztof Benedyczak
Marten von Gagern
Michael Haardt
Michael Wronksi

Apologies if I missed anyone!

New pages
---------

mq_close.3
mq_getattr.3
mq_notify.3
mq_open.3
mq_receive.3
mq_send.3
mq_unlink.3
    mtk
        New pages describing POSIX message queue API.

posix_fallocate.3
    mtk, after a suggestion by James Peach
        New page describing posix_fallocate().

mq_overview.7
    mtk
        New page giving overview of the POSIX message queue API.

Changes to individual pages
---------------------------

lseek.2
    Michael Haardt
        Add a case to the EINVAL error text.
    mtk
        Various minor wording fixes
        Added SEE ALSO referring to new posix_fallocate.3.

posix_fadvise.2
    mtk
        Added "#define _XOPEN_SOURCE 600" to prototype.
        Added SEE ALSO referring to new posix_fallocate.3.

proc.5
    mtk
        Migrated information on POSIX message queues to new mqueue.7 page.

inotify.7
    Marten von Gagern
        Fix thinko: s/assuming a non-blocking/assuming a blocking/
top
==================== Changes in man-pages-2.26 ====================

Released: 2006-03-21

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andi Kleen
Andries Brouwer
Christoph Lameter
Hasso Tepper
Justin Pryzby
Martin (Joey) Schulze
Nicolas François
Paul Brook
Siward de Groot
Steve Beattie
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

clone.2
getdents.2
gettid.2
llseek.2
mmap2.2
modify_ldt.2
pivot_root.2
quotactl.2
readdir.2
sysctl.2
syslog.2
tkill.2
    mtk, aeb, Steve Beattie
        Added comment in SYNOPSIS to note that syscall(2) may be
        preferable over _syscallN (see intro(2)).

Various minor formatting changes were done on a range of
pages in Section 7.  (No content was changed.)

New pages
---------

openat.2
    mtk
        New page describing openat(2), added in kernel 2.6.16,
        and some notes on rationale for the at*(2) system calls.

mbind.2
    Andi Kleen, Christoph Lameter, mtk
        Added MPOL_MF_MOVE and MPOL_MF_MOVE_ALL descriptions,
        from numactl-0.9.2 man page.
        Plus a few other smaller fixes.

fexecve.3
    mtk
        New page describing fexecve(3).

futimes.3
    mtk
        New page describing futimes(3).

Changes to individual pages
---------------------------

execve.2
    mtk
        Added SEE ALSO pointing to new fexecve.3.

intro.2
    mtk, aeb, Steve Beattie
        Added some notes on syscall(2) versus _syscall.

msgctl.2
msgget.2
msgop.2
    mtk
        Added SEE ALSO pointing to mq_overview.7.

open.2
    mtk
        Added SEE ALSO pointing to new openat.2.

        Split out part of the RETURN VALUE text into separate
        NOTES section.

        Modified wording referring to raw(8) to
        indicate that this interface is deprecated.

poll.2
    mtk
        Added discussion of ppoll(2), which is new in 2.6.16.

ppoll.2
    mtk
        New link to poll.2.

recvmsg.2
sendmsg.2
    mtk / Paul Brook
        Added text to note that although POSIX says msg_controllen
        should be socklen_t, glibc actually uses size_t.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=356502
        and the associated glibc bug report.
        http://sourceware.org/bugzilla/show_bug.cgi?id=2448
    mtk
        Various formatting fixes.

select.2
    mtk
        Updated to reflect the fact that pselect() has been implemented
        in the kernel in 2.6.16; various other minor wording changes.

        pselect() prototype needs "#define _XOPEN_SOURCE 600".

tempnam.3
    Justin Pryzby
        Clean up description of EEXIST error.
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=357893

unlink.2
    mtk
        Added a little extra text to clarify EISDIR vs EPERM.

utime.2
    mtk
        Added new SEE ALSO entry pointing to new futimes.3 page.

exec.3
    mtk
        Added SEE ALSO pointing to new fexecve.3.

shm_unlink.3
    mtk
        New link to shm_open.3 (should have been made when page
        was originally written).

swab.3
    Walter Harms
        Add needed "#define _XOPEN_SOURCE".

undocumented.3
    mtk
        Updated to remove a few function names that are now documented.

capabilities.7
    mtk
        Various changes to bring this page closer to
        current kernel versions.

inotify.7
    mtk
        Noted that glibc 2.4 is required to get glibc support
        for inotify.

mq_overview.7
    mtk
        Some rewording and added a few words about System V
        message queues.

netlink.7
    Hasso Tepper
        Substantial updates to various parts of this page.
    mtk, Alain Portal
        Minor fixes

pthreads.7
    mtk
        Updated to reflect that the NPTL limitation that only the main
        thread could call setsid() and setpgid() was removed in 2.6.16.

raw.7
    Hasso Tepper
        Removed text implying that only in kernel 2.2 does IP_HDRINCL
        prevent datagrams from being fragmented.

socket.7
    mtk
        Documented SO_SNDBUFFORCE and SO_RCVBUFFORCE socket options,
        new in 2.6.14.

        Placed socket options in alphabetical order.
top
==================== Changes in man-pages-2.27 ====================

Released: 2006-03-24

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Charles P. Wright
Christoph Lameter
Chuck Ebbert
Daniel Jacobowitz
Ingo Molnar
Heiko Carstens
Janak Desai
Paolo (Blaisorblade) Giarrusso
Stefan Puiu

Apologies if I missed anyone!

Global changes
--------------

man7/*
    mtk
        Various minor formatting changes were done on a range of
        pages in Section 7.  (No content was changed.)

New pages
---------

unshare.2
    mtk, with reference to documentation by Janak Desai
        New page describing unshare(2), added in kernel 2.6.16.

Changes to individual pages
---------------------------

clone.2
fork.2
vfork.2
    mtk
        Added SEE ALSO pointing to new unshare.2.

mbind.2
    Christoph Lameter
        MPOL_MF_MOVE_ALL requires CAP_SYS_NICE not CAP_SYS_RESOURCE.

mremap.2
    mtk
        Clarified the description of MREMAP_FIXED and restructured
        the text to reflect the fact that this flag is exposed
        by glibc since version 2.4.

ptrace.2
    Chuck Ebbert, with assistance from Daniel Jacobowitz,
    Paolo (Blaisorblade) Giarrusso, and Charles P. Wright;
    after a suggestion from Heiko Carstens.
        Document the following ptrace requests:
            PTRACE_SETOPTIONS (2.4.6)
                plus associated flags:
                    PTRACE_O_TRACESYSGOOD (2.4.6)
                    PTRACE_O_TRACEFORK (2.5.46)
                    PTRACE_O_TRACEVFORK (2.5.46)
                    PTRACE_O_TRACECLONE (2.5.46)
                    PTRACE_O_TRACEEXEC (2.5.46)
                    PTRACE_O_TRACEVFORKDONE (2.5.60)
                    PTRACE_O_TRACEEXIT (2.5.60)
            PTRACE_SETSIGINFO (2.3.99-pre6)
            PTRACE_GETSIGINFO (2.3.99-pre6)
            PTRACE_GETEVENTMSG (2.5.46)
            PTRACE_SYSEMU (since Linux 2.6.14)
            PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)

sched_get_priority_max.2
sched_setscheduler.2
sched_setparam.2
    mtk, Ingo Molnar
        Modified to document SCHED_BATCH policy, new in kernel 2.6.16.

        Text describing SCHED_BATCH was added to sched_setscheduler.2,
        and was drawn in part from Ingo Molnar's description in the
        mail message containing the patch that implemented this policy.

        Various other minor rewordings and formatting fixes.

proc.5
    mtk, using text from Documentation/filesystems/proc.txt
        Document /proc/sys/vm/drop_caches, new in kernel 2.6.16.
    mtk, using information from ChangeLog-2.6.14.
        Document /proc/PID/smaps, new in kernel 2.6.14.

capabilities.7
    mtk
        Noted affect of CAP_SYS_NICE for mbind(MPOL_MF_MOVE_ALL).

pthreads.7
    mtk
        Kernel 2.6.16 eliminated buggy behavior with respect to
        the alternate signal stack.
top
==================== Changes in man-pages-2.28 ====================

Released: 2006-03-31

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Aleksandr Blokhin
Greg Johnson

Apologies if I missed anyone!

New pages
---------

sem_post.3
sem_getvalue.3
sem_close.3
sem_open.3
sem_destroy.3
sem_wait.3
sem_unlink.3
sem_init.3
sem_overview.7
    mtk
        New pages describing the POSIX semaphores API.

        These pages supersede and provide a superset of the information
        in the glibc (3thr) "semaphores(3)" manual page.

Changes to individual pages
---------------------------

ppoll.2
    Aleksandr Blokhin
        Fix broken link.

ptrace.2
    mtk
        Wrapped long lines (no content changes).

semctl.2
semget.2
semop.2
    mtk
        Add SEE ALSO pointing to the new sem_overview.7 page.

elf.5
    Greg Johnson
        Removed SEE ALSO reference to nonexistent core(5).
top
==================== Changes in man-pages-2.29 ====================

Released: 2006-04-06

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Michael Haardt
Roberto Jimenoca
Stefan Puiu

Apologies if I missed anyone!

Global changes
--------------

getrlimit.2
prctl.2
sigaction.2
elf.5
signal.7
    mtk
        Added SEE ALSO entry referring to new core.5 page.

New pages
---------

mkdirat.2
    mtk
        New page describing mkdirat(2), new in 2.6.16.

mknodat.2
    mtk
        New page describing mknodat(2), new in 2.6.16.

core.5
    mtk
        New page describing core dump files.

mkfifoat.3
    mtk
        New page describing mkfifoat(3).

Changes to individual pages
---------------------------

accept.2
getpeername.2
getsockname.2
    Michael Haardt / mtk
        Document EINVAL error for 'len' argument < 0.

fcntl.2
    mtk
        Expanded discussion of mandatory locking.

getrlimit.2
    mtk
        Added BUGS text on 2.6.x handling of RLIMIT_CPU limit
        of zero seconds.  See
        http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2

mkdir.2
    mtk
        Added SEE ALSO entry referring to new mkdirat.2.

mknod.2
    mtk
        Added SEE ALSO entry referring to new mknodat.2.

open.2
    mtk / Roberto Jimenoca
        Clarified discussion of file types affected by O_NONBLOCK.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=360243

openat.2
    mtk
        Rewrote NOTES describing rationale for openat().
        Various other minor changes.

recv.2
    Stefan Puiu
        Removed a misleading cross-ref to socket.2.

shmop.2
    mtk
        Since 2.6.17-rc1, shmdt() gives the error EINVAL in a further
        circumstance: if shmaddr is not aligned on a page boundary.

unshare.2
    mtk
        Remove text saying that specifying invalid flags "is likely
        to cause compatibility problems" since the kernel now
        (2.6.17-rc1) contains an explicit check for invalid bits
        with a consequent EINVAL error.

mkfifo.3
    mtk
        Added SEE ALSO entry referring to new mkfifoat.3.

proc.5
    mtk
        Information on core_pattern and core_uses_pid has
        been migrated to the new core.5 page.

ip.7
    Stefan Puiu
        Removed paragraph referring to obsolete ipchains / ipfw(4).

sem_overview.7
    mtk
        Add SEE ALSO entry referring to pthreads.7.
top
==================== Changes in man-pages-2.30 ====================

Released: 2006-04-17

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andre Lehovich
Andries Brouwer
Karel Kulhavy
Stefan Puiu

Apologies if I missed anyone!

New pages
---------

linkat.2
    mtk
        New page describing linkat(), new in kernel 2.6.16

renameat.2
    mtk
        New page describing renameat(), new in kernel 2.6.16

symlinkat.2
    mtk
        New page describing symlinkat(), new in kernel 2.6.16

unlinkat.2
    mtk
        New page describing unlinkat(), new in kernel 2.6.16

Changes to individual pages
---------------------------

link.2
    mtk
        Added SEE ALSO entry pointing to new linkat.2 page.

openat.2
    mtk
        Added SEE ALSO entries pointing to new *at.2 pages.

rename.2
    mtk
        Added SEE ALSO entry pointing to new renameat.2 page.

rmdir.2
    mtk
        Added SEE ALSO entry pointing to new unlinkat.2 page.

symlink.2
    mtk
        Added SEE ALSO entry pointing to new symlinkat.2 page.

unlink.2
    mtk
        Added SEE ALSO entry pointing to new unlinkat.2 page.

termios.3
    mtk / Karel Kulhavy
        Document the feature test macros required to expose various flags.
    Karel Kulhavy
        Clarify 'speed' argument for cfsetispeed() text.
    Karel Kulhavy / mtk
        Note that LOBLK is not implemented on Linux.
    mtk
        Clarify arguments for cfsetspeed().
        Various formatting changes.

full.4
    Andre Lehovich
        Add a sentence describing the purpose of full(4).

core.5
    aeb / mtk
        Rework text describing circumstances in which
        core dump files are not produced.
    mtk / Stefan Puiu
        A core dump of a multithreaded process always includes the
        PID in the core filename.
    mtk / Stefan Puiu
        Eliminate some accidentally duplicated text.
top
==================== Changes in man-pages-2.31 ====================

Released: 2006-05-02

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Joshua Kwan
Justin Pryzby
Karel Kulhavy
Mark Glines
Martin (Joey) Schulze
Nishanth Aravamudan
Reuben Thomas
Ryan S. Arnold
Ulrich Drepper

Apologies if I missed anyone!

Page renamings
--------------

The following pages have been relocated into section 7, since
that is their more natural home.  SEE ALSO references in various
other pages have been adjusted.

epoll.4
fifo.4
futex.4
complex.5
environ.5
        (many pages outside man-pages actually *expect*
        'environ' to be in Section 7.)

ipc.5
        renamed to svipc.7

".so" link files have been created to link the old file locations to the
new file locations.  These links are added just to ensure that cross
references from any other (non-man-pages) pages will remain valid;
eventually these links will be removed.

New pages
---------

fstatat.2
    mtk
        New page for fstatat(2), new in 2.6.16.

adjtime.3
    mtk
        New page for adjtime(3).

error.3
    Justin Pryzby / mtk
        New page describing error() and error_at_line()
        Fixes http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=186307

program_invocation_name.3
    mtk
        New page describing program_invocation_name and
        program_invocation_short_name variables.

sockatmark.3
    mtk
        New page for sockatmark(3).

ftm.7
    mtk
        New page describing feature test macros.

time.7
    mtk
        New page giving an overview of "time" on Linux systems.

Global changes
--------------

getgroups.2
wait4.2
chown.2
chdir.2
gettimeofday.2
initgroups.3
dirfd.3
    mtk
        Simplified wording around requirement for _BSD_SOURCE
        feature test macro.

times.2
time.2
gettimeofday.2
getitimer.2
nanosleep.2
ctime.3
rtc.4
    mtk
        Added SEE ALSO referring to new time.7.

err.3
errno.3
perror.3
strerror.3
    Justin Pryzby / mtk
        Add SEE ALSO referring to new error.3.

getdate.3
printf.3
scanf.3
    mtk
        Added SEE ALSO entry referring to setlocale.3.

Changes to individual pages
---------------------------

accept.2
    Mark Glines
        Remove mention of SOCK_RDM from this page, since this socket
        type does not support accept()ing connections.

adjtimex.2
    mtk
        Modified text referring to adjtime(); added SEE ALSO for new
        adjtime.3 page.

fsync.2
    mtk, after a note by Karel Kulhavy
        Rewrote most of the DESCRIPTION, as well as some other parts
        the page, to clarify use and operation of, and rationale for,
        fsync(2) and fdatasync(2).

getitimer.2
    mtk
        Updated discussion of maximum timer value to reflect the fact
        that the default jiffy is now 4 milliseconds.

        Added text to note that current incorrect behavior of
        normalizing tv_usec >= 1000000 will be repaired in a future
        kernel; applications should be fixed now.

gettimeofday.2
    Karel Kulhavy
        Point out more explicitly that 'tz' argument should
        normally be NULL.
    mtk
        Various other minor edits and formatting fixes.

mount.2
    mtk
        Since kernel 2.6.16, MS_NOATIME and MS_NODIRATIME are settable
        on a per-mount basis.
        Detail exactly which mount flags can be changed on MS_REMOUNT.

nanosleep.2
    mtk / Karel Kulhavy
        Clarify RETURN VALUE discussion.

openat.2
    mtk
        Add SEE ALSO reference pointing to new fstatat.2.

program_invocation_short_name.3
    mtk
        New link to new program_invocation_name.3.

recv.2
    mtk
        Added SEE ALSO for new sockatmark.3.

rmdir.2
    Joshua Kwan / Martin (Joey) Schulze / mtk
        Correct wording of EBUSY case.
    mtk
        Add ".." case to ENOTEMPTY error

select.2
    Karel Kulhavy
        Note more clearly that fd_set arguments can be NULL.
    mtk / Karel Kulhavy
        Improve opening paragraph describing purpose of select().
    mtk
        Various other minor edits and formatting fixes.

semget.2
    mtk / Nishanth Aravamudan
        Add text to noting that the initial values of semaphores
        in a new set are indeterminate.

shmget.2
    mtk
        Add text noting that contents of newly created segment are zero
        values.

sigwaitinfo.2
    mtk
        Noted that all threads should block signal being waited for.

stat.2
    Nishanth Aravamudan / mtk
        Added NOTE that st_size is always returned as zero for most
        /proc files.
    mtk
        Add SEE ALSO reference pointing to new fstatat.2.

syscall.2
    Justin Pryzby / mtk
        Remove bogus BUGS text.

utime.2
    mtk
        Various minor changes.

confstr.3
    mtk
        Rewrote RETURN VALUE discussion.
        Updated CONFORMING TO.
        Removed BUGS.

ctanh.3
    Martin (Joey) Schulze / mtk
        Fix errors in DESCRIPTION.

ctime.3
    mtk
        The range of tm_sec is 0..60 (not 0..61).

error_at_line.3
error_message_count.3
error_on_per_line.3
error_print_progname.3
    mtk
        New links to new error.3.

fmemopen.3
    mtk / Ryan S. Arnold
        Add text noting that explicitly controlling output buffering
        may be useful to catch errors on output operations on an
        fmemopen() stream.

getline.3
    Justin Pryzby
        Add SEE ALSO pointing to getline.3.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=364772

strtod.3
strtoul.3
    mtk
        Describe correct handling of errno in order to
        distinguish error from success after the call.

        Added EXAMPLE section which points to strtol.3 which provides
        an example of the use of the analogous strtol(3).

strtol.3
    mtk / Justin Pryzby
        Add an example program.
    mtk
        Describe correct handling or errno in order to
        distinguish error from success after the call.

tmpfile.3
    Reuben Thomas
        DESCRIPTION does not need to say "temporary file name"
        just "temporary file", since the name is in any case
        unavailable to the user.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=363518
    mtk
        In DESCRIPTION:
        Change /automatically deleted when the program terminates normally/
        to     /automatically deleted when the program terminates/
        since deletion occurs on both normal and abnormal termination.

ip.7
    Karel Kulhavy / mtk
        Various wording improvements and clarifications.

signal.7
    mtk / Ulrich Drepper
        Add text noting that a signal's disposition is process-wide,
        shared by all threads.
    mtk
        Add text on changing signal dispositions.
        Add text on "signal mask and pending signals".
        Other minor edits.

time.7
    mtk
        Added SEE ALSO for new adjtime.3.

ld.so.8
    Justin Pryzby
        Remove bogus duplicate line.
top
==================== Changes in man-pages-2.32 ====================

Released: 2006-05-13

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Johannes Weiner
Justin Pryzby
Karel Kulhavy
Paul Brook
Pavel Heimlich

Apologies if I missed anyone!

New pages
---------

faccessat.2
    mtk
        New page for faccessat(2), new in 2.6.16.

fchmodat.2
    mtk
        New page for fchmodat(2), new in 2.6.16.

fchownat.2
    mtk
        New page for fchownat(2), new in 2.6.16.

futimesat.2
    mtk
        New page for futimesat(2), new in 2.6.16.

Changes to individual pages
---------------------------

access.2
    mtk
        Add SEE ALSO reference pointing to new faccessat.2 page.

capget.2
    mtk
        Reworded to reflect that capabilities are per-thread.

chmod.2
    mtk
        Add SEE ALSO reference pointing to new fchmodat.2 page.

chown.2
    mtk
        Add SEE ALSO reference pointing to new fchownat.2 page.

mmap.2
    mtk
        Updated discussion of MAP_NORESERVE since it is no longer
        restricted to MAP_PRIVATE mappings.
        Add reference to discussion of /proc/sys/vm/overcommit_memory
        in proc.5.

openat.2
    mtk
        Add SEE ALSO reference pointing to new faccessat.2, fchmodat.2,
        fchownat.2, futimesat.2 pages.

shmget.2
    mtk
        Document SHM_NORESERVE flag, new in 2.6.15.

truncate.2
    Paul Brook / mtk
        Expand text noting that ftruncate()/truncate() may fail if
        asked to extend a file beyond its current length.
        Add EPERM error.

utime.2
    mtk
        Add SEE ALSO reference pointing to new futimesat.2 page.

fopen.3
    Justin Pryzby / mtk
        Document 'm' (mmap) flag.
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=365754
    mtk
        Document 'c' (notcancel) flag.

futimes.3
    mtk
        Add SEE ALSO reference pointing to new futimesat.2 page.

qsort.3
    Johannes Weiner
        Add missing "const" qualifies to cast in EXAMPLE.
    mtk
        Slight rewording of comments in EXAMPLE.

termios.3
    Karel Kulhavy
        Clarify meaning of IXANY.
        Clarify relationship of MIN with VMIN and TIME with VTIME.
    mtk
        Noted that CIBAUD, OFDEL, and DELECHO are not implemented
        on Linux.
        Added explanatory paragraph for phrases "not in POSIX" and
        "XSI".

capabilities.7
    mtk
        Reworded to reflect that capabilities are per-thread.
        Add ioprio_set() to list of operations permitted by
        CAP_SYS_NICE.
        Add ioprio_set() IOPRIO_CLASS_RT and IOPRIO_CLASS_IDLE
        scheduling classes to list of operations permitted by
        CAP_SYS_ADMIN.
        Note effects of CAP_SYS_NICE for migrate_pages().
top
==================== Changes in man-pages-2.33 ====================

Released: 2006-05-23

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Justin Pryzby
Martin Osvald"
Stefan Puiu

Apologies if I missed anyone!

Page renamings
--------------

ftm.7
    mtk / Stefan Puiu
        renamed to the more suggestive feature_test_macros.7

New pages
---------

mq_getsetattr.2
    mtk
        New page briefly describing mq_getsetattr(2), the system
        call that underlies mq_setattr(3) and mq_getattr(3).

rpmatch.3
    Justin Pryzby / mtk
        New page for rpmatch(3).

Changes to individual pages
---------------------------

chmod.2
    mtk
        Remove mention of non-standard S_IREAD, S_IWRITE, S_IEXEC.
        POSIX does now document ELOOP.

open.2
    mtk
        Remove mention of non-standard S_IREAD, S_IWRITE, S_IEXEC.

mmap.2
    Justin Pryzby
        Add mincore(2) to SEE ALSO.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367401

msync.2
    Justin Pryzby
        Note that EINVAL can also be caused by
        flags == MS_SYNC | MS_ASYNC.

sched_setaffinity.2
    mtk
        Add CPU_ISSET, CPU_CLR, CPU_SET, CPU_ZERO to NAME section.

select.2
    mtk
        Various minor changes.

select_tut.2
    mtk
        Removed much material that is redundant with select.2.
        Various other changes.

umask.2
    mtk
        Substantial rewrite of description of 'mask'.

CPU_ISSET.3
CPU_CLR.3
CPU_SET.3
CPU_ZERO.3
    mtk
        New links to sched_setaffinity.2

FD_CLR.3
FD_ISSET.3
FD_SET.3
FD_ZERO.3
    mtk
        New links to select.2.

fts.3
    Justin Pryzby
        Add SEE also referring to ftw.3.

ftw.3
    Justin Pryzby
        Add SEE also referring to fts.3.

getline.3
    Justin Pryzby
        Various minor clarifications.

mkstemp.3
    mtk
        Clarify that O_EXCL is an open(2) flag.

mq_open.3
    Martin Osvald
        Fix prototype declaration for 'attr'.

mq_notify.3
    Martin Osvald
        s/sigev_signal/sigev_signo/

mq_setattr.3
    mtk
        New link to mq_getattr.3.

mq_timedreceive.3
    mtk
        New link to mq_receive.3.

mq_timedsend.3
    mtk
        New link to mq_send.3.

setlocale.3
    Justin Pryzby
        Added SEE ALSO referring to rpmatch.3.

sigandset.3
sigisemptyset.3
sigorset.3
    mtk
        New links to sigsetops.3.

stdio.3
    Justin Pryzby
        Added SEE ALSO referring to unlocked_stdio.3
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367667

strchr.3
    Justin Pryzby
        Add description of strchrnul().

strchrnul.3
    mtk
        New link to strchr.3.

undocumented.3
    Justin Pryzby / mtk
        Updated to remove some functions that don't exist, and
        therefore don't need to be documented.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367671

unlocked_stdio.3
    Justin Pryzby
        Added SEE ALSO referring to stdio.3
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367667

mq_overview.7
    mtk
        Added section describing relationship between library
        interfaces and system calls.
        Added SEE ALSO referring to new mq_getsetattr.2.

feature_test_macros.7
    Stefan Puiu
        Fix typo: s/_POSIX_C_SOURCE/_POSIX_SOURCE/
top
==================== Changes in man-pages-2.34 ====================

Released: 2006-06-20

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Aristeu Sergio Rozanski Filho
bert hubert
Chris Curtis
Eduardo Madeira Fleury
Joerg Scheurich
Justin Pryzby
Kenichi Okuyama
Marc Lehmann
Martin (Joey) Schulze
Mats Wichmann
Mike Frysinger
Peter Eiserloh
Stefan Puiu
Thomas Dickey
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

tzselect.8
zdump.8
zic.8
    mtk, Joey
        Added header comment noting that these pages are in the public
        domain.

bindresvport.3
getrpcent.3
getrpcport.3
rpc.3
xdr.3
rpc.5
    mtk, aeb, Joey
        Added following to top of these pages to clarify origin and
        license:
        .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)

New pages
---------

ioprio_set.2
    Eduardo Madeira Fleury, with edits by mtk, and review by Jens Axboe
        New page for ioprio_get(2) and ioprio_set(2), new in 2.6.13.

offsetof.3
    Justin Pryzby / mtk
        New page describing offsetof() macro.

Changes to individual pages
---------------------------

_exit.2
    mtk
        Add SEE ALSO referring to exit_group.2.

acct.2
    mtk
        Add SEE ALSO referring to acct.5.

fcntl.2
    mtk
        Explicitly mention term "dnotify" in discussion of F_NOTIFY.

inotify_add_watch.2
    Aristeu Sergio Rozanski Filho / mtk
        s/<inotify.h>/<sys/inotify.h>/ in prototypes.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369960
    mtk
        Renamed argument from 'path' to 'pathname'.
        Reword introductory paragraph to clarify that
        inotify_add_watch() may also modify an existing watch item.
    mtk
        The EINVAL error can also occur if 'fd' is not an inotify
        file descriptor.
    mtk
        Moved BUGS section from this page to inotify.7.

inotify_init.2
    Aristeu Sergio Rozanski Filho / mtk
        s/<inotify.h>/<sys/inotify.h>/ in prototypes.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369960

inotify_rm_watch.2
    Aristeu Sergio Rozanski Filho / mtk
        s/<inotify.h>/<sys/inotify.h>/ in prototypes.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369960
    mtk
        The EINVAL error can also occur if 'fd' is not an inotify
        file descriptor.

ioprio_get.2
    mtk
        New link to new ioprio_set.2.

mmap.2
    mtk
        Add SEE ALSO referring to remap_file_pages.2.

mount.2
    Kenichi Okuyama
        s/MNT_FORCE/MNT_EXPIRE/ under EINVAL error.

mremap.2
    Mike Frysinger
        s/unsigned long flags/int flags/ in SYNOPSIS.

pipe.2
    mtk
        Add SEE ALSO referring to popen.3.

posix_fadvise.2
    mtk
        Add SEE ALSO referring to readahead.2.

read.2
    mtk
        SEE ALSO for readv should refer to Section 2, not 3.

readahead.2
    mtk
        Add SEE ALSO referring to posix_fadvise.2.

send.2
    Peter Eiserloh
        Fix missing arguments in statement about equivalent send()
        and sendto() calls.

setsid.2
    mtk
        Add SEE ALSO referring to tcgetsid.3.

shmctl.2
    mtk
        Minor wording change at start of DESCRIPTION.

stat.2
    mtk
        Add SEE ALSO referring to access.2.

statfs.2
    mtk
        Relocated "Note" about f_fsid.

write.2
    mtk
        SEE ALSO for writev should refer to Section 2, not 3.

__setfpucw.3
    mtk, Joey
        Added license statement (GPL) after consultation with
        Joerg Scheurich.

assert_perror.3
    Justin Pryzby
        Add #define _GNU_SOURCE to prototype

difftime.3
    Joey
        Added note about time_t representation on other systems.
        Added CONFORMING TO.

ftw.3
    Justin Pryzby / mtk
        A fairly major revision...
        Document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
        Reorganized and rewrote much of the page
        Added an example program.

inet.3
    Marc Lehmann
        Fixed typo in NOTES.
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=370277

isalpha.3
    Joey
        Updated CONFORMING TO.

mktemp.3
    mtk
        Updated CONFORMING TO.

printf.3
    Walter Harms
        Add documentation of %m.

readdir.3
    mtk
        Added SEE ALSO referring to ftw.3.

re_comp.3
    mtk
        Note that these functions are obsolete in favor of regcomp(3).
    Justin Pryzby
        Add SEE ALSO referring to regcomp.3

scandir.3
    Mats Wichmann
        Reworded CONFORMING TO statement on scandir() and alphasort().

strchr.3
    Stefan Puiu
        Fix prototype for strchrnul().

strtoul.3
    Stefan Puiu
        Add text clarifying treatment of strings starting with
        minus sign.

tmpnam.3
    mtk, after comments by Justin Pryzby
        Add text noting the need to use open(O_EXCL).
    mtk
        Clarify discussion of use of free(3).
        Various other minor changes to text and formatting.

tmpfile.3
    mtk
        Updated CONFORMING TO.

tmpnam.3
    mtk, after comments by Justin Pryzby
        Add text noting the need to use open(O_EXCL).
        Updated CONFORMING TO.

undocumented.3
    mtk
        Remove offsetof(), which is now documented.

null.4
    mtk
        Added SEE ALSO referring to full.4.

console_codes.4
    Thomas Dickey
        Various improvements and corrections.

epoll.7
    mtk
        Added CONFORMING TO section mentioning FreeBSD kqueue and
        Solaris /dev/poll.

feature_test_macros.7
    mtk
        Added pointer to location of LFS specification.

futex.7
    mtk, after suggestion by Joey.
        Added license statement to page, after discussion with
        original author, bert hubert.
    mtk
        Reformat long lines; no content changes.

inotify.7
    mtk
        'path' argument renamed to 'pathname'.
        A few minor rewordings.
        Added BUGS section describing a couple of bugs.

ip.7
    mtk
        Add SEE ALSO referring to byteorder.3.

man.7
    Justin Pryzby
        Add SEE ALSO referring to groff_man(7).
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369253
top
==================== Changes in man-pages-2.35 ====================

Released: 2006-07-06

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andi Kleen
Andrew Morton
Bauke Jan Douma
Davide Libenzi
Denis Barbier
Horacio Rodriguez Montero
Johan Lithander
Justin Pryzby
Mike Frysinger
Stefan Puiu
Thorsten Kukuk

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

sync_file_range.2
    Andrew Morton / mtk
        New page for sync_file_range(2), new in kernel 2.6.17.

Changes to individual pages
---------------------------

adjtime.3
    mtk
        Noted BUG that occurs if 'delta' is specified as NULL.
        See http://bugzilla.kernel.org/show_bug.cgi?id=6761

bind.2
    Stefan Puiu
        Add EADDRNOTAVAIL error.
    Stefan Puiu / mtk
        Make example code more complete.

epoll_ctl.2
    mtk / Davide Libenzi
        Added EPOLLRDHUP description.
    mtk
        Added SEE ALSO referring to poll.2.

poll.2
    mtk / Davide Libenzi
        Added POLLRDHUP description.
    mtk
        The correct header file is <poll.h>, not <sys/poll.h>.
        Rewrote and reformatted various other parts.

readlink.2
    mtk
        Nowadays, readlink() returns 'ssize_t', as required in
        POSIX.1-2001.

wavelan.4
    mtk
        Added license statement.

nscd.conf.5
    Thorsten Kukuk
        Add documentation for various new fields.

passwd.5
    Horacio Rodriguez Montero
        Add explanation of 'x' character in 'password' field.
    mtk
        The proper name of "*" is "asterisk" not "star".

tcp.7
    Johan Lithander
        Update RFC reference for ECN.
    Andi Kleen
        Add sentence on "low memory" limit for tcp_mem on 32-bit systems.
top
==================== Changes in man-pages-2.36 ====================

Released: 2006-07-11

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Jens Axboe
Justin Pryzby
Kyle McMartin

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

MAINTAINING
    mtk
        How to maintain man-pages.

TODO
    mtk
        Things that it would be nice to get done for man-pages one day.

scripts/FIXME_list.sh
    mtk
        This script, intended for use by manual page maintainers,
        displays the FIXMEs in the manual page source files.

Changes to individual pages
---------------------------

fdatasync.2
fsync.2
    mtk
        Added SEE ALSO referring to sync_file_range.2.

sendfile.2
    mtk / Jens Axboe
        Fix description of 'offset' argument to explain the case
        where 'offset' is NULL.

ferror.3
    Justin Pryzby
        Add SEE ALSO referring to fdopen.3.

intro.3
    mtk
        Removed information about Section 3 subsections -- it doesn't
        reflect current reality, and probably never has.

        Added SEE ALSO referring to intro.2.

tcp.7
    Kyle McMartin
        Correction: tcp_window_scaling is ENabled by default.
top
==================== Changes in man-pages-2.37 ====================

Released: 2006-08-02

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Dean Gaudet
Frank van Viegen
Helmut Grohne
Ivana Varekova
Thomas Huriaux
Ville Skyttä

Apologies if I missed anyone!

Global changes
--------------

Thomas Huriaux / mtk

        Various formatting problems found as a result of reviewing the
        following command were fixed.

        for a in  $(wc man?/*.?| awk '$1 > 2 ' | grep -v total); do
            echo $a; groff -Tascii -wmac -mman $a > /dev/null;
        done 2>&1 | less

        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=378544

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

readlinkat.2
    mtk (after prompting from Ivana Varekova)
        New page for readlinkat(2), new in kernel 2.6.16.

Changes to individual pages
---------------------------

ldd.1
    Ville Skyttä
        Document "-u" option.

chdir.2
    mtk
        Noted effect of fork() and execve() on current working directory.

chroot.2
    mtk
        Noted effect of fork() and execve() on root directory.

epoll_ctl.2
    Frank van Viegen / mtk
        Fix description of EBADF error.

exevce.2
    mtk
        Add text noting that effective IDs are copied to
        saved set-IDs during execve().
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=379297

getitimer.2
    mtk
        Noted effect of fork() and execve() on interval timers.

getrlimit.2
    mtk
        Noted effect of fork() and execve() on resource limits.

getpriority.2
    mtk
        Noted effect of fork() and execve().

inotify_add_watch.2
    mtk
        Some rewording; included text describing required file
        permissions.

intro.2
    mtk
        Revised description of standards under CONFORMING TO.

makecontext.3
    Helmut Grohne / mtk
        Point out that args following 'argc' are int.
    mtk
        Added an example program.
        Various minor wording fixes.

mmap.2
    mtk
        Expand description of MAP_POPULATE.
    mtk, after prompting by Dean Gaudet
        Expand description MAP_NONBLOCK.
    mtk
        Various minor formatting fixes.

openat.2
    mtk
        Added SEE ALSO linking to readlinkat.2.

nanosleep.2
    mtk
        Noted buggy behavior in Linux 2.4 and earlier when
        nanosleep() is restarted after receiving stop+SIGCONT signals.

nice.2
    mtk
        Very minor rewording.

readlink.2
    mtk
        Added SEE ALSO linking to readlinkat.2.

sched_setscheduler.2
    mtk
        Noted preservation of scheduling parameters across execve().

setpgid.2
    mtk
        Noted effect of fork() and execve() on process group ID.

setsid.2
    mtk
        Noted effect of fork() and execve() on session ID.

umask.2
    mtk
        Noted effect of fork() and execve() on umask.

atexit.3
    mtk
        Noted inheritance of registrations across fork().

capabilities.7
    mtk
        Added material on privileges required for move_pages().
        CLONE_NEWNS needs CAP_SYS_ADMIN.
        keyctl(KEYCTL_CHOWN) and keyctl(KEYCTL_SETPERM) require
        CAP_SYS_ADMIN.
top
==================== Changes in man-pages-2.38 ====================

Released: 2006-08-03

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal

Apologies if I missed anyone!

Global changes
--------------

Most pages
    mtk
        There was a major reworking of the CONFORMING TO sections
        in most manual pages.

        * generally try to rationalize the names used for standards.
          The preferred names are now documented as the head words
          of the list in standards(7).  For the future: there is
          probably no need to talk about anything more than
          C89, C99, POSIX.1-2001 (or later), xBSD, and SVr4.
          (In particular, I've eliminated most references to XPG
          and SVID, replacing them with references to SUS or SVr4.)

        * eliminate discussion of errors that can occur on other
          systems.  This information exists only patchily in the
          manual pages, is probably of limited use, is hard to maintain,
          and was in some cases simply wrong (and probably always was).

        * Tried to ensure that those interfaces specified in C99 or
          POSIX.1-2001 are marked as such in their manual pages.

intro.1
intro.2
intro.3
intro.4
intro.5
intro.7
feature_test_macros.7
    mtk
        Added SEE ALSO referring to new standards.7.

Various pages
    mtk
        Changed instances of "HP UX" to "HP-UX".

Various pages
    mtk
        Changed instances of "DG-UX to "DG/UX"

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

standards.7
    mtk
        Based on material taken from intro.2, but expanded to
        include discussion of many additional standards.

Changes to individual pages
---------------------------

bind.2
    mtk
        Minor wording change for ENOTSOCK error.

intro.2
    mtk
        Removed information on standards to new standards.7.
top
==================== Changes in man-pages-2.39 ====================

Released: 2006-08-05

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        Updated CONFORMING TO and/or standards references
        in various pages that were missed for 2.38.

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

chdir.2
    mtk
        _XOPEN_SOURCE=500 also gets fchdir() prototype.

standards.7
    mtk
        Added a few more standards, and expand some explanations.
top
==================== Changes in man-pages-2.40 ====================

Released: 2006-09-04

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andi Kleen
Andries Brouwer
Christoph Hellwig
Chuck Ebbert
Samuel Thibault
Toralf Förster

Apologies if I missed anyone!

Global changes
--------------

faccessat.2
fchmodat.2
fchownat.2
fstatat.2
futimesat.2
linkat.2
mkdirat.2
mknodat.2
openat.2
readlinkat.2
renameat.2
symlinkat.2
    mtk (after a note by Alain Portal)
        Make naming of 'pathname' argument consistent; various
        minor rewordings.

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

clone.2
    mtk
        Reinstate text on CLONE_DETACHED, and add a few words.

execve.2
    mtk
        Added list of process attributes that are not preserved on exec().

fork.2
    mtk, after a suggestion by Christoph Hellwig
        Greatly expanded, to describe all attributes that differ
        in parent and child.

linkat.2
    mtk
        Document AT_SYMLINK_FOLLOW (new in 2.6.18).

set_mempolicy.2
    mtk / Andi Kleen
        Memory policy is preserved across execve().

write.2
    mtk / Alain Portal
        SEE ALSO for writev should refer to Section 2, not 3.
        (i.e., really make the change that was logged in 2.34)

getcwd.3
    Samuel Thibault / mtk
        Fix SYNOPSIS and CONFORMING TO text for getwd() and
        get_current_dir().
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=381692

proc.5
    Chuck Ebbert
        Document /proc/PID/auxv.

capabilities.7
    Alain Portal
        Restore text accidentally deleted in 2.39.

regex.7
    mtk / Alain Portal
        Change references to "1003.2" to "POSIX.2".
top
==================== Changes in man-pages-2.41 ====================

Released: 2006-10-12

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
Andries Brouwer
Andrew Morton
Britton Leo Kerin
Dan Jacobson
Guillem Jover
Hrvoje Niksic
Jens Axboe
Justin Pryzby
Kevin Ryde
Marcel Holtmann
Senthil Kumar
Stefan Puiu
Stuart MacDonald
Trond Myklebust

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

splice.2
tee.2
vmsplice.2
    Jens Axboe / Michael Kerrisk
        See also:
            http://lwn.net/Articles/118760/
            http://lwn.net/Articles/178199/
            http://lwn.net/Articles/179492/
            http://kerneltrap.org/node/6505
            http://lwn.net/Articles/179434/

Changes to individual pages
---------------------------

ldd.1
    Stefan Puiu
        Note glibc version where "ldd -u" appeared.

execve.2
    mtk
        The PR_SET_NAME setting is not preserved across an execve().

fork.2
    mtk
        Mappings marked with madvise(MADV_DONTFORK) are not inherited
        by child.

getdtablesize.2
    mtk
        Noted that sysconf(_SC_OPEN_MAX) is preferred in portable
        applications.

getpagesize.2
    mtk
        Noted that sysconf(_SC_PAGE_SIZE) is preferred in portable
        applications.
        _SC_PAGE_SIZE is available on most systems.

madvise.2
    mtk
        Document MADV_REMOVE, new in 2.6.16.
        Document MADV_DONTFORK / MADV_DOFORK, new in 2.6.16.

mount.2
    mtk / Trond Myklebust
        MNT_FORCE can cause data loss.

mmap.2
    mtk
        Added note on Linux's old (pre-2.6.12) buggy treatment of
        length==0.
    Justin Pryzby / mtk
        Added some EINVAL errors.

mremap.2
    mtk
        Remove superfluous "#include <unistd.h>" from SYNOPSIS.

msync.2
    mtk
        Added EBUSY error for case where MS_INVALIDATE is applied to
        a locked region.

posix_fadvise.2
    Andrew Morton
        Since 2.6.18, POSIX_FADV_NOREUSE is a no-op.

prctl.2
    Marcel Holtmann / mtk
        Since kernel 2.6.18, setting 2 for PR_SET_DUMPABLE is no longer
        possible.
    Guillem Jover
        Updated Linux versions where the options where introduced.
        Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
        PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
        PR_SET_FPEXC, PR_GET_FPEXC.
    Michael Kerrisk
        Document PR_GET_ENDIAN and PR_SET_ENDIAN.

remap_file_pages.2
    mtk
        Add "#define _GNU_SOURCE" to SYNOPSIS.

sync_file_range.2
    mtk
        Noted that sync_file_range() appeared in kernel 2.6.17.

vfork.2
    mtk
        Noted interactions with fork handlers in multithreaded programs.

wait4.2
    mtk
        Added feature test macros to SYNOPSIS.

clog2.3
    mtk / aeb / Kevin Ryde
        Fix broken text in description.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=386214

clog10.3
    Kevin Ryde
        Fix broken text in description.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=386214

mq_receive.3
    Britton Leo Kerin
        Fix return type in SYNOPSIS; should be "ssize_t" not "mqd_t".
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=387551

qsort.2
    Hrvoje Niksic
        Fix wording referring to the use of strcmp() in 'compar'
        function.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=391402

sendfile.2
    mtk
        Added SEE ALSO referring to new splice.2 page.

termios.3
    mtk
        Documented IUTF8 (which was new in kernel 2.6.4).

tzset.3
    mtk
        Added some TZ examples.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=386087

proc.5
    mtk
        Added delayacct_blkio_ticks (new in 2.6.18) to /proc/PID/statm.

ip.7
    Stuart MacDonald / Andi Kleen
        Fix discussion for TCP error queue /IP_RECVERR on TCP.

pthreads.7
    mtk
        Noted effect of RLIMIT_STACK resource limit for NPTL.

socket.7
    Senthil Kumar
        Place socket options in alphabetical order.
top
==================== Changes in man-pages-2.42 ====================

Released: 2006-11-24

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andrew Morton
Chuck Ebbert
Doug Goldstein
Eduard Bloch
Evan Teran
Pavel Heimlich
Petr Baudis
Randy Dunlap
Ulrich Drepper

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

brk.2
    Evan Teran / mtk
        Add text describing behavior of the Linux brk() system call
        and point out that the glibc brk() wrapper provides different
        behavior.
    mtk
        Note that sbrk() is implemented as a library function in glibc
        that calls the brk() system call.

futex.2
    mtk
        FUTEX_FD is scheduled for removal in June 2007.

getaddrinfo.3
getnameinfo.3
    Ulrich Drepper, with edits by mtk
        Add text describing Internationalized Domain Name
        extensions.

open.2
    mtk / Eduard Bloch
        Fix description of O_LARGEFILE to mention required feature test
        macros.

ptrace.2
    Chuck Ebbert
        Since Linux 2.6.18, the PID of the new process is also available
        for PTRACE_EVENT_VFORKDONE.

syslog.3
    Doug Goldstein
        Fix header file required for vsyslog() in SYNOPSIS.

wcwidth.3
    Petr Baudis
        Fix CONFORMING TO.

core.5
    mtk
        Linux 2.4.21 added core_pattern (which was already in 2.6).
        Noted a few more reasons why a core dump file might not
        be produced.
top
==================== Changes in man-pages-2.43 ====================

Released: 2006-11-29

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
David Brownell
Eduard Bloch
Egmont Koblinger
Reuben Thomas

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

ioperm.2
    mtk
        Clarify discussion of privilege requirements.
        Added ENOMEM to ERRORS.

open.2
    mtk / Eduard Bloch
        Clarify description of O_LARGEFILE.

crypt.3
    Egmont Koblinger
        Make description of MD5 output string less ambiguous.

strerror.3
    Reuben Thomas
        Add C99 to CONFORMING TO; see
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=400634

rtc.4
    David Brownell

        Update the RTC man page to reflect the new RTC class framework:

        - Generalize ... it's not just for PC/AT style RTCs, and there
          may be more than one RTC per system.

        - Not all RTCs expose the same feature set as PC/AT ones; most
          of these ioctls will be rejected by some RTCs.

        - Be explicit about when {A,P}IE_{ON,OFF} calls are needed.

        - Describe the parameter to the get/set epoch request; correct
          the description of the get/set frequency parameter.

        - Document RTC_WKALM_{RD,SET}, which don't need AIE_{ON,OFF} and
          which support longer alarm periods.

        - Hey, not all system clock implementations count timer irqs any
          more now that the new RT-derived clock support is merging.

proc.5
    mtk
        s/fseek(3)/lseek(2)/ under /proc/PID/mem entry.

feature_test_macros.7
    mtk / Eduard Bloch
        The LFS spec is now at http://opengroup.org/platform/lfs.html

raw.7
udp.7
    Andi Kleen
        Describe the correct default for UDP/RAW path MTU discovery.
top
==================== Changes in man-pages-2.44 ====================

Released: 2007-04-04

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andre Majorel
Benjamin Gilbert
Carlo Marcelo Arenas Belon
Chuck Ebbert
Ivana Varekova
Jakub Jelinek
John Ward
Jorge Peixoto de Morais Neto
Julien Blache
Julien Cristau
Justin Pryzby
Martín Ferrari
Mike Frysinger
Nick Piggin
Nick Pollitt
Nicolas François
Pádraig Brady
Premysl Hruby
Reuben Thomas
Samuel Thibault
Serge E. Hallyn
Thomas Huriaux
Timo Sirainen
Val Henson

Apologies if I missed anyone!

New pages
---------

termio.7
    mtk, after a bit of prodding by Reuben Thomas
        A brief discussion of the old System V termio interface,
        with pointers to pages that will contain the information
        that the reader probably wants.

scripts/find_repeated_words.sh
    mtk
        Find consecutive duplicate words in a man page, some of
        which may be grammar errors.

Global changes
--------------

Various pages
    Justin Pryzby / mtk
        Add "#define _ATFILE_SOURCE" to SYNOPSIS in following pages:
            faccessat.2
            fchmodat.2
            fchownat.2
            fstatat.2
            futimesat.2
            linkat.2
            mkdirat.2
            mknodat.2
            openat.2
            readlinkat.2
            renameat.2
            symlinkat.2
            unlinkat.2
            mkfifoat.3

Various pages
    mtk
        Various references to "getty" were changed to "mingetty", since
        that is the manual page more likely to be found on current systems.

Various pages
    mtk, after a suggestion by Reuben Thomas
        Updated various header pages to accurately reflect which functions
        are and are not part of C89.  Also fixed/improved a few other
        CONFORMING TO entries.

Various pages
    mtk
        s/Unices/Unix systems/ on the 5 pages where it appears.

Various pages
    mtk
        Wrapped long source lines in the following files
            getsockopt.2
            mknodat.2
            io_setup.2
            select_tut.2
            select.2
            readlinkat.2
            io_cancel.2
            syslog.2
            wcsncat.3
            getipnodebyname.3
            cmsg.3
            wcpncpy.3
            wcsrtombs.3
            wcstok.3
            fgetwc.3
            wmemcmp.3
            wcsspn.3
            div.3
            modf.3
            stdio_ext.3
            ctermid.3
            des_crypt.3
            wcsncmp.3
            wmemchr.3
            wcsstr.3
            wmemcpy.3
            wprintf.3
            wcsnrtombs.3
            termios.3
            erf.3
            ceil.3
            lround.3
            nextafter.3
            wcsncpy.3
            wmemset.3
            getw.3
            console_ioctl.4
            sk98lin.4
            environ.7
            unix.7
            time.7

Various pages
    mtk
        Added a SEE ALSO reference for feature_test_macros(7) to all
        pages where a feature test macro appears in the SYNOPSIS.

Various pages
    mtk
        Added SEE ALSO entry pointing to time.7
            alarm.2
            nanosleep.2
            ualarm.3
            usleep.3

Various pages
    Justin Pryzby / mtk
        Fixed consecutive duplicate word typos on a number of pages.

Typographical or grammatical errors have been corrected in several
places.  (Special thanks to Nicolas François!)

Changes to individual pages
---------------------------

access.2
    mtk
        Since 2.6.20, access() honors the MS_NOEXEC mount flag.
    Jorge Peixoto de Morais Neto / mtk
        Improve ENOENT description.

clone.2
    mtk
        Added some detail to the prototype.
        Added some notes on IA-64's clone2().

epoll_ctl.2
    mtk
        Add text to note that EPOLLRDHUP appeared in kernel 2.6.17.

faccessat.2
    Justin Pryzby
        Various fixes as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411177
        * s/effective/real/ in description text.
        * added <fcntl.h> to synopsis.
        * various other changes.

getrlimit.2
    mtk / Fedora downstream patches; thanks to Ivana Varekova
        Added a few words to note that RLIMIT_NPROC is really a limit on
        threads.

io_cancel.2
io_destroy.2
io_getevents.2
io_setup.2
io_submit.2
    Fedora downstream patches; thanks to Ivana Varekova
        s%linux/aio.h%libaio.h% in SYNOPSIS.
        Changed return type from "long" to "int".

mbind.2
    Samuel Thibault / mtk
        Fix EINVAL description.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411777

mincore.2
    Nick Piggin
        Kernel 2.6.21 fixes several earlier bugs in mincore().
    Nick Pollitt
        Remove words "of a file" -- mincore() is describing
        memory residence information, not properties of a file.
    mtk
        Rewrote various parts to make the page clearer.

mmap.2
    mtk
        Rewrote and reorganized various parts to be clearer.
    Taken from Fedora downstream patches; thanks to Ivana Varekova
        Removed text stating that mmap() never returns 0; that's
        not true.

mount.2
    mtk / Val Henson
        Document MS_RELATIME, new in Linux 2.6.20.

open.2
    Andre Majorel / mtk
        On Linux, the error returned when opening a large file on a
        32-bit system is actually EFBIG, not EOVERFLOW.

posix_fadvise.2
    Pádraig Brady
        Fix RETURN VALUE description: returns error number of failure.

rename.2
    mtk / Timo Sirainen
        Various improvements to DESCRIPTION.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=416012

semop.2
    mtk
        If sops contains multiple operations, then these are performed
        in array order.  All Unix systems that I know of do this,
        and some Linux applications depend on this behavior.  SUSv3
        made no explicit statement here, but SUSv4 will explicitly
        require this behavior.
        Small rewording of explanation of "atomically".

signal.2
    Nicolas François
        Fix incorrect argument name in DESCRIPTION.
    mtk
        Small wording improvement.

socket.2
    Nicolas François
        Add reference to ipv6.7 page.

socketcall.2
    Nicolas François
        Fix .TH line.

splice.2
    Benjamin Gilbert
        Fix inconsistent argument names in SYNOPSIS and DESCRIPTION.

statvfs.2
    mtk
        Small wording clarification.

symlink.2
    mtk / Nicolas François
        Removed cryptic text under CONFORMING to referring to
        "open(2) and NFS".  There is no relevant text in open.2 as
        far as I (mtk) can see.

time.2
    mtk / Reuben Thomas
        Remove sentence "gettimeofday() obsoleting time() on 4.3BSD".
        This information is old, and probably no longer relevant.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=403888

write.2
    mtk, after an idea from a downstream Fedora patch.
        Clarified discussion of /count == 0/ case.

ptrace.2
    Chuck Ebbert
        When the parent receives an event with PTRACE_EVENT_* set,
        the child is not in the normal signal delivery path.  This
        means the parent cannot do ptrace(PTRACE_CONT) with a signal
        or ptrace(PTRACE_KILL).  kill() with a SIGKILL signal can be
        used instead to kill the child process after receiving one
        of these messages.

sched_setaffinity.2
    mtk
        Fix glibc version number in description of 'cpusetsize' argument.

vfork.2
    mtk
        Stripped some excess/outdated text from the BUGS section.

basename.3
    mtk / Jorge Peixoto de Morais Neto
        Add text to clarify that the pointer returned by these
        functions may be into some part of 'path'.

dlopen.3
    Taken from Fedora downstream patches; thanks to Ivana Varekova
    + Carlo Marcelo Arenas Belon
        Add "#include <stdlib.h>" to example program.

fclose.3
    mtk
        Complete rewrite.  The existing page was hard to read,
        and the RETURN VALUE description seems to be wrong.

getopt.3
    mtk
        Added getopt() example program.
    mtk
        Add a few words to clarify the operation of the GNU-specific
        double-colon feature, which allows options to have optional
        arguments.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=352139

glob.3
    Nicolas François
        Fix PROTOTYPE.

inet_network.3
    mtk, after an idea from a downstream Fedora patch.
        Clarified description of inet_network().

log.3
    Nicolas François
        Fix .TH line.

log10.3
    Nicolas François
        Fix .TH line.

malloc.3
    Nicolas François
        Small rewording to mention calloc().

posix_openpt.3
    Martín Ferrari
        Fix return type in SYNOPSIS; as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=400971
        Needs _XOPEN_SOURCE == 600; as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=400975
    Julien BLACHE
        s/ptsname/posix_openpt/ in RETURN VALUE

re_comp.3
    Taken from Fedora downstream patches; thanks to Ivana Varekova
        Add "#define _REGEX_RE_COMP" to SYNOPSIS.

regex.3
    Nicolas François
        Fix .TH line.

termios.3
    mtk
        Added .SS headers to give some structure to this page; and a small
        amount of reordering.
    mtk
        Added a section on canonical and non-canonical mode.
    mtk
        Enhanced the discussion of "raw" mode for cfmakeraw().
    mtk
        Document CMSPAR.
    mtk
        Make description of PARODD a little clearer.
    Reuben Thomas
        Add SEE ALSO link to tty_ioctl.4
    mtk
        Add SEE ALSO link to console_ioctl.4

ualarm.3
    mtk
        Removed BSD prototype from synopsis.
        Various rewordings.

usleep.3
    mtk
        Removed BSD prototype from synopsis.
        Various rewordings.

termcap.5
    Taken from Fedora downstream patches; thanks to Ivana Varekova
        s/curses/ncurses/ under SEE ALSO

bootparam.7
    Taken from Fedora downstream patches; thanks to Ivana Varekova
        Documented "mem=nopentium".

feature_test_macros.7
    mtk
        The default treatment of _POSIX_C_SOURCE changed in glibc 2.4.
    mtk, after a suggestion by Justin Pryzby
        Added some text warning that the "__" macros that
        <features.h> defines internally should never be
        directly defined by programs.
    mtk, based on notes by Jakub Jelinek
        Document _FORTIFY_SOURCE
        (See http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html )
    mtk
        Document _REENTRANT and _THREAD_SAFE.

mdoc.7
    mtk / Nicolas François
        Remove CONFIGURATION section, since this does not seem to be
        true for Linux.

svipc.7
    Nicolas François
        Fix data types in associated data structures;
        remove nonexistent semzcnt and semncnt fields.

time.7
    mtk
        Since kernel 2.6.20, the software clock can also be 300 HZ.
top
==================== Changes in man-pages-2.45 ====================

Released: 2007-04-05

Global changes
--------------

This release consists mainly of formatting fixes (to a large
number of pages) to achieve greater consistency across pages.
With the exception of the few individual changes noted below,
no changes were made to content.

Changes to individual pages
---------------------------

io_destroy.2
io_getevents.2
io_setup.2
io_cancel.2
io_submit.2
    mtk
        Clarified RETURN VALUE text

bindresvport.3
    mtk
        Rewrote prototype using modern C syntax.
top
==================== Changes in man-pages-2.46 ====================

Released: 2007-04-06

Global changes
--------------

This release consists mainly of formatting fixes (to a large
number of pages) to achieve greater consistency across pages:

* Most instances of two or more consecutive blank lines in man
  page output were shrunk to a single line.
* A number of example programs were reformatted
  to more closely match K&R style.
* In various places (mainly code examples), the use of tabs was
  replaced by spaces

With the exception of the few individual changes noted below,
no changes were made to content.

Changes to individual pages
---------------------------

bdflush.2
    mtk
        Add <sys/kdaemon.h> header file to SYNOPSIS.

sched_rr_get_interval.2
    mtk
        Moved timespec definition from SYNOPSIS into description.

select_tut.2
    mtk
        Make SYNOPSIS match select.2.
top
==================== Changes in man-pages-2.47 ====================

Released: 2007-05-04

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
John Heffner

Apologies if I missed anyone!

Global changes
--------------

This release consists mainly of changes to source file layout
(wrapped long lines; stripped trailing white space; started new
sentences on new lines).

There is very little change to output formatting or content (see the
notes below).

Changes to individual pages
---------------------------

sched_rr_get_interval.2
    mtk
        Remove crufty statement that this system call is not implemented.
        The nice interval can be used to control the size of
        the round-robin quantum.
        Corrected .TH line.

ip.7
    John Heffner / mtk
        Document IP_PMTUDISC_PROBE, which will be in 2.6.22.
top
==================== Changes in man-pages-2.48 ====================

Released: 2007-05-04

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Colin Watson
Justin Pryzby

Apologies if I missed anyone!

Global changes
--------------

This release consists mainly of changes to source file layout
(wrapped long lines; stripped trailing white space; started new
sentences on new lines).

There is very little change to output formatting or content (see the
notes below).

Various pages
    mtk
        In various places where it occurred,
        s/nonnegative/non-negative/

Various pages
    mtk
        s/wide character/wide-character/ when used attributively.

Changes to individual pages
---------------------------

man.7
    Justin Pryzby / Colin Watson / mtk
        .SH doesn't require quotes.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411303
top
==================== Changes in man-pages-2.49 ====================

Released: 2007-05-20

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Akihiro MOTOKI
Bruno Haible
Justin Pryzby

Apologies if I missed anyone!

New pages
---------

bsd_signal.3
    mtk
        Documentation of bsd_signal().

euidaccess.3
    mtk
        Manual page for euidaccess() and eaccess().

getsubopt.3
    mtk / Justin Pryzby
        Documentation of getsubopt().

sysv_signal.3
    mtk
        Documentation of sysv_signal().

New links
---------

epoll_pwait.2
    mtk
        New link to epoll_wait.2.

eaccess.3
    mtk
        New link to new euidaccess.3,

sem_timedwait.3
    mtk
        New link to sem_wait.3.

sem_trywait.3
    mtk
        New link to sem_wait.3.

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

access.3
    mtk
        Added SEE ALSO ref to new euidaccess.3 page.

epoll_wait.2
    mtk
        Added description of epoll_pwait(), new in kernel 2.6.19.

execve.2
    mtk
        Add text noting that Linux allows 'argv' and 'envp' to be
        NULL, but warning that this is non-standard and non-portable,
        and should be avoided in portable programs.
        Bug filed (http://bugzilla.kernel.org/show_bug.cgi?id=8408)
        to get this changed, but maybe that won't be done because it
        is an ABI change.
    mtk
        Added an example program.
    mtk
        Expanded the discussion of interpreter scripts and the
        'optional-arg' argument of an interpreter script.
        For further info, see
        http://homepages.cwi.nl/~aeb/std/hashexclam-1.html
        http://www.in-ulm.de/~mascheck/various/shebang/
    mtk
        Added text noting that FD_CLOEXEC causes record locks to be
        released.
    mtk
        Mention effect of MS_NOSUID mount(2) flag for set-user-ID
        programs.
    mtk
        Expanded description of handling of file descriptors during
        execve(), adding text to note that descriptors 0, 1, and 2
        may be treated specially.

faccessat.3
    mtk
        Added SEE ALSO ref to new euidaccess.3 page.

mmap.2
    mtk
        Place MAP_* flags list in alphabetical order.

readv.2
    mtk
        A fairly substantial rewrite, which among other things
        fixes the problem reported by Kyle Sluder in
        http://bugzilla.kernel.org/show_bug.cgi?id=8399
        And added some example code.

sigaction.2
    mtk
        Added text referring to the discussion of async-signal-safe
        functions in signal(7).
        A few other minor formatting and wording changes.

signal.2
    mtk
        Moved the discussion of async-signal-safe functions to signal(7).
        Added text referring to the discussion of async-signal-safe
        functions in signal(7).
        Added SEE ALSO entries referring to new bsd_signal.3 and
        sysv_signal.3 pages.

copysign.3
    Bruno Haible
        Clarify discussion of negative zero.

getopt.3
    mtk
        Add SEE ALSO ref to new getsubopt.3.

iconv_open.3
    Bruno Haible
        Describe the glibc/libiconv //TRANSLIT and //IGNORE extensions
        for 'tocode'.

iswblank.3
    Bruno Haible
        Update CONFORMING TO; iswblank() is in POSIX.1-2001.

inotify.7
    mtk
        Definitions for IN_DONT_FOLLOW, IN_MASK_ADD, and IN_ONLYDIR
        were added to glibc in version 2.5.

signal.7
    mtk
        Incorporated (and slightly modified) the text on
        async-signal-safe functions that was formerly in signal(2).
        Added SEE ALSO entries referring to new bsd_signal.3 and
        sysv_signal.3 pages.
top
==================== Changes in man-pages-2.50 ====================

Released: 2007-05-21

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andreas Halter
Laird Shaw
Mike Frysinger

Apologies if I missed anyone!

Removed pages (!)
-----------------

Most Section 1 man pages are removed
    mtk (with help from Mike Frysinger, Laird Shaw, Andreas Halter)
        Once upon time Andries added a number of Section 1 manual pages
        to man-pages.  However, since that time, those pages have not
        seen much maintenance, and are not in fact distributed in most
        distributions.  Instead most distributions supply the
        coreutils versions of these pages, which are currently
        maintained.  In addition, man-pages provides the 1p pages,
        which document the portable subset of functionality of these
        commands.  Since the man1 pages are mostly unneeded, and
        out of date, I'm removing them.  The following pages disappear:

            chgrp.1
            chmod.1
            chown.1
            cp.1
            dd.1
            df.1
            diff.1
            dir.1
            dircolors.1
            du.1
            install.1
            ln.1
            ls.1
            mkdir.1
            mkfifo.1
            mknod.1
            mv.1
            rm.1
            rmdir.1
            touch.1
            vdir.1

        The following Section 1 pages will be kept:

            intro.1
            ldd.1
            time.1
top
==================== Changes in man-pages-2.51 ====================

Released: 2007-05-28

Global changes
--------------

Various pages
    mtk
        (Hopefully) all cross references outside a page now include a
        section number.  This should permit better resulting output
        from a man2html-type conversion.

Various pages
    mtk
        Convert function formatting of the form "\fBname\fP()" to
        ".BR name ()".

Changes to individual pages
---------------------------

futimesat.2
    mtk
        s/futimes/futimesat/ in .SH NAME line.

msgop.2
    mtk
        Put "msgrcv" and "msgsnd" in .SH NAME line.

mount.2
    mtk
        Add "umount2" to .SH NAME line.

wait.2
    mtk
        Add "waitid" to .SH NAME line.

getopt.3
    mtk
        Add "getopt_long" and "getopt_long_only" in .SH NAME line.

sem_wait.3
    mtk
        Add "sem_timedwait" and  "sem_trywait" to .SH NAME line.

stdarg.3
    mtk
        Add "va_start", "va_arg", "va_end", "va_copy" to .SH NAME line.
top
==================== Changes in man-pages-2.52 ====================

Released: 2007-05-29

    "A foolish consistency is the hobgoblin of little minds, adored by
     little statesmen and philosophers and divines"

        Ralph Waldo Emerson (1803-1882)

    "But damn it, these man pages are a mess!"

Global changes
--------------

Most of the changes below are about bringing greater consistency
to manual pages, including reducing the wide range of .SH
Section headings.

Typographical or grammatical errors have been corrected in several
places.

Various pages
    mtk
        Make 'manual' component of .TH line into the string
        "Linux Programmer's Manual".
        Reason: consistency.

Various pages
    mtk
        Changed date in .TH line into form YYYY-DD-MM.
        Reason: consistency.

Various pages
    mtk
        Some .SH header lines were made into .SS lines.  (One of the aims
        here is to reduce the number of non-standard .SH lines.)

Various pages
    mtk
        Change title .SH sections named "NOTE" to "NOTES", in some cases
        also changing the location of the section within the page.
        Reason: consistency.

Various pages
    mtk
        Commented out .SH AUTHOR sections; the right place for
        documentation authorship sections is usually comments at the
        top of the page source.

Various pages
    mtk
        Changed .SH HISTORY to .SH VERSIONS.
        Reason: in many cases, HISTORY was being used to describe
        Linux/glibc version information, as was already done for
        VERSIONS sections in other pages.

Various pages
    mtk
        Removed HISTORY section, or moved it as a subsection or paragraphs
        under another section e.g., NOTES.
        Reason: there are too many arbitrary section (.SH) names, and
        a HISTORY section never was consistently used across Linux
        manual pages.

Various pages
    mtk
        Moved SEE ALSO section to be last section on the page
        Reason: consistency -- and this is where SEE ALSO should be!

Various pages
    mtk
        Relocated GLIBC NOTES as subsection under NOTES
        Reason: reduce number of arbitrary section (.SH) names.

Various pages
    mtk
        Relocated LINUX NOTES as subsection under NOTES
        Reason: reduce number of arbitrary section (.SH) names.

Various pages
    mtk
        Renamed some "AVAILABILITY" sections to "VERSIONS".
        Reason: consistency.

Various pages
    mtk
        Renamed some "DIAGNOSTICS" sections to "RETURN VALUE".
        Reason: consistency.

getopt.3
tzselect.8
    mtk
        s/\.SH ENVIRONMENT VARIABLES/.SH ENVIRONMENT/
        Reason: consistency.

intro.2
select.2
sysctl.2
bsearch.3
dlopen.3
envz_add.3
fmtmsg.3
getgrent_r.3
getgrouplist.3
getpwent_r.3
getutent.3
hsearch.3
rtime.3
strptime.3
tsearch.3
vcs.4
wordexp.3
    mtk
        s/return 0/exit(EXIT_FAILURE)/ in main() of function example
        program.
        Reason: consistency.

mprotect.2
select_tut.2
dlopen.3
getgrent_r.3
getopt.3
getpwent_r.3
hsearch.3
select_tut.2
tsearch.3
    mtk
        Use symbolic constants (EXIT_SUCCESS, EXIT_FAILURE) in calls
        to exit().
        Reason: consistency.

access.2
chown.2
lseek.2
open.2
read.2
utmp.5
    mtk
        Renamed RESTRICTIONS section to NOTES, or moved text in a
        RESTRICTIONS section under existing NOTES section.
        Reason: consistency, and reduce number of arbitrary section (.SH)
        names.

Changes to individual pages
---------------------------

capget.2
    mtk
        s/\.SH FURTHER INFORMATION/.SH NOTES/

dup.2
    mtk
        s/\.SH WARNING/.SH NOTES/

kill.2
    mtk
        Renamed LINUX HISTORY section to LINUX NOTES, and relocated
        within page.

select_tut.2
    mtk
        Relocated example program and made its .SH title "EXAMPLE".

sigaltstack.2
    mtk
        Move code example into its own EXAMPLE section.

sigreturn.2
    mtk
        s/\.SH WARNING/.SH NOTES/

setuid.2
    mtk
        s/\.SH "LINUX-SPECIFIC REMARKS"/.SH LINUX NOTES/

shmget.2
    mtk
        Remove section about effect of fork()/exec()/exit(); shmop.2
        contains the same text, and it only needs to be said once.

shmop.2
    mtk
        Minor rewording under DESCRIPTION.

daemon.3
    mtk
        Minor wording and formatting changes.

encrypt.3
    mtk
        Removed statement that glibc unconditionally exposes declarations
        of encrypt() and setkey(), since portable applications must
        use <unistd.h> and define _XOPEN_SOURCE to obtain the declarations
        of setkey() and encrypt().  Adjusted example program accordingly.

mkstemp.3
    mtk
        Slight rewording.

LDP.7
    mtk
        Minor wording and formatting changes.

man.7
    mtk
        Substantial rewrite, revising and extending the discussion
        about desired conventions for writing pages.
        There will be further updates to this page in the next few
        man-pages releases.
top
==================== Changes in man-pages-2.53 ====================

Released: 2007-05-30

    "A foolish consistency is the hobgoblin of little minds, adored by
     little statesmen and philosophers and divines"

        Ralph Waldo Emerson (1803-1882)

    "But damn it, these man pages are a mess!"

Global changes
--------------

Many many pages
    mtk
        Reordered sections to be more consistent, in some cases renaming
        sections or shifting paragraphs between sections.

man7/*
    mtk
        In various pages in this section, .SH headings were
        converted to .SS.
top
==================== Changes in man-pages-2.54 ====================

Released: 2007-06-07

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Emmanuel Mogenet
Michael Berg

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        Where there is an instruction in the SYNOPSIS about linking
        or compiling with a certain option, the option is now
        marked up in italics (e.g., "\fI-lm\fP").

Various pages
    mtk
        Added page numbers to page cross references.

A few pages
    mtk
        s/manpage/man page/, for consistency.

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

man-pages.7
    mtk
        A description of the conventions that should be followed
        when writing pages for the man-pages package.

Removed pages
-------------

man1/README
    mtk
        Already deleted most of the man1 pages previously, so
        this doesn't need to stay.

LDP.7
    mtk
        Removed this page since it is out of date, and the proper place
        to go for up-to-date information is http://www.tldp.org/

ksoftirq.9
    mtk
        Reason: this was the only Section 9 page, and it is old
        (Linux 2.4).  The man9 section never took off as an idea, and
        I see little point in keeping a Section 9 with just a single
        old page.

Changes to individual pages
---------------------------

HOWTOHELP
    mtk
        Moved some material out of here into new man-pages.7.

alloc_hugepages.2
    mtk
        Minor rewrites, eliminating some duplication, and removing
        some outdated text.

epoll_pwait.2
    Michael Berg
        Fix broken link path;
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=425570

fcntl.2
    mtk
        Remove misleading text about setting O_ASYNC when calling
        open(); one must use fcntl() F_SETFL for this task.

fdatasync.2
    mtk
        Converted outdated BUGS note about fdatasync() being
        equivalent to fsync() on Linux 2.2 into a NOTES note
        about this historical behavior.

futex.2
    mtk
        Small rewording to fix "fails with the error EWOULDBLOCK"
        rather than "returns EWOULDBLOCK".
        See Red Hat bug 172828.

mprotect.2
    mtk, after an observation by Emmanuel Mogenet
        A much improved example program.
    mtk
        Significant rewrites and additions to description.

mremap.2
    mtk
        Remove text about the nonexistent BSD mremap() -- too
        much information, in my opinion.

sched_yield.2
    mtk
        Added ERRORS section.

set_mempolicy.2
    mtk
        Moved text for "Versions and Library Support".

set_tid_address.2
    mtk
        Small rewording in RETURN VALUE section.

sigaction.2
    mtk
        Add EXAMPLE section with a pointer to example in mprotect.2.

sync_file_range.2
    mtk
        Fix return type in SYNOPSIS.  Add RETURN VALUE section.

atexit.3
    mtk
        Small rearrangement of text under NOTES.

bindresvport.3
    mtk
        Rewrite and substantial additional text.

exec.3
    mtk
        Minor clarifications for text on execlp() and execvp().  Removed
        FILES section, since it provides no useful additional info.

fenv.3
    mtk
        Moved link instructions from NOTES to SYNOPSIS.
        Added feenableexcept, fedisableexcept, fegetexcept
        to .SH NAME list.

fputwc.3
    mtk
        Added 'putwc' to .SH NAME list.

gethostbyname.3
    mtk
        s/int/socklen_t/ for type of gethostbyaddr() 'len' argument,
        and add a few more words in NOTES about the type used here.

login.3
    mtk
        Removed remark from NOTES about linking with -lutil; add
        text on that point to SYNOPSIS.

openpty.3
    mtk
        Removed redundant remark from NOTES about linking with -lutil
        since there is text on that point under SYNOPSIS.

sysconf.3
    mtk
        Added SEE ALSO referring to getconf(1).

unlocked_stdio.3
    mtk
        Revised .SH NAME section.

ascii.7
    mtk
        Minor rearrangement of order of text.

capabilities.7
    mtk
        s/exec()/execve(2)/ in various places.

complex.7
    mtk
        Changed "atan(1)" to "atan(1.0)" to prevent some versions of
        man2html(1) from mistaking that string as a page cross reference.

rtnetlink.7
    mtk
        Small restructuring to avoid 'cannot adjust line' from man(1).

ldconfig.8
    mtk
        Removed now very out-of-date sentence about need to link shared
        libraries with -lc.

man.7
    mtk
        Various text was moved out of this page into the new man-pages.7.

mdoc.7
    mtk
        Added SEE ALSO referring to new man-pages.7.

mdoc.samples.7
    mtk
        A few changes, hopefully done right, to eliminate some
        errors to stderr when rendering with man(1).

rtnetlink.7
    mtk
        Shorten a line in table so it fits in 80 columns.
        Minor rewording under BUGS.

tzselect.8
    mtk
        Moved EXIT STATUS section.
top
==================== Changes in man-pages-2.55 ====================

Released: 2007-06-10

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alexander Taboriskiy
Joey Hess
John Reiser
Julien Cristau
Justin Pryzby
Martin (Joey) Schulze
Mike Frysinger
Serge van den Boom
Ulrich Drepper
Xose Vazquez Perez

Apologies if I missed anyone!

Global changes
--------------

clone.2
getdents.2
gettid.2
ioprio_set.2
llseek.2
mmap2.2
modify_ldt.2
mq_getsetattr.2
pivot_root.2
quotactl.2
readdir.2
sysctl.2
syslog.2
tkill.2
    mtk, after a note by Mike Frysinger
        Updated to reflect the fact that the _syscallN() macros
        have gone away,

Several pages
    mtk
        Change reference to path_resolution.2 to path_resolution.7.

Typographical or grammatical errors have been corrected in several
places.

Moved pages
-----------

path_resolution.2 has been moved to section 7, thus path_resolution.7
    mtk
        Reason: this is an overview page, not one describing as
        a specific system call.

Changes to individual pages
---------------------------

MAINTAINING
    mtk, after a note from Xose Vazquez Perez
        Added pointer to Red Hat man-pages bugzilla.
    mtk
        Added a release philosophy note on separating out big
        formatting changes into their own release that contains minimal
        content changes.

accept.2
    mtk
        Add new EXAMPLE section with pointer to example in bind.2.

arch_prctl.2
    mtk
        Added RETURN VALUE section.

bind.2
    mtk
        Expand example program, and move it to new EXAMPLE section.
        Added text pointing to example in getaddrinfo.3.

cacheflush.2
    mtk
        Convert NOTES section to CONFORMING TO and note that
        this call is Linux-specific.
        Other minor rewordings.

connect.2
    mtk
        Added new EXAMPLE section pointing to example in getaddrinfo.3.

create_module.2
    mtk
        Add ENOSYS error.

fcntl.2
flock.2
    mtk
        Small rewrite of SEE ALSO text pointing to Documentation/* in
        kernel source.

get_kernel_syms.2
    mtk
        Added ERRORS heading
        Add ENOSYS error.

getdtablesize.2
    mtk
        Added an ERRORS section.

getsid.2
    mtk
        Added a RETURN VALUE section.

getpid.2
    mtk
        Added an ERRORS section (stating that the calls are
        always successful).

ioctl_list.2
    mtk
        Add SEE ALSO reference to ioctl.2.

listen.2
    mtk
        Add new EXAMPLE section with pointer to example in bind.2.

query_module.2
    Martin (Joey) Schulze
        Add ENOSYS error.

recv.2
    mtk
        Added new EXAMPLE section pointing to example in getaddrinfo.3.

sched_get_priority_max.2
sched_rr_get_interval.2
sched_setscheduler.2
sched_yield.2
    mtk
        Modified .TH line

send.2
    mtk
        Added new EXAMPLE section pointing to example in getaddrinfo.3.

set_tid_address.2
    mtk
        Added an ERRORS section (stating that the call is
        always successful).

signal.2
    mtk, after a note from Alexander Taboriskiy
        Strengthen warning against the use of signal().
        Added siginterrupt(3) to SEE ALSO list.
    mtk
        Rewrote various parts; added an ERRORS section.

socket.2
    mtk
        Added new EXAMPLE section pointing to example in getaddrinfo.3.

stat.2
    mtk
        Added EXAMPLE program.

syscall.2
    mtk
        Converted to -man format; some rewrites; added an EXAMPLE.

sysctl.2
    mtk
        Improved the example program.

getnameinfo.3
    mtk
        Add text pointing to example in getaddrinfo.3.

getaddrinfo.3
    mtk
        Add example programs.
        Add getnameinfo() to SEE ALSO list.

memmove.3
    mtk / Serge van den Boom
        Clarify discussion of what happens if 'src' and 'dest' overlap.

regex.3
    Justin Pryzby
        Add grep(1) to SEE ALSO list.

sigpause.3
    mtk after a note from Ulrich Drepper
        Clarify discussion of feature test macros that are needed to
        expose System V and BSD versions of this function in glibc.

undocumented.3
    mtk
        Removed some functions that have been documented.

wprintf.2
    Martin (Joey) Schulze
        Remove wscanf.3 from SEE ALSO list, since that page does not exist.

utmp.5
    Joey Hess
        Removed outdated note on xdm.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=418009
    Martin (Joey) Schulze
        Removed outdated note about Debian and libc5.

bootparam.7
    Martin (Joey) Schulze
        Fix order of commands listed under 'init='.

hier.7
    Joey Hess
        Add /media, remove /dos.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=418234

inotify.7
    mtk
        Added text describing what happens when the buffer given to
        read(2) is too small to return information about the next event,
        and noting the behavior change in 2.6.21.

man-pages.7
    mtk
        Added text to note that ERRORS list should be in alphabetical order.

mdoc.7
mdoc.samples.7
    mtk
        Added SEE ALSO reference to groff_mdoc(7).

unix.7
    mtk
        Added  EXAMPLE section with pointer to bind.2 EXAMPLE.

ld.so.8
    mtk
        Simplify text describing --inhibit-rpath.
    mtk, after a note by John Reiser
        Describe use of $ORIGIN in rpath.
top
==================== Changes in man-pages-2.56 ====================

Released: 2007-06-11

Global changes
--------------

Many pages
    mtk
        Removed version numbers in .TH lines.
        Reason: these were only arbitrarily updated, and so impart no
        useful information.  Version information goes into a
        VERSIONS section nowadays, and the date in the .TH line should
        be updated to reflect the date of the last (significant)
        change to the page.

Typographical or grammatical errors have been corrected in several
places.
top
==================== Changes in man-pages-2.57 ====================

Released: 2007-06-17

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Samuel Thibault

Apologies if I missed anyone!

Global changes
--------------

Many pages
    mtk
        Fix section numbers in page cross references.

Changes to individual pages
---------------------------

access.2
    mtk
        Minor wording fixes.
        Small clarification of description of 'mode'.

bind.2
    mtk
        Small reworking of EXAMPLE program.

exit_group.2
    mtk
        Minor wording fixes.

exit.3
    mtk
        Added more detail on exit handlers.
        Minor wording fixes.

ioctl.2
    mtk
        Remove SEE ALSO reference to nonexistent mt.4.

modify_ldt.2
    Samuel Thibault / mtk
        In Linux 2.6, the 'modify_ldt_ldt_s' structure was renamed
        'user_desc'.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=378668
    mtk
        Include definition of 'user_desc' structure.
        Minor rewordings.

mprotect.2
    mtk
        Small reworking of EXAMPLE program.

sigaction.2
    mtk
        Removed reference to nonexistent sigsend(2).

a64l.3
    mtk
        Remove SEE ALSO reference to nonexistent itoa.3.

dysize.3
    mtk
        Removed SEE ALSO reference to nonexistent time.3.

encrypt.3
    mtk
        Removed SEE ALSO reference to nonexistent fcrypt.3.

fmemopen.3
    mtk
        Small reworking of EXAMPLE program.

fpurge.3
    mtk
        Remove SEE ALSO reference to nonexistent fclean.3.

getutent.3
    mtk
        s/ttyname(0)/ttyname(STDIN_FILENO)/ in program example.

vcs.4
    mtk
        s/exit(1)/exit(EXIT_FAILURE)/

environ.7
    mtk
        Correct some section numbers in page cross references.

man-pages.7
    mtk
        Modify requirements for example programs a little.

uri.7
    mtk
        Wrapped long source lines.
top
==================== Changes in man-pages-2.58 ====================

Released: 2007-06-24

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Marc Boyer
Mike Frysinger

Apologies if I missed anyone!

Global changes
--------------

Various pages, as detailed below
    mtk
        Added or updated VERSIONS sections.

killpg.2
setuid.2
faccessat.2
fork.2
setfsuid.2
kill.2
getsid.2
wait.2
execve.2
getpid.2
setgid.2
seteuid.2
setresuid.2
setfsgid.2
access.2
initgroups.3
euidaccess.3
tcgetpgrp.3
path_resolution.7
capabilities.7
unix.7
    mtk
        Add SEE ALSO link to new credentials.7.

New pages
---------

credentials.7
    mtk
        An overview of Linux process identifiers (PIDs, PPIDs,
        PGIDS, SIDs, UIDs, GIDs).

Changes to individual pages
---------------------------

bind.2
    mtk
        Added some comments to example program.

getxattr.2
    mtk
        VERSIONS: In kernel since 2.4; glibc support since 2.3.

listen.2
    mtk
        Updated discussion of somaxconn limit.

listxattr.2
    mtk
        VERSIONS: In kernel since 2.4; glibc support since 2.3.

posix_fadvise.2
    mtk
        VERSIONS: Glibc support has been provided since version 2.2.

readahead.2
    mtk
        Added VERSIONS section.

remap_file_pages.2
    mtk
        Updated VERSIONS section with text on glibc support.

removexattr.2
    mtk
        VERSIONS: In kernel since 2.4; glibc support since 2.3.

semop.2
    mtk
        Added VERSIONS section with info on semtimedop().

setxattr.2
    mtk
        VERSIONS: In kernel since 2.4; glibc support since 2.3.

dl_iterate_phdr.3
    mtk
        VERSIONS: Supported since glibc 2.2.4.

getloadavg.3
    mtk
        Added VERSIONS section.

posix_openpt.3
    mtk
        VERSIONS: Supported since glibc 2.2.1.

printf.3
    mtk after a suggestion by Mike Frysinger
        Add text to the introductory part of DESCRIPTION, about the
        'size' argument of snprintf() and vsnprintf().

shm_open.3
    mtk
        Added VERSIONS section; rewrote info about linking with -lrt.

strcat.3
    Marc Boyer
        Improve the discussion of strncat().

strcpy.3
    Marc Boyer
        Improve the discussion of strncpy().

proc.5
    mtk
        Added discussion of /proc/sys/net/core/somaxconn.
top
==================== Changes in man-pages-2.59 ====================

Released: 2007-06-25

Global changes
--------------

Manual pages are now standardized on American spelling.  See
http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences
for more information on the differences.  Formerly, different pages (and
sometimes even a single page!) employed American and British spelling
conventions; best to standardize on one spelling, and American English
is the standard in Computer Science.

Changes to individual pages
---------------------------

man-pages.7
    mtk
        Note that man-pages has now standardized on American spelling
        conventions.

execve.2
getxattr.2
listxattr.2
removexattr.2
setxattr.2
signal.2
syscall.2
aio_cancel.3
bindresvport.3
stdarg.3
charmap.5
bootparam.7
ipv6.7
man.7
path_resolution.7
uri.7
nscd.8
    mtk
        Corrected minor spelling/wording mistakes (i.e., changes
        independent of fixes for American spelling).
top
==================== Changes in man-pages-2.60 ====================

Released: 2007-06-25

Global changes
--------------

Various pages
    mtk
        Wrapped lines in some files.

Various pages
    mtk
        Change "e.g. " to "e.g., ", or in some cases, "for example, ".

Various pages
    mtk
        Change "i.e. " to i.e., ", or in some cases, "that is, ".

Various pages
    mtk
        Removed AUTHORS section.

Typographical or grammatical errors have been corrected in several
places.

Changes to individual pages
---------------------------

vfork.2
    mtk
        s/w.r.t/with respect to/

man-pages.7
    mtk
        Strengthened warning against use of AUTHORS section.
top
==================== Changes in man-pages-2.61 ====================

Released: 2007-07-01

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Benno Schulenberg
Florian Ernst
Ivana Varekova
Jeff Schroeder
Joey (Martin) Schulze
Justin Pryzby
Loïc Minier
Michael Gehring
Serge van den Boom
Stefan Puiu
Stepan Kasal

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        substitute `\\0' by '\\0'.

Various pages
    mtk
        s/`/'/ when the thing being quoted is a character.

accept.2
bind.2
connect.2
getsockopt.2
listen.2
socket.2
socketpair.2
    mtk after a note by Martin (Joey) Schulze
        Add NOTES paragraph noting that <sys/types.h> isn't required by
        POSIX.1-2001 or Linux, but was required on some implementations.

accept.2
getsockname.2
recv.2
vm86.2
send.2
getgrouplist.3
memmem.3
nsswitch.conf.5
putenv.3
wprintf.3
    mtk
        Replace form `...' with \fI...\fP where the enclosed string
        is a pathname, type name, or argument name.

A few files
    mtk
        s/process' /process's/

gets.3
qsort.3
getaddrinfo.3
rpc.3
ungetwc.3
wcsnrtombs.3
capabilities.7
    mtk
        Add section number to page cross references.

time.1
bind.2
pivot_root.2
sysctl.2
    mtk
        Reordered .SH sections.

full.4
mouse.4
random.4
sd.4
    mtk
        Made CONFIG/CONFIGURING heading ==> CONFIGURATION

time.1
console_codes.4
random.4
sk98lin.4
charmap.5
ftpusers.5
bootparam.7
charsets.7
glob.7
mq_overview.7
unicode.7
uri.7
utf-8.7
    mtk
        Reformatted headings

New pages
---------

backtrace.3
    mtk, with input from Justin Pryzby and Stefan Puiu
        Documents backtrace(), backtrace_symbols(), and
        backtrace_symbols_fd().

New links
---------

backtrace_symbols.3
backtrace_symbols_fd.3
    mtk
        Links to backtrace.3.

__clone.2
    Stepan Kasal
        Link to clone.2.

Changes to individual pages
---------------------------

Makefile
    Serge van den Boom
        Fix setting of 'prefix' macro.

eval.1p
    Benno Schulenberg
        Fix bad text (concatenated line).

chdir.2
    mtk
        Fixed description of EACCES error.
        Added sentence defining "current working directory".
        Other minor wording changes.

cfree.3
    mtk
        Added SEE ALSO section.

clone.2
    mtk
        s/clone2/__clone2/.

fdatasync.2
    mtk
        Minor wording changes.

fork.2
    Alain Portal
        Fix small wording error.

gethostid.2
    Stefan Puiu / mtk
        Add NOTES on what happens if gethostid() can't open /etc/hostid.

idle.2
    mtk
        Made NOTES text into a VERSIONS section, since that's what it
        really describes.

ioperm.2
    mtk
        Minor wording changes.

intro.2
    mtk
        Rewrite to reflect the fact that the _syscallN
        macros are no longer available.

io_cancel.2
    mtk
        Add "Link with -laio" to SYNOPSIS.

io_destroy.2
    mtk
        Add "Link with -laio" to SYNOPSIS.

io_getevents.2
    mtk
        Add "Link with -laio" to SYNOPSIS.

io_setup.2
    mtk
        Add "Link with -laio" to SYNOPSIS.

io_submit.2
    Ivana Varekova
        Fix include in SYNOPSIS.
    mtk
        Add "Link with -laio" to SYNOPSIS.

ipc.2
    mtk
        Add semtimedop() to SEE ALSO.
        Note that some architectures don't have ipc(2); instead
        real system calls are provided for shmctl(), semctl(), etc.

killpg.2
    mtk
        Minor wording changes.

listen.2
    mtk
        Added <sys/types.h> to SYNOPSIS.

sched_setscheduler.2
    mtk
        Add NOTES para about permissions required to call
        sched_setscheduler() on other systems.

select.2
    mtk
        Noted that 'timeout' can also be changed if select() is
        interrupted by a signal.

setup.2
    mtk
        Remove reference to _syscall0() macro.

shmop.2
    mtk
        Changed text for EINVAL error.

socketcall.2
    mtk
        Add recvmsg() and sendmsg() to SEE ALSO.
        Note that some architectures don't have socketcall(2); instead
        real system calls are provided for socket(), bind(), etc.

swapon.2
    Ivana Varekova  / mtk
        Update text for EPERM error describing the maximum number of
        swap files.  (From downstream Fedora patch.)

write.2
    mtk
        Added details about seekable files and file offset.
        Noted that write() may write less than 'count' bytes, and
        gave some examples of why this might occur.
        Noted what happens if write() is interrupted by a signal.
        Minor wording changes.

__setfpucw.3
    mtk
        Added a CONFORMING TO section; other minor edits.

confstr.3
    mtk
        Minor rewrites in code example.

ctime.3
    Justin Pryzby
        Make SEE ALSO refer to timegm.3

daemon.3
    mtk
        Small wording change.

dl_iterate_phdr.3
    Michael Gehring
        Comment was missing closing "*/".

dlopen.3
    mtk
        Formatting changes, and minor rewordings.
    mtk, after a note by Serge van den Boom
        Add a comment explaining the need for the rather
        strange cast of the return value of dlsym().

fpclassify.3
    mtk
        Add "isinf" to NAME section.

getgrouplist.3
    mtk
        Minor rewording.

getline.3
    mtk
        Minor rewording, and note that '*n* is ignored
        if '*lineptr' is NULL.

malloc.3
    Ivana Varekova  / mtk
        Update description of MALLOC_CHECK_ to include description
        for value 3.  (From downstream Fedora patch.)

netlink.3
    mtk
        Added a CONFORMING TO section; other minor edits.

openpty.3
    mtk
        Minor changes to SYNOPSIS.

program_invocation_name.3
    mtk
        Shortened page title to INVOCATION_NAME.

rtnetlink.3
    mtk
        Added a CONFORMING TO section; other minor edits.

scanf.3
    Florian Ernst
        Fix duplicated word "the".
        (Really fix http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=412467 !)

select_tut.3
    mtk
        Small wording change.

setnetgrent.3
    mtk
        Added a CONFORMING TO section.

sigpause.3
    mtk
        Added a CONFORMING TO section.

strftime.3
    Just Pryzby
        Small wording fix.
    mtk
        Note use of "gcc -Wno-format-y2k" to avoid the "`%c' yields only
        last 2 digits of year in some locales" warning.

strstr.3
    mtk
        Add "strcasestr" to NAME section.

syslog.3
    mtk
        Small wording change.

termios.3
    mtk
        Reformat SYNOPSIS.
        Added a CONFORMING TO section.

timegm.3
    mtk
        Small wording changes.

ulimit.3
    mtk
        Remove erroneous text saying that glibc does not provide
        <ulimit.h>; it does.

initrd.4
    mtk
        Various reformattings.

core.5
    mtk
        Added a sentence noting why core dumps named "core.PID" were useful
        with LinuxThreads.

bootparam.7
    mtk
        Fix capitalization in .SS headings.

epoll.7
    mtk
        Language clean ups.

feature_test_macros.7
    mtk
        Added SEE ALSO section.

mq_overview.7
    mtk
        Reformatted headings; minor rewrites.

sem_overview.7
    mtk
        Reformatted headings; minor rewrites.

socket.7
    Loïc Minier
        Document argument type for SO_REUSEADDR.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=255881

uri.7
    mtk
        Wrap long line in SYNOPSIS.

ldconfig.8
    mtk
        Added SEE ALSO section.
top
==================== Changes in man-pages-2.62 ====================

Released: 2007-07-09

This release consists solely of formatting fixes.  There are no changes
to content.

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Stepan Kasal

Apologies if I missed anyone!

Global changes
--------------

Many many pages
    mtk
        Many many formatting fixes.

man[013]p/*
    Stepan Kasal
        Add section number to .TH line for POSIX pages in man[013]p.
top
==================== Changes in man-pages-2.63 ====================

Released: 2007-07-16

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Arnd Bergmann
Eduardo M. Fleury
Ivana Varekova
Justin Pryzby
Marc Boyer
Martin (Joey) Schulze
Martin Röhricht
Patrick Mansfield
Pierre Habouzit
Stepan Kasal

Apologies if I missed anyone!

Global changes
--------------

gettimeofday.2
madvise.2
msgctl.2
select.2
semctl.2
shmctl.2
syslog.2
stat.2
a64l.3
printf.3
termios.3
xdr.3
sd.4
    mtk
        Minor wording changes.

obsolete.2
syscall.2
unimplemented.2
    mtk
        Added SEE ALSO reference to syscalls.2.

New pages
---------

sgetmask.2
    mtk
        A real man page for sgetmask(2) and ssetmask(2).
        (This page replaces a previous link of the same name, which
        linked to signal.2.)

spu_create.2
    Arnd Bergmann with additional work by Eduardo M. Fleury and mtk
        Document the PowerPC SPU spu_create() system call.
        (Originally taken from the kernel source file
        Documentation/filesystems/spufs.txt.)

spu_run.2
    Arnd Bergmann with additional work by Eduardo M. Fleury and mtk
        Document the PowerPC SPU spu_run() system call.
        (Originally taken from the kernel source file
        Documentation/filesystems/spufs.txt.)

spufs.7
    Arnd Bergmann with additional work by Eduardo M. Fleury and mtk
        Document the PowerPC SPU file system.
        (Originally taken from the kernel source file
        Documentation/filesystems/spufs.txt.)

Removed Pages
-------------

__clone.2
    mtk
        This file was created by accident in 2.61, as a copy of clone.2.
        (it should have been a link to clone.2.)

obsolete.2
    mtk
        Details on this page are covered in syscalls.2 and in
        respective syscall man pages (stat.2, uname.2).

undocumented.2
    mtk
        This page is very out of date, and in any case difficult
        to maintain.  Information about undocumented system calls
        is maintained in the HOWTOHELP file, and probably in other
        places soon.

killpg.3
    mtk
        This rather incomplete page seems unnecessary since there
        is a killpg.2.

New links
---------

chown32.2
fchown32.2
getegid32.2
geteuid32.2
getgid32.2
getgroups32.2
getresgid32.2
getresuid32.2
getuid32.2
lchown32.2
setfsgid32.2
setfsuid32.2
setgid32.2
setgroups32.2
setregid32.2
setresgid32.2
setresuid32.2
setreuid32.2
setuid32.2
    mtk
        Added as link to corresponding page without "32".

fcntl64.2
fstat64.2
fstatat64.2
fstatfs64.2
ftruncate64.2
getdents64.2
lstat64.2
pread64.2
pwrite64.2
sendfile64.2
stat64.2
statfs64.2
truncate64.2
    mtk
        Added as link to corresponding page without "64".

__clone2.2
clone2.2
    mtk
        Links to clone.2.

ugetrlimit.2
    mtk
        Link to getrlimit.2.

mq_notify.2
mq_open.2
mq_timedreceive.2
mq_timedsend.2
mq_unlink.2
    mtk
        Added as links to corresponding section 3 pages.

fadvise64.2
fadvise64_64.2
    mtk
        Links to posix_fadvise.2.

rt_sigaction.2
rt_sigpending.2
rt_sigprocmask.2
rt_sigtimedwait.2
    mtk
        Added as link to corresponding page without "rt_" prefix.

rt_sigqueueinfo.2
    mtk
        Link to sigqueue.2.

madvise1.2
tuxcall.2
vserver.2
    mtk / Ivana Varekova
        Link to unimplemented.2.

Changes to individual pages
---------------------------

access.2
    mtk
        Fairly substantial rewrites of various parts,
        and a few additions.

chmod.2
    mtk
        Update SYNOPSIS to reflect the fact that fchmod(2) needs
        either "#define _XOPEN_SOURCE 500" or "#define _BSD_SOURCE".

chown.2
    mtk
        Update SYNOPSIS to reflect the fact that fchmod(2) and lchown(2)
        need either "#define _XOPEN_SOURCE 500" or "#define _BSD_SOURCE".
        Added an example program.

killpg.2
    mtk
        Note that killpg() is actually a library function on Linux.

mmap.2
    mtk
        Added note that glibc mmap() wrapper nowadays invokes mmap2().

mmap2.2
    Ivana Varekova / mtk
        On most platforms the unit for 'offset' is 4096 bytes, not
        the system page size.
    mtk
        Rewrote NOTES to note that glibc mmap() wrapper nowadays
        invokes this system call.
    mtk
        Added an EXAMPLE program.

oldfstat.2
oldlstat.2
oldstat.2
    mtk
        Changed link to point to stat.2 (instead of obsolete.2).

olduname.2
oldolduname.2
    mtk
        Changed link to point to uname.2 (instead of obsolete.2).

sched_setaffinity.2
    Martin Röhricht
        Added _GNU_SOURCE to SYNOPSIS.

semctl.2
    mtk
        Remove reference discussion of ipc(2), since none of the
        other System V IPC pages mention ipc(2).

semop.2
    mtk
        Add an example code segment.

shmctl.2
    mtk
        Add svipc(7) to SEE ALSO list.

sigaction.2
    mtk
        Reformatted tables as lists; other minor reformattings and
        wording changes.

sigqueue.2
    mtk
        Added info on rt_sigqueueinfo(2).

sigwaitinfo.2
    mtk
        Noted that sigwaitinfo() is a library function implemented on
        top of sigtimedwait().

ssetmask.2
    mtk
        Make this link point to new sgetmask.2 instead of signal.2.

stat.2
    mtk
        Add notes on the different system call interfaces that
        have appeared over time.

syscalls.2
    mtk
        A fairly substantial rewrite of this page,
        bringing it up to date with the current
        kernel version, and listing all system calls
        in tabular form.

uname.2
    mtk
        Add notes on the different system call interfaces that
        have appeared over time.

unimplemented.2
    mtk
        Add vserver, madvise1 to NAME line.
        Removed SEE ALSO reference to obsolete.2.
    Ivana Varekova
        Add tuxcall to NAME line.

mktemp.3
    Patrick Mansfield
        Fix description of return value.

strcat.3
    Marc Boyer
        Minor fix to example program.

undocumented.3
    mtk
        Add section numbers to function names; remove some functions
        since they are documented.

proc.5
    mtk
        Update/correct text on /proc/malloc.
    mtk, after a note by Pierre Habouzit, and a few comments by Justin Pryzby
        Update description of /proc/PID/stat to match 2.6.21.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=417933

inotify.7
    mtk
        IN_DONT_FOLLOW and IN_ONLYDIR are only available from 2.6.15.

signal.7
    Stepan Kasal / mtk
        Note SIGRTMIN value depends on glibc.
    mtk
        Various rewrites and additions to the text in real-time signals.
        Add SEE ALSO reference to sgetmask.2.

svipc.7
    mtk
        Add ipc(2) to SEE ALSO.
top
==================== Changes in man-pages-2.64 ====================

Released: 2007-07-27

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Aleksandr Koltsoff
Andries Brouwer
Justin Pryzby

Apologies if I missed anyone!

Global changes
--------------

INFINITY.3
_exit.2
a64l.3
abs.3
acct.2
acosh.3
addseverity.3
adjtime.3
asinh.3
atanh.3
atoi.3
brk.2
cbrt.3
cfree.3
chdir.2
chmod.2
chown.2
clearenv.3
clock_getres.3
clone.2
confstr.3
copysign.3
ctermid.3
ctime.3
daemon.3
dirfd.3
div.3
drand48.3
drand48_r.3
dysize.3
ecvt.3
ecvt_r.3
erf.3
euidaccess.3
exp2.3
expm1.3
fdatasync.2
ferror.3
fexecve.3
fgetgrent.3
fgetpwent.3
finite.3
flockfile.3
fopen.3
fpclassify.3
fsync.2
futimes.3
fwide.3
gamma.3
gcvt.3
getcwd.3
getdate.3
getdirentries.3
getdomainname.2
getdtablesize.2
getgrent.3
getgrent_r.3
getgrouplist.3
getgroups.2
gethostbyname.3
gethostid.2
gethostname.2
getlogin.3
getmntent.3
getpagesize.2
getpw.3
getpwent.3
getpwent_r.3
getpwnam.3
getsid.2
getspnam.3
gettimeofday.2
getumask.3
getusershell.3
gsignal.3
hypot.3
inet.3
initgroups.3
insque.3
isalpha.3
iswblank.3
j0.3
kill.2
killpg.2
lgamma.3
lockf.3
log1p.3
log2.3
logb.3
longjmp.3
lrint.3
lround.3
madvise.2
mbsnrtowcs.3
memfrob.3
mincore.2
mkdtemp.3
mknod.2
mkstemp.3
mktemp.3
nan.3
nanosleep.2
nextafter.3
nice.2
on_exit.3
perror.3
posix_memalign.3
posix_openpt.3
printf.3
profil.3
psignal.3
putenv.3
putpwent.3
qecvt.3
rand.3
random.3
rcmd.3
readahead.2
readlink.2
realpath.3
remainder.3
remquo.3
rexec.3
rint.3
round.3
rpmatch.3
scalb.3
scandir.3
scanf.3
seekdir.3
select.2
sem_wait.3
semop.2
setbuf.3
setenv.3
seteuid.2
setjmp.3
setnetgrent.3
setpgid.2
setresuid.2
setreuid.2
sigaltstack.2
siginterrupt.3
significand.3
sigqueue.2
sigvec.3
sigwaitinfo.2
sockatmark.3
stat.2
stime.2
strdup.3
strerror.3
strsep.3
strtod.3
strtok.3
strtol.3
strtoul.3
symlink.2
sync.2
syscall.2
syslog.3
tcgetsid.3
telldir.3
tempnam.3
termios.3
tgamma.3
timegm.3
toascii.3
trunc.3
truncate.2
ttyslot.3
tzset.3
ualarm.3
unlocked_stdio.3
unshare.2
usleep.3
vfork.2
vhangup.2
wait.2
wait4.2
wcscasecmp.3
wcsncasecmp.3
wcsnlen.3
wcsnrtombs.3
wcswidth.3
wordexp.3
wprintf.3
    mtk
        Added/updated feature test macro requirements for
        glibc; see feature_test_macros.7 for details.

Changes to individual pages
---------------------------

mq_notify.2
mq_open.2
mq_timedreceive.2
mq_timedsend.2
mq_unlink.2
    mtk
        Fix broken link

setpgid.2
    mtk
        Fairly substantial changes and corrections, including adding
        coverage of all of the interfaces that get/set PGIDs.

syscalls.2
    mtk / aeb
        Various rewordings; clear up some imprecisions.

lgamma.3
    mtk
        Added 'signgam' to SYNOPSIS and NAME line.

strerror.3
    mtk
        Note that the XPG version is provided since glibc 2.3.4.
        The page formerly said that the GNU-specific version
        is provided by default.  That certainly isn't true
        nowadays, since _POSIX_C_SOURCE is set to 200112L by
        default, so that the XSI-compliant version is supplied
        by default.

man-pages.7
    mtk
        Added note pointing to feature_test_macros.7 for a description
        of how feature test macro requirements should be specified in
        manual pages.  Various other minor fixes and changes.

feature_test_macros.7
    mtk
        Added note about how feature test macros are specified
        in manual pages.
        Many other corrections, improvements, additions, and
        details about differences across glibc versions.
top
==================== Changes in man-pages-2.65 ====================

Released: 2007-09-17

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Aleksandr Koltsoff
Andi Kleen
Anton Blanchard
Ari Entlich
Carsten Emde
François Diakhate
Geoff Clare
Jon Burgess
Julien Cristau
Lee Schermerhorn
Mats Wichmann
Maxime Bizon
Maxime Vaudequin
Michael Prokop
Mike Frysinger
Nicolas François
Nicolas George
Paul Brook
Reuben Thomas
Sam Varshavchik
Samuel Thibault
Thomas Huriaux
Tolga Dalman
Ulrich Drepper
Vincent Lefevre

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

Various pages
    mtk
        Use 'glibc' consistently to refer to GNU C library.

Various pages
    mtk
        Order errors under ERRORS alphabetically.

Various pages
    Nicolas François
        Spelling and formatting fixes, as per
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=439560

intro.2
select.2
fmtmsg.3
getgrent_r.3
envz_add.3
rtime.3
strptime.3
wordexp.3
    Maxime Vaudequin
        Add "#include <stdlib.h>" (to declare exit(3)) to example program.

New pages
---------

timeradd.3
    mtk
        Description of timeradd(), timersub(), timerclear(),
        timerisset(), timercmp() macros for operating on
        struct timeval.

Removed pages
-------------

fdatasync.2
    mtk
        Somehow, over time, material on fdatasync(2) crept into
        fsync.2, and fdatasync also got added to the NAME section
        of fsync.2.  All of the material in fdatasync.2 that was
        not already in fsync.2 has now been moved there, and
        the former page has been removed.
        In place of the content there, is now a link to fsync.2.

New links
---------

clock_getres.2
clock_gettime.2
clock_settime.2
    mtk
        Link to man3/clock_getres.3.

fdatasync.2
    mtk
        Link to fsync.2.

fdopendir.3
    mtk
        Link to opendir.3.

gethostbyaddr_r.3
    Mats Wichmann
        Link to gethostbyaddr.3.

timerclear.3
timercmp.3
timerisset.3
timersub.3
    mtk
        Links to new timeradd.3.

Changes to individual pages
---------------------------

Makefile
    Mike Frysinger
        Make the install target of man-pages respect the standard
        "DESTDIR" variable as well as check the exit status of the
        install command so errors aren't ignored.

get_mempolicy.2
    Lee Schermerhorn
        changed the "policy" parameter to "mode" through out the
        descriptions in an attempt to promote the concept that the memory
        policy is a tuple consisting of a mode and optional set of nodes.

        added requirement to link '-lnuma' to synopsis

        rewrite portions of description for clarification.

        added all errors currently returned by sys call.

        removed cautionary note that use of MPOL_F_NODE|MPOL_F_ADDR
        is not supported.  This is no longer true.

        added mmap(2) to SEE ALSO list.

getitimer.2
    mtk
        Since kernel 2.6.22, Linux setitimer() now conforms to POSIX.1,
        giving an EINVAL error for a non-canonical tv_usec value.

gettimeofday.2
    mtk
        Replace discussion of timer* macros with a pointer
        to new page timeradd.3.

ioctl_list.2
    Nicolas George
        Fixed argument type for BLKGETSIZE.

mbind.2
    Lee Schermerhorn

        changed the "policy" parameter to "mode" throughout the
        descriptions in an attempt to promote the concept that the memory
        policy is a tuple consisting of a mode and optional set of nodes.

        rewrite portions of description for clarification.

            clarify interaction of policy with mmap()'d files and shared
            memory regions, including SHM_HUGE regions.

            defined how "empty set of nodes" specified and what this
            means for MPOL_PREFERRED.

            mention what happens if local/target node contains no
            free memory.

            clarify semantics of multiple nodes to BIND policy.
            Note:  subject to change.  We'll fix the man pages when/if
                   this happens.

        added all errors currently returned by sys call.

        added mmap(2), shmget(2), shmat(2) to SEE ALSO list.

mmap.2
mprotect.2
    François Diakhate
        Add text noting that PROT_WRITE may (and on x86 does)
        imply PROT_READ.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=441387

nfsservctl.2
    Aleksandr Koltsoff
        Fix prototype.

oldfstat.2
oldlstat.2
oldstat.2
    mtk
        Fix broken link

prctl.2
    mtk
        Update arches/kernel versions for PR_SET_UNALAIGN / PR_GET_UNALIGN.

readahead.2
    mtk
        Removed SEE ALSO reference to nonexistent fadvise.2.

reboot.2
    mtk
        Place SYNOPSIS comments inside C comments (/* ... */).

sched_setaffinity.2
    Samuel Thibault
        Note what thread is affected if 'pid' is specified
        as 0, or as the value returned by getpid().

sched_setscheduler.2
    Carsten Emde
        Add text on real-time features of mainline Linux kernel.

select_tut.2
    mtk
        sync SYNOPSIS with select.2

set_mempolicy.2
    Lee Schermerhorn

        changed the "policy" parameter to "mode" throughout the
        descriptions in an attempt to promote the concept that the memory
        policy is a tuple consisting of a mode and optional set of nodes.

        added requirement to link '-lnuma' to synopsis

        rewrite portions of description for clarification.

            clarify interaction of policy with mmap()'d files.

            defined how "empty set of nodes" specified and what this
            means for MPOL_PREFERRED.

            mention what happens if local/target node contains no
            free memory.

            clarify semantics of multiple nodes to BIND policy.
            Note:  subject to change.  We'll fix the man pages when/if
                   this happens.

        added all errors currently returned by sys call.

        added mmap(2) to SEE ALSO list.

sigaction.2
    mtk
        s/si_sign/si_errno/ in statement about which field is unused.
    Ari Entlich
        s/SIGILL/SIGCHLD/ for paragraph describing SIGCHLD.

stat.2
    mtk
        Improve text describing underlying system calls.

swapon.2
    Michael Prokop
        EINVAL also occurs if target path is on tmpfs or similar.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435885

sync.2
    mtk
        Incorporated material from now deleted fdatasync.2.

syscall.2
    mtk
        Small fix in example program.

uname.2
    mtk
        Improve text describing underlying system calls.

utime.2
    Vincent Lefevre / mtk
        Clarify utimes() behaviour when 'times' is NULL.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=431480
    mtk
        Other minor clarifications of description of utimes().

copysign.3
    Vincent Lefevre
        s/sign/sign bit/ to remove ambiguity in description.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435415

euidaccess.3
    mtk
        Changed NOTES to VERSIONS.

ffsl.3
    mtk
        Add ffsl and ffsll to NAME line.

fts.3
    mtk
        Removed statement that fts functions are expected to appear
        soon in POSIX; it's years old and has not yet come to pass.

ftw.3
    mtk / Geoff Clare
        Fixes/improvements for example program.

getdate.3
    mtk
        Add getdate_r to NAME section.

getaddrinfo.3
    mtk / Geoff Clare
        Fixes/improvements for example program.

gethostbyaddr.3
    Mats Wichmann
        Add documentation for gethostbyaddr_r().
        Plus a few other small fixes.

gethostbyname.3
    mtk
        Add gethostbyname2, gethostbyname2_r, gethostbyname_r,
        gethostent_r to NAME line.

getmntent.3
    mtk
        Fix misnamed function references.

getopt.3
    Jon Burgess
        Fix small error in example program.

getrpcent.3
    mtk
        Add setrpcent and endrpcent to NAME line.

gsignal.3
    Aleksandr Koltsoff
        Fix gsignal() prototype.

hsearch.3
    mtk
        Add hcreate_r, hdestroy_r, hsearch_r to NAME line.

inet.3
    Maxime Bizon
        Correct definition of "struct in_addr".

isatty.3
    mtk
        Minor wording fix.

isgreater.3
    mtk
        Add islessequal to NAME line.

lgamma.3
    Vincent Lefevre
        Fix CONFORMING TO section.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=417592

log1p.3
    mtk
        Add log1pf and log1pl to NAME line.

longjmp.3
    Paul Brook / mtk
        After a call to longjmp(), the values of modified, non-volatile
        variables in the function that called setjmp() are unspecified.

makecontext.3
    Aleksandr Koltsoff
        Fix makecontext() prototype.

malloc.3
    mtk / Tolga Dalman
        Explain what happens for malloc(0), or calloc() where one of the
        arguments is 0.
    mtk
        Added notes on malloc()'s use of sbrk() and mmap().
    mtk
        Add mmap(2), alloca(3) to SEE ALSO.

mq_close.3
mq_getattr.3
mq_notify.3
mq_open.3
mq_receive.3
mq_send.3
mq_unlink.3
    mtk
        Add "Link with -lrt." to SYNOPSIS.

opendir.3
    Ulrich Drepper; some edits and additional text by mtk
        Document fdopendir().

readdir.3
    mtk, after a note by Andi Kleen
        Document DT_* constants for d_type.
    Ulrich Drepper / mtk
        Rework discussion of non-standard structure fields.

sem_wait.3
    mtk
        Minor improvements to example program.

syslog.3
    mtk
        Add vsyslog to NAME section.

termios.3
    Nicolas François
        Fix XCASE feature test macro description.

wcsspn.3
    Aleksandr Koltsoff
        Add return type to prototype.

proc.5
    mtk
        Improve description of num_threads field under /proc/PID/stat.
    Maxime Vaudequin
        Fix path error (s%proc/sys%proc/sys/kernel%) in mentions of
        /proc/sys/ostype, /proc/sys/osrelease and proc/sys/version.
    Maxime Vaudequin
        I noticed things to correct and to clarify in subsection
        "/proc/filesystems" of proc.5:
        - clarify filesystems listing: not only FS compiled
          into the kernel, also FS kernel modules currently loaded
        - add a reference to fs(5)
        - add an explanation for FS marked with "nodev"
        - s/mount(1)/mount(8)/, also corrected in section "SEE ALSO"
        - clarify usage by mount: the current wording may lead to
          think /proc/filesystems is always used by mount when no FS
          is specified. So, usage of "may" which IMHO is more
          appropriate + additional explanations
          In mount(8) we can see:

               If no -t option is given, or if the auto type is
               specified, mount will try to guess the desired type.
               If mount was compiled with the blkid library, the
               guessing is done by this library. Otherwise, mount
               guesses itself by probing the superblock; if that
               does not turn up anything that looks familiar,
               mount will try to read the file /etc/filesystems,
               or, if that does not exist, /proc/filesystems.
               All of the filesystem types listed there will be
               tried, except for those that are labeled "nodev"
               (e.g., devpts, proc and nfs). If /etc/filesystems
               ends in a line with a single * only, mount will
               read /proc/filesystems afterwards.
    Samuel Thibault
        Since linux 2.6.11, /proc/stat has an eighth value for cpu
        lines: stolen time, which is the time spent in other operating
        systems when running in a virtualized environment.

arp.7
        Updated BUGS text referring to jiffies; refer to time.7 instead.

credentials.7
    mtk
        Add words to note that file system ID is Linux specific.

hier.7
    Maxime Vaudequin
        This is some corrections for hier.7:
        - missing period for /media and /mnt
        - /mnt description is not totally correct, it is true for some
          distributions but in others /mnt is used as a temporary FS
          mount point, as it is specified by FHS:
          http://www.pathname.com/fhs/pub/fhs-2.3.html#MNTMOUNTPOINTFORATEMPORARILYMOUNT
        - s/X-Windows/X-Window/ (3 occurrences)
        - section "SEE ALSO": s/mount(1)/mount(8)/

man-pages.7
man.7
mdoc.7
mdoc.samples.7
    mtk / Nicolas François
        Nowadays tmac.XXX are called XXX.tmac.

pthreads.7
    mtk
        Update text about modern threading implementations
        (NPTL vs LinuxThreads).

socket.7
    mtk, after a note by Andi Kleen
        Clarify that SO_SNDTIMEO and SO_RCVTIMEO only have effect for
        socket I/O calls; not for multiplexing system calls like
        select() and poll().

time.7
    mtk
        Add SEE ALSO reference to new timeradd.3.
top
==================== Changes in man-pages-2.66 ====================

Released: 2007-10-01

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Amit K. Arora
David Chinner
Fredrik Noring
Mats Wichmann
Maxime Vaudequin
Ollie Wild
Ulrich Drepper

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several
places.

New pages
---------

fallocate.2
    David Chinner, with some input from Amit Amora and mtk
        Describes the fallocate() system call, new in 2.6.23.

Changes to individual pages
---------------------------

close.2
    Fredrik Noring
        Add text cautioning about use of close() in
        multithreaded programs.

execve.2
    Ollie Wild / mtk
        Add text describing limit on total size of argv + envp,
        and changes that occurred with 2.6.23.
    mtk
        Add getopt(3) to SEE ALSO list.

open.2
    mtk, Acked by Ulrich Drepper
        Added description of O_CLOEXEC (new in 2.6.23) + other
        minor fixes for O_DIRECT.

recv.2
    mtk
        Added description of MSG_CMSG_CLOEXEC (new in 2.6.23).

sysctl.2
    mtk
        Strengthened the warning against using this system call
        and note that it may disappear in a future kernel version.

rpc.3
    Mats Wichmann
        Fix type definition for 'protocol' in prototypes of pmap_set()
        and pmap_getport().
top
==================== Changes in man-pages-2.67 ====================

Released: 2007-10-08

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
Andrew Josey
Maxime Vaudequin

Apologies if I missed anyone!

Global changes
--------------

*.1p
*.3p
    mtk, after a note by Andi Kleen and consultation with Andrew Josey.
        Add a PROLOG section:
            This manual page is part of the POSIX Programmer's Manual.
            The Linux implementation of this interface may differ
            (consult the corresponding Linux manual page for details
            of Linux behavior), or the interface may not be implemented
            on Linux.

*.0p
*.1p
*.3p
    mtk
        Some formatting fixes, mostly to get rid of unwanted
        spaces before "," in formatted output.

*
*/*
    mtk
        Change all occurrences of my email address in man-pages source
        to my new gmail address.

Many many pages
    Maxime Vaudequin
        I noticed useless use of macros with alternating formatting
        (".IR" instead ".I" which suffices, ".BR" instead ".B", etc.)
        because there is only one element.  For example in ldconfig.8:

            -.BR /sbin/ldconfig
            +.B /sbin/ldconfig

        This is not very important, it only makes the sources more tidy.
        To find these I used:

            egrep '^\.(B[RI]|R[IB]|I[RB]) ([^ ]+|\"[^\"]\+\")$'

        And if you want to make these changes, you can use:

            sed 's/^\(\.[BRI]\)[BRI]\( \([^ ]\+\|\"[^\"]\+\"\)\)$/\1\2/g'
top
==================== Changes in man-pages-2.68 ====================

Released: 2007-11-19

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

A. Costa
Andrew McDonald
Geoff Clare
Heikki Orsila
Hyokyong Kim
Ivana Varekova
Justin Pryzby
Maxime Vaudequin
Mike Frysinger
Nicolas François
Pádraig Brady
Sam Varshavchik
Timo Juhani Lindfors
Ulrich Drepper

Apologies if I missed anyone!

Global changes
--------------

faccessat.2
fchmodat.2
fchownat.2
fstatat.2
futimesat.2
linkat.2
mkdirat.2
mknodat.2
readlinkat.2
renameat.2
symlinkat.2
mkfifoat.3
    mtk, after http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=445436
        by Timo Juhani Lindfors
        Added <fcntl.h> to SYNOPSIS.

Typographical or grammatical errors have been corrected in several places.

New pages
---------

_syscall.2
    mtk
        Created as a new page, by taking the content specific to
        the _syscall() macros from intro(2).

Changes to individual pages
---------------------------

README
    mtk
        Brought up to date.

man-pages-*-Announce
    mtk
        Brought the info in here up to date.

intro.1
    mtk
        Added intro paragraph about section, plus a paragraph
        about exit status values.
        Move "user intro" text to NOTES.

get_mempolicy.2
    mtk
        Reorder ERRORS sections alphabetically

intro.2
    mtk
        Pretty much a complete rewrite, covering some additional topics.
        Moved _syscallN() material to new _syscall(2) page.

mbind.2
    mtk
        Reorder ERRORS sections alphabetically

mmap.2
    Maxime Vaudequin
        Fix syntax error in example program.

prctl.2
    mtk
        Linux 2.6.22 added support on Alpha for PR_SET_UNALIGN.

ptrace.2
    Nicolas François / mtk
        s/PTRACE_POKEUSR/PTRACE_POKEUSER/
        s/PTRACE_PEEKUSR/PTRACE_PEEKUSER/

read.2
    mtk / Geoff Clare
        Add text describing timerfd EINVAL error for read(2).

set_mempolicy.2
    mtk
        Reorder ERRORS sections alphabetically

syscall.2
    mtk
        Added _syscall(2) and intro(2) to SEE ALSO section.

syscalls.2
    mtk
        Added fallocate(2); removed timerfd(2).

sysinfo.2
    mtk
        Removed reference to example in intro(2).

dlopen.3
    mtk
        Added "Link with -ldl." to SYNOPSIS.

getaddrinfo.3
    Ulrich Drepper / mtk
        Remove references to getipnodebyname.3 and getipnodebyaddr.3.

gethostbyname.3
    mtk / Ulrich Drepper
        Remove SEE ALSO references to getipnodebyname.3 and
        getipnodebyaddr.3.

    Pádraig Brady / mtk / Ulrich Drepper
        Point out that the functions described on this page
        are made obsolete by getaddrinfo(3) and getnameinfo(3).

getipnodebyname.3
    mtk
        Clarify that glibc does not implement these functions.

glob.3
    Ulrich Drepper / mtk
        Fix description of GLOB_ONLYDIR.
    mtk
        Added description of GLOB_TILDE_NOMATCH.
        Expanded the description of various flags.
        Various wording fixes..

intro.3
    mtk
        Pretty much a complete rewrite, covering some additional topics.

posix_fallocate.3
    mtk
        Add SEE ALSO referring to fallocate.2.

rpc.3
    Sam Varshavchik
        Add some arg declarations to prototypes; fix typos.

setbuf.3
    Mike Frysinger
        Fix text in BUGS section.

sigset.3
    mtk
        The sigset() bugs were fixed in glibc 2.5.
        See http://sourceware.org/bugzilla/show_bug.cgi?id=1951

intro.4
    mtk
        Minor rewrites.

st.4
    Maxime Vaudequin
        Various small corrections, formattings and modifications.

elf.5
    Mike Frysinger
        Document:
        - new p_flag: PT_GNU_STACK
        - new sections: .gnu.version .gnu.version_d .gnu.version_r
          .note.GNU-stack
        - new structures: ElfN_Verdef ElfN_Verdaux ElfN_Verneed
          ElfN_Vernaux

intro.5
    mtk
        Minor rewrites.

proc.5
    Ivana Varekova / mtk
        Add text noting that since kernel 2.6.16, /proc/slabinfo is
        only available if CONFIG_SLAB is enabled.
    Maxime Vaudequin
        Update description of /proc/pci.
    Maxime Vaudequin
        Give italic formatting to file names in proc.5.
    mtk
        The display type of the /proc/PID/stat fields changed
        %lu to %u in Linux 2.6.22:
            flags
            rt_priority
            policy

slabinfo.5
    Ivana Varekova / mtk
        Add text noting that since kernel 2.6.16, /proc/slabinfo is
        only available if CONFIG_SLAB is enabled.

intro.6
    mtk
        Minor rewrites.

bootparam.7
    Maxime Vaudequin
        Update references to files in kernel "Documentation" directory.

intro.7
    mtk
        Minor rewrites.

ipv6.7
    Andrew McDonald
        Fix description of IPV6_ROUTER_ALERT option.

standards.7
    mtk
        Note online location of C99 standard.

intro.8
    mtk
        Some rewrites, plus new paragraph on exit status values.
top
==================== Changes in man-pages-2.69 ====================

Released: 2007-12-03

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Adam Borowski
Alain Portal
Andries E. Brouwer
J. Bruce Fields
David Härdeman
Jeremy Kerr
Luke Browning
Mats Wichmann
Maxime Vaudequin
Mike Frysinger
Reuben Thomas
Sam Varshavchik

Apologies if I missed anyone!

Global changes
--------------

*.[013]p
    mtk
        Many whitespace clean-ups in formatted output.

mprotect.2
bind.2
mq_notify.3
makecontext.3
fmemopen.3
    David Härdeman / mtk
        Rename error handling function in example program
        (s/die/handle_error/).

Typographical or grammatical errors have been corrected in several places.

Removed pages
-------------

HOWTOHELP
MAINTAINING
    mtk
        The content of these files is now available in HTML format.

New links
---------

cfsetspeed.3
    mtk
        Link to termios.3.

Changes to individual pages
---------------------------

time.1
    Alain Portal
        Added "Linux User's Manual" to .TH line.

_syscall.2
    aeb / mtk
        Remove outdated text about pointer blocks for syscalls that have
        more than 5 arguments.

fcntl.2
    J. Bruce Fields
        Add warning that mandatory locking is unreliable.
    J. Bruce Fields
        Clarify details in description of file leases.
    J. Bruce Fields / mtk
        Minor wording edits.
    J. Bruce Fields
        Add F_GETLEASE under RETURN VALUE.

mmap.2
    mtk
        Handle errors using a custom handle_error() macro.

sched_setscheduler.2
    Mats Wichmann
        Add BUGS text noting that the return value from Linux
        sched_setschuler() does not conform to POSIX.

spu_create.2
    Jeremy Kerr
        Various updates and improvements.
    Luke Browning
        Refinement of text describing a "gang".
    mtk
        Minor edits.

spu_run.2
    Jeremy Kerr
        Various updates and improvements.
    mtk
        Minor edits.

err.3
    mtk
        Remove HISTORY section.

fopen.3
    Mike Frysinger
        Document 'e' (close-on-exec) option, new in glibc 2.7.

getloadavg.3
    Alain Portal / mtk
        Remove HISTORY section.

printf.3
    Andries E. Brouwer / mtk
        Fix the discussion of stdarg macros in the description of
        vprintf() description.

sem_wait.3
    mtk
        Handle errors using a custom handle_error() macro.

sigsetops.3
    Mats Wichmann
        Note that sigset_t objects must be initialized
        with sigemptyset() or sigfillset() before the other
        macros are employed.

termios.3
    mtk, after a note by Alain Portal
        Added cfsetspeed() to SYNOPSIS.  Added text under CONFORMING TO
        noting that cfsetspeed() is BSD specific.

ttyslot.3
    Alain Portal
        Various references to "getty" were changed to "mingetty", since
        that is the manual page more likely to be found on current
        systems.  (Completes changes that were made in man-pages-2.44.)

initrd.4
    mtk, after a note by Alain Portal
        Move "Configuration" section to top of page (like other
        section 4 pages) and make it a .SH section.

full.4
    mtk
        Re-ordered CONFIGURATION section to go before DESCRIPTION.

sk98lin.4
    Maxime Vaudequin
        Fix reference to kernel Documentation file.

elf.5
    mtk
        Renamed HISTORY section to NOTES, and removed BSD specific info.

proc.5
    Maxime Vaudequin
        Mention grub(8) in same sentence as lilo(8).
    Maxime Vaudequin
        Improve description of /proc/sys/abi and
        /proc/sys/kernel/modprobe.

utmp.5
    Alain Portal
        Various references to "getty" were changed to "mingetty", since
        that is the manual page more likely to be found on current
        systems.  (Completes changes that were made in man-pages-2.44.)

iso_8859-2.7
    Adam Borowski
        Reverse the 2.68 change applied by mtk in response to
        http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=445085
        that replaced "Sorbian" with "Serbian".
        (Sorbian is a language of 50000 people in Brandenburg.)

man-pages.7
    mtk
        Added CONFIGURATION to list of "standard" section names.

spufs.7
    Jeremy Kerr
        Various updates and improvements.
    mtk
        Minor edits.

tcp.7
    Maxime Vaudequin
        Fix reference to kernel Documentation file.
top
==================== Changes in man-pages-2.70 ====================

Released: 2007-12-06

Global changes
--------------

Many pages
    mtk
        Remove section numbers for page references where the
        reference refers to the page itself.  (This stops man2html
        producing links from a page back to itself.)

Typographical or grammatical errors have been corrected in several places.

Changes to individual pages
---------------------------

get_mempolicy.2
    mtk
        Add CONFORMING TO section.

io_getevents.2
    mtk
        Remove redundant SEE ALSO entry.

mbind.2
    mtk
        Add CONFORMING TO section.

msgop.2
    mtk
        Remove redundant SEE ALSO entries.

sigprocmask.2
    mtk
        Remove redundant SEE ALSO entry.

splice.2
    mtk
        Remove redundant SEE ALSO entry.
        Add SEE ALSO referring to vmsplice(2).

csin.3
    mtk
        Remove redundant SEE ALSO entry.
        Add SEE ALSO referring to ccos(3).

gethostbyname.3
    mtk
        Add gethostbyaddr_r to NAME section.

rint.3
    mtk
        Remove redundant SEE ALSO entry.

sigsetops.3
    mtk
        Minor rewording.

epoll.7
    mtk
        Minor rewording.
top
==================== Changes in man-pages-2.71 ====================

Released: 2007-12-14

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
John Sigler
Josh Triplett
Mats Wichmann
Pascal MALAISE
Sam Varshavchik

Apologies if I missed anyone!

Global changes
--------------

err.3
fts.3
getloadavg.3
queue.3
rcmd.3
rexec.3
stdin.3
elf.5
operator.7
    mtk
        Replaced the use of mdoc macros on these pages with man
        macros.  The only pages in man-pages that still use
        mdoc macros are mdoc.7 and mdoc.samples.7.

Typographical or grammatical errors have been corrected in several places.

Deleted pages
-------------

TODO
    mtk
        This information is now on the website.

Changes to individual pages
---------------------------

Changes.old
    mtk
        Reformat various change log entries to use a consistent format.
        Expand Debian bug report numbers to be URLs.
        Other minor tidy-ups.

fcntl.2
    mtk
        Document the F_DUPFD_CLOEXEC operation, which is
        new in kernel 2.6.24.

listen.2
    Josh Triplett
        Fix incorrect path for somaxconn.

getpw.3
    Alain PORTAL
        Add ENOENT error to ERRORS.

sysconf.3
    Mats Wichmann
        Add documentation of _SC_NPROCESSORS_CONF and _SC_NPROCESSORS_ONLN.

tty.4
    John Sigler
        Add tty_ioctl(4) to SEE ALSO list.

regex.7
    Pascal MALAISE
        Separate text on back references from that describing basic regexps,
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=379829.
    mtk
        Remove crufty text about word boundaries.
top
==================== Changes in man-pages-2.72 ====================

Released: 2007-12-14

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Alex Tuninga
Bert Wesarg
Maxime Vaudequin
Rob Weryk
Sam Varshavchik

Apologies if I missed anyone!

Global changes
--------------

Various pages
    Alain PORTAL / mtk
        Format include files consistently (".I <.*\.h>").

Various pages
    Alain PORTAL / mtk
        Format pathname in italics (.I).

dbopen.3
mpool.3
recno.3
    Alain PORTAL
        Remove brackets ([]) around error names.

console.4
tty.4
ttyS.4
issue.5
ttytype.5
utmp.5
    mtk / Maxime Vaudequin
        Some systems have mingetty(8), others have agetty(8), so both
        should be mentioned when we are talking about getty-style programs.

Typographical or grammatical errors have been corrected in several places.

Renamed pages
-------------

filesystems.5
    mtk / Alain PORTAL
        Was previously fs.5

New links
---------

argz.3
    Bert Wesarg / mtk
        Link to argz_add.3.

envz.3
    Bert Wesarg / mtk
        Link to envz_add.3.

fs.5
    mtk / Alain PORTAL
        Link to filesystems.5.

Changes to individual pages
---------------------------

readahead.2
    Rob Weryk
        Fix declaration of 'offset' in SYNOPSIS.

seteuid.2
    mtk
        s/SETGUID/SETEUID/ in .TH line.

__setfpucw.3
    mtk
        Fixed include files references / formatting.

abort.3
    mtk, after a note by Alex Tuninga
        A fairly significant rewrite to clarify operation of abort().

argz_add.3
    Bert Wesarg / mtk
        s/envz/envz_add/ in SEE ALSO.

basename.3
    mtk
        s/DIRNAME/BASENAME/ in .TH line, and swap function names
        in NAME section.

envz_add.3
    Bert Wesarg / mtk
        s/argz/argz_add/ in SEE ALSO.

flockfile.3
    mtk
        s/LOCKFILE/FLOCKFILE/ in .TH line.

getgrent_r.3
    mtk
        s/GETGRENT/GETGRENT_R/ in .TH line.

stdio.3
    Sam Varshavchik
        Reformat function list at end of page as a proper table.

ttyslot.3
    Maxime Vaudequin
        Revert earlier s/getty/mingetty/.  This page talks about
        historical behavior, and that means "getty(8)".

undocumented.3
    mtk
        Remove reference to "obstack stuff"; it's not clear what
        that is about.

console_ioctl.4
    mtk
        s/CONSOLE_IOCTLS/CONSOLE_IOCTL/ in .TH line.

proc.5
    mtk
        s/fs (5)/filesystems (5)/

man-pages.7
    mtk / Alain PORTAL
        Improve discussion of formatting of file names.
top
==================== Changes in man-pages-2.73 ====================

Released: 2007-12-14

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Pádraig Brady
Reuben Thomas

Apologies if I missed anyone!

Global changes
--------------

Various pages
    Alain PORTAL
        Formatting fixes.

Typographical or grammatical errors have been corrected in several places.

Changes to individual pages
---------------------------

mknod.2
    mtk, after a report by Reuben Thomas
        Clarify use of mkfifo() versus mknod().
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=455825

fgetgrent.3
    mtk
        Small rewording.

fgetpwent.3
    mtk
        Small rewording.

rcmd.3
    mtk
        Noted feature test macro requirements.
        BUGS: noted that iruserok() is not declared in glibc headers.

filesystems.5
    mtk
        Added Reiserfs, XFS, JFS to list of file systems.
top
==================== Changes in man-pages-2.74 ====================

Released: 2007-12-20

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andrew Morton
David Brown
Jeremy Kerr
Mats Wichmann
Sam Morris
Sam Varshavchik
Samuel Thibault

Apologies if I missed anyone!

Global changes
--------------

Various pages
    Alain PORTAL
        Formatting fixes.

Various pages
    mtk / Alain Portal
        s/``...''/"..."/

Various pages
    mtk
        s/epoch/Epoch/

Various pages
    mtk
        Make the standard indent for code samples, shell session
        logs, etc. to be ".in +4n".

Typographical or grammatical errors have been corrected in several places.

Changes to individual pages
---------------------------

_syscall.2
    mtk
        Nowadays there is _syscall6() also.

chroot.2
    mtk
        Various minor formatting changes.

epoll_wait.2
    mtk
        Fix types in structs.
        Formatting fixes.

mount.2
    mtk, after a note by Sam Morris
        Clarify that MS_NODIRATIME provides a subset of the
        functionality provided by MS_NOATIME.

sched_setaffinity.2
    mtk
        Minor rearrangement of text.

select_tut.2
    mtk
        Fix (my) typos in argument names.
        Formatting fixes.

spu_create.2
    Jeremy Kerr
        We can use context FDs for the dirfd argument to the *at() syscalls.

times.2
    mtk, after a note from David Brown and Andrew Morton
        http://marc.info/?l=linux-kernel&m=119447727031225&w=2
        Rework the text describing the return value to be closer
        to the requirements of POSIX.1; move Linux details
        to NOTES and add a warning not to rely on those details.
        Add a warning about the -1 to -4095 bug which results
        in a 41 second window where the glibc wrapper will wrongly
        return -1 indicating an error.
    mtk
        Remove cruft HZ text.
        Clarify text describing return value of clock(3).

getw.3
    Mats Wichmann
        CONFORMING TO: getw() and putw() were in SUSv2, but are not
        in POSIX.1-2001.

hash.3
    mtk / Alain Portal
        Minor rewordings + formatting fixes.

st.4
    Alain Portal / mtk
        Many formatting fixes.
    mtk
        Place ERRORS in alphabetical order.

vcs.4
    Samuel Thibault
        Document VT_GETHIFONTMASK (new in 2.6.18) and add to example program;
        attribute/text characters are in the host byte order.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=456437
    mtk
        Minor edits.

bootparam.7
    Alain PORTAL
        Formatting fixes.

inotify.7
    mtk
        Minor heading changes and reformattings.

man-pages.7
    mtk
        Note that code segments, structure definitions, shell session
        logs, should be indented by 4 spaces.

spufs.7
    Jeremy Kerr
        Add a little information about the differences to mbox.
top
==================== Changes in man-pages-2.75 ====================

Released: 2008-01-08

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andi Kleen
Andreas Henriksson
Jeremy Kerr
Justin Pryzby
Phil Endecott
Sam Varshavchik
Thomas Huriaux
Timo Sirainen
Trond Myklebust

Apologies if I missed anyone!

Global changes
--------------

Various pages
    mtk
        (Grammatical) hyphenation was fixed in many places.

epoll_wait.2
mbind.2
spu_run.2
ecvt.3
fmtmsg.3
getnameinfo.3
rtc.4
proc.5
charsets.7
ip.7
ipv6.7
raw.7
uri.7
    Justin Pryzby / mtk
        Fix incorrect usage of "a" and "an" before following vowel /
        consonant, by reviewing the output of the following scripts:

            for a in  $(wc */*.? | awk '$1 > 10 {print $4}' | gv total); do
                echo $a
                MANWIDTH=4000 man -l $a 2>/dev/null |
                        egrep '(^| )an [^aeiou][a-z]'
            done | less

            for a in  $(wc */*.? | awk '$1 > 10 {print $4}' | gv total); do
                echo $a
                MANWIDTH=4000 man -l $a 2>/dev/null |
                        egrep '(^| )a [aeiou][a-z]'
            done| less

err.3
fts.3
queue.3
rcmd.3
rexec.3
stdin.3
elf.5
    mtk, after a note by Alain Portal
        Improve macros used in 2.71 to convert from "mdoc" to "man".

_exit.2
chroot.2
getgid.2
getpid.2
getrusage.2
getsid.2
gettid.2
getuid.2
iopl.2
kill.2
personality.2
pivot_root.2
ptrace.2
sched_setparam.2
sched_setscheduler.2
sched_yield.2
seteuid.2
setgid.2
setpgid.2
setresuid.2
setreuid.2
setuid.2
unlink.2
wait.2
openpty.3
raise.3
setlogmask.3
sleep.3
ttyslot.3
ulimit.3
tty.4
tty_ioctl.4
path_resolution.7
    mtk
        s/current process/calling process/

cacheflush.2
clone.2
fcntl.2
getitimer.2
getrlimit.2
mmap.2
mprotect.2
times.2
adjtime.3
byteorder.3
inet.3
offsetof.3
rtc.4
icmp.7
pipe.7
time.7
    mtk
        s/x86/i386/ since that is the name used in 'arch' directories
        in the kernel source, and previously both i386 and x86 were both
        used in man pages; also nowadays 'x86' is somewhat ambiguous,
        since it is the name of the 'arch' directory for i386 and x86-64.

conj.3
cacos.3
cacosh.3
cabs.3
carg.3
casin.3
casinh.3
catan.3
catanh.3
ccos.3
ccosh.3
cexp.3
cimag.3
clog.3
cosh.3
creal.3
csin.3
csinh.3
ctan.3
ctanh.3
sinh.3
tanh.3
    mtk
        Various reformattings.

Various pages
    Alain Portal
        Formating fixes.

mlock.2
mprotect.2
mpool.3
offsetof.3
    Alain Portal
        Format SYNOPSIS in a manner consistent with other pages.

Various pages
    mtk / Alain Portal
        Format casts so that there is a non-breaking space after the
        type, and remove unnecessary parentheses around the casted value.
        Thus, for example, the following:

            .IR "(size_t) (\-1)" .

        becomes:

            .IR "(size_t)\ \-1" .

Various pages
    mtk / Alain Portal
        Replace "-" by "\-" where a real dash is required.

Various pages
    mtk
        Make the formatting of instances of '*varname' consistent, changing
        instances such as:

            .RI * varname

        to:

            .I *varname

pciconfig_read.2
nfsservctl.2
bstring.3
cpow.3
getipnodebyname.3
getpwnam.3
getrpcent.3
lsearch.3
malloc_hook.3
mpool.3
stdin.3
strtol.3
strtoul.3
unlocked_stdio.3
regex.3
sd.4
resolv.conf.5
utmp.5
futex.7
    mtk
        Format SYNOPSIS consistently.

drand48.3
drand48_r.3
flockfile.3
erf.3
sigvec.3
timeradd.3
wprintf.3
    mtk, after a note by Alain Portal
        Standardize sentence used under "Feature Test Macro Requirements"
        when referring to all functions shown in the SYNOPSIS.

get_kernel_syms.2
getdents.2
getitimer.2
nanosleep.2
query_module.2
statvfs.2
clock_getres.3
getaddrinfo.3
getgrent.3
getipnodebyname.3
console_ioctl.4
tty_ioctl.4
rtnetlink.7
    mtk
        Indent structure definitions by +4n.

recv.2
btree.3
dbopen.3
ether_aton.3
fts.3
hash.3
mpool.3
profil.3
rcmd.3
recno.3
rpc.3
xdr.3
console_ioctl.4
ddp.7
ip.7
ipv6.7
svipc.7
    mtk
        Use C99 standard types in declarations.
            s/u_long/unsigned long/
            s/ulong/unsigned long/
            s/u_char/unsigned char/
            s/u_short/unsigned short/
            s/ushort/unsigned short/
            s/u_int8_t/uint8_t/
            s/u_int16_t/uint16_t/
            s/u_int32_t/uint32_t/
            s/u_int/unsigned int/

exit_group.2
fallocate.2
getdents.2
ioctl_list.2
nfsservctl.2
sched_setaffinity.2
set_tid_address.2
ustat.2
argz_add.3
confstr.3
envz_add.3
getline.3
getpwnam.3
gets.3
getw.3
inet_ntop.3
inet_pton.3
offsetof.3
console_ioctl.4
termcap.5
ascii.7
feature_test_macros.7
netlink.7
operator.7
svipc.7
    mtk
        Fix unbalanced .nf/.fi pairs.

chmod.2
getxattr.2
listxattr.2
lseek.2
removexattr.2
setxattr.2
stat.2
feature_test_macros.7
fpathconf.3
fopen.3

    mtk
        Rename argument: s/file*des/fd/ , since that is the name most
        commonly used on man pages for a file descriptor argument.

bindresvport.3
des_crypt.3
getopt.3
getrpcent.3
realpath.3
rpc.3
xdr.3
    mtk
        Removed .SM macros.

madvise.2
getdirentries.3
printf.3
sigvec.3
    mtk
        Remove extraneous .br macro before/after .SH/.SS.

_syscall.2
lookup_dcookie.2
aio_cancel.3
aio_error.3
aio_fsync.3
aio_read.3
aio_return.3
aio_write.3
canonicalize_file_name.3
envz_add.3
getgrouplist.3
getttyent.3
key_setsecret.3
mtrace.3
tcgetpgrp.3
tcgetsid.3
ttyslot.3
tty_ioctl.4
    mtk
        Remove extraneous .sp macros.

fcntl.2
outb.2
send.2
syscalls.2
getopt.3
proc.5
man-pages.7
standards.7
tcp.7
    mtk
        Remove/replace extraneous .sp macros.

Typographical or grammatical errors have been corrected in several places.

Changes to individual pages
---------------------------

_syscall.2
    mtk
        Nowadays there are seven macros (see 2.74 change log also).

arch_prctl.2
    mtk, Acked by Andi Kleen
        Clarify interpretation of 'addr'; plus a few other minor edits
        and updates.

bind.2
    mtk
        Minor rewrites.

close.2
    mtk
        Clarify relationship between file descriptor and open file
        description.

connect.2
    mtk, Acked by Andi Kleen
        Since kernel 2.2, AF_UNSPEC for unconnecting a connected
        socket *is* supported.

execve.2
    Alain Portal
        Minor rewordings.

futimesat.2
    Alain Portal
        Remove duplicate "#include <fcntl.h>" from SYNOPSIS.

getgid.2
    mtk
        Add getresgid(2) and credentials(7) to SEE ALSO.

getpagesize.2
    mtk
        Small rewording.

getresuid.2
    mtk
        Rewrote various parts.

getuid.2
    mtk
        Add getresuid(2) and credentials(7) to SEE ALSO.

ioctl_list.2
    Alain Portal
        Use proper tables for layout, and various formatting fixes.
    mtk
        Various formatting fixes.

listen.2
    mtk
        Rewrote various parts.

mbind.2
    Andi Kleen / mtk / Alain Portal
        Modify explanation of EINVAL 'maxnode' error.

mmap.2
    mtk
        Add comma to clarify meaning of a sentence.

open.2
    mtk
        Clarify initial description of O_EXCL.
        Clarify description of behaviors of O_CREAT | O_EXCL
        for symbolic links.
        Clarify text describing use of lockfiles without O_EXCL.
    mtk, with input from Timo Sirainen and Trond Myklebust
        O_EXCL is supported on NFSv3 and later, with Linux 2.6 and later.

pipe.2
    mtk
        Rename 'filedes' argument 'pipefd'.

pivot_root.2
    mtk
        s/cwd/current working directory/

seteuid.2
    mtk
        Minor changes.

setpgid.2
    mtk
        Add credentials(7) to SEE ALSO, and updated copyright credits,
        to reflect my rewrite of a few months ago.

setsid.2
    mtk
        Add getsid(2) and credentials(7) to SEE ALSO.

spu_create.2
    Alain Portal / mtk; acked by Jeremy Kerr
        Minor formatting/wording changes.
    mtk
        Put EPERM in right alphabetical position in ERRORS list.

argz_add.3
    mtk
        Formatting fixes.

atexit.3
    mtk
        Minor changes to example program.

cerf.3
    mtk
        These functions are still not present as at glibc 2.7.

dbopen.3
    Alain Portal / mtk
        Various minor spelling and formatting fixes.

envz_add.3
    mtk
        Formatting fixes.

fexecve.3
    mtk
        Fix placement of feature test macro in SYNOPSIS.

fmax.3
fmin.3
    mtk
        Small rewording.

getline.3
    mtk
        Minor changes to example program.

getrpcent.3
getrpcport.3
    mtk
        Use modern C prototypes in SYNOPSIS.

getutent.3
    Alain Portal / mtk
        Formatting fixes.

mbsnrtowcs.3
mbsrtowcs.3
mbstowcs.3
    mtk
        Use .IP tags to create properly formatted lists.

rpc.3
    mtk
        Convert function declarations to use modern C prototypes.
        Add text and start of page describing header files
        and types required by functions.
        Reformat discussion of request under clnt_control().

xdr.3
    mtk
        Convert function declarations to use modern C prototypes.
        Remove crufty "int empty" from xdrrec_eof() description.

console_codes.4
    Phil Endecott
        Relocate misplaced line:
            "and if LF/NL (new line mode) is set also a carriage return;"
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=458338.

console_ioctl.4
    mtk
        Formatting fixes.

bootparam.7
    mtk, after a note by Alan Portal
        Fix reference to kernel documentation source file in the
        "The Sound Driver" subsection.

man-pages.7
    Alain Portal
        Move CONFIGURATION description after SYNOPSIS description.
    mtk / Alain Portal
        Note that header files should be surrounded by angle brackets (<>).

posixoptions.7
    mtk
        Minor formatting and wording fixes.

rtnetlink.7
    Andreas Henriksson
        Fix description of RTM_F_EQUALIZE.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=458325.

signal.7
    mtk
        Minor formatting and wording fixes.

socket.7
    mtk
        Small rewording of discussion of O_ASYNC.

spufs.7
    mtk / Jeremy Kerr / Alain Portal
        s/SPE/SPU/
top
==================== Changes in man-pages-2.76 ====================

Released: 2008-01-14

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Carlo Marcelo Arenas Belon
Jeremy Kerr
Sam Varshavchik
Trond Myklebust

Apologies if I missed anyone!

Global changes
--------------

longjmp.3
printf.3
scanf.3
setbuf.3
setjmp.3
sk98lin.4
environ.7
    mtk
        Rework/remove use of ".ad" macros.

ioctl_list.2
mlock.2
mprotect.2
mremap.2
syslog.2
cfree.3
mpool.3
offsetof.3
rpc.3
stdin.3
    mtk
        Fix unbalanced quotes in formatting macros.

ftok.3
    mtk
        s/i-node/inode/, for consistency with other pages and POSIX.1-2001.

Typographical or grammatical errors have been corrected in several places.

Changes to individual pages
---------------------------

chown.2
    mtk
        Minor wording change.

dup.2
    mtk
        Reordered text in DESCRIPTION and added some details for dup2().

open.2
    Trond Myklebust / mtk
        Minor fix to O_EXCL changes in previous release.

gettid.2
    mtk
        Rewrote DESCRIPTION; noted that thread ID is not the same
        thing as a POSIX thread ID.

pipe.2
    mtk
        Rewrote DESCRIPTION; minor additions to EXAMPLE text.

umask.2
    mtk
        A few rewrites and additions.

strptime.3
    Carlo Marcelo Arenas Belon / mtk
        Add "#define _XOPEN_SOURCE" to example program.

initrd.4
    mtk
        Use quotes more consistently in formatting macros.

random.4
    mtk, after a report by Daniel Kahn Gilmor
        Add 2.6 details for /proc/sys/kernel/random/poolsize.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=459232.

pthreads.7
    mtk
        Minor changes.

spufs.7
    mtk / Jeremy Kerr
        Define abbreviation "MSS".
top
==================== Changes in man-pages-2.77 ====================

Released: 2008-01-31

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Pavel Heimlich
Phil Endecott
Thomas Huriaux
Vincent Lefevre
WANG Cong

Apologies if I missed anyone!

Global changes
--------------

stdarg.3
bootparam.7
    Thomas Huriaux
        Fix broken use of single quotes at start of line,
        as per: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=462636

Typographical or grammatical errors have been corrected in several places.

New pages
---------

remove_COLOPHON.sh
    mtk
        Script to remove the COLOPHON section from the man pages provided
        as command-line arguments.  This is useful to remove the COLOPHON
        sections from all of the man pages in two different release trees
        in order to do a "diff -ruN" to see the "real" differences
        between the trees.

Changes to individual pages
---------------------------

fcntl.2
    mtk
        Replace tables with .TP macros.

fork.2
    mtk
        Added discussion of directory streams.
        Removed "#include <sys/types>" from SYNOPSIS.
        Changed authorship notice.

futex.2
    mtk
        Add ENOSYS error to errors.
    Phil Endecott
        Explicitly describe return value in the event of an error.

inotify_add_watch.2
    mtk
        Minor wording changes.

splice.2
    WANG Cong
        Fix types for 2 and 4 arguments in splice prototype.

wait.2
    Phil Endecott
        Clarify description of return value for WNOHANG.

tkill.2
    mtk
        Rewrote DESCRIPTION; emphasized that tkill() is obsoleted by
        tgkill().

alloca.3
    mtk
        Change description in NAME section.
        Various rewrites and additions (including notes on longjmp() and
        SIGSEGV).
    mtk / Vincent Lefevre
        Weaken warning against use of alloca(), and
        point out some cases where it can be useful;
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=461100.

bootparam.7
    Pavel Heimlich
        Remove junk line.

inotify.7
    mtk
        Replace tables with .TP macros.
        s/MultiSource Synchronization/MultiSource Synchronization (MSS)/
top
==================== Changes in man-pages-2.78 ====================

Released: 2008-02-15

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Davide Libenzi
Greg Banks
Michael Tokarev
Phil Endecott

Apologies if I missed anyone!

Global changes
--------------

sigaction.2
signal.2
sigwaitinfo.2
signal.7
    mtk
        Add SEE ALSO entry referring to new signalfd.2 page.

Typographical or grammatical errors have been corrected in several places.

New pages
---------

eventfd.2
    mtk, with input and review from Davide Libenzi
        Documents the eventfd() system call, new in 2.6.22.

signalfd.2
    mtk, with input and review from Davide Libenzi
        Documents the signalfd() system call, new in 2.6.22.

Changes to individual pages
---------------------------

futex.2
    mtk / Phil Endecott
        Improve wording describing error returns.

open.2
    Greg Banks
        Greatly expand the detail on O_DIRECT.

reboot.2
    mtk / Michael Tokarev
        Fix RETURN VALUE description: in some cases reboot() does not
        return.
    mtk
        Rename the 'flag' argument to 'cmd', since that is more meaningful,
        and also what is used in the kernel source.
        Other minor wording changes.
top
==================== Changes in man-pages-2.79 ====================

Released: 2008-03-07

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries E. Brouwer
Chris Heath
Davide Libenzi
Fernando Luis Vázquez Cao
Heikki Orsila
Jeremy Kerr
Justin Pryzby
Lasse Kärkkäinen
Michael Haardt
Mike Frysinger
Ron Burk
Sam Varshavchik
Samuel Thibault
Walter Harms

Apologies if I missed anyone!

Global changes
--------------

Typographical or grammatical errors have been corrected in several places.

New pages
---------

timerfd_create.2
    mtk, with input and review from Davide Libenzi
        Documents the timerfd_create(), timerfd_settime(), and
        timerfd_gettime() system calls, which are new in 2.6.25.

New links
---------

timerfd_gettime.2
timerfd_settime.2
    mtk
        Links to new timerfd_create.2 page.

eventfd_read.3
eventfd_write.3
    mtk
        Links to eventfd.2.

Changes to individual pages
---------------------------

Makefile
    aeb
        Remove code relating to man1/README, which no longer exists.

execve.2
    mtk
        Clarify detail of RLIMIT_STACK/4 limit for argv+environ.

getitimer.2
    mtk
        Added SEE ALSO entry referring to timerfd_create.2.

getrusage.2
    mtk
        Minor rewordings.

open.2
    Michael Haardt
        Move discussion of 'mode' argument under description of O_CREAT.

signalfd.2
    mtk
        Fix type for 'ssi_ptr' field.
        See http://sources.redhat.com/ml/libc-hacker/2008-01/msg00002.html.

syscalls.2
    mtk
        Add timerfd_create(), timerfd_settime(), and timerfd_gettime()
        to list.

syslog.2
    Jeremy Kerr
        Add info on command type 10.
        Add details on types 6, 7, 8, and 9.
        Minor grammar fix.
    mtk
        Update LOG_BUF_LEN details.
        Update RETURN VALUE section.
        Notes capability requirements under EPERM error.
        Minor fix to description of type==3 and type==4.
        Other minor edits.

ctime.3
    Walter Harms
        Note that POSIX requires localtime() to act as though tzset()
        was called, but localtime_r() does not have the same requirement.
        See also http://thread.gmane.org/gmane.comp.time.tz/2034/

getaddrinfo.3
    mtk
        Clarify discussion of NULL 'hints' argument; other minor rewrites.
    mtk / Sam Varshavchik
        Remove some duplicated text.

malloc.3
    Lasse Kärkkäinen / Mike Frysinger / mtk
        Clarify description of realloc() behavior for
        ((size == 0) && (ptr != NULL)).

posix_fallocate.3
    Samuel Thibault
        s/stdlib.h/fcntl.h/ in SYNOPSIS.

proc.5
    Fernando Luis Vázquez Cao
        Update /proc/[number]/cmdline description.
        It used to be true that the command line arguments were
        not accessible when the process had been swapped out.
        In ancient kernels (circa 2.0.*) the problem was that the
        kernel relied on get_phys_addr to access the user space buffer,
        which stopped working as soon as the process was swapped out.
        Recent kernels use get_user_pages for the same purpose and thus
        they should not have that limitation.

epoll.7
    Davide Libenzi / mtk
        Clarify the somewhat unintuitive behavior that occurs if a file
        descriptor in an epoll set is closed while other file descriptors
        referring to the same underlying open file description remain
        open.
        See also http://thread.gmane.org/gmane.linux.kernel/596462/.
    mtk
        Clarify error that occurs if we add an epoll fd to its own set.
    mtk
        A few minor rewordings.
    mtk, after a note by Chris Heath
        Rework Q1/A1, describing what happens when adding the same
        file descriptor twice to an epoll set, and when adding duplicate
        file descriptors to the same epoll set.
    Heikki Orsila / mtk / Davide Libenzi
        Clarify Q9/A9 to discuss packet/token-oriented files.
    mtk, after comments by Davide Libenzi and Chris Heath
        Added Q0/A0, making explicit that the key for items in an epoll
        set is [file descriptor, open file description].
    mtk, after a note by Ron Burk
        Change A3, to note that when events are available,
        the epoll file descriptor will indicate as being readable.
    mtk
        Add some further explanation to Q5/A5 about why an epoll file
        descriptor cannot be passed across a Unix domain socket.

posixoptions.7
    mtk
        Add SEE ALSO entry for standards(7).

regex.7
    mtk
        Add grep(1) to SEE ALSO.
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348552.

standards.7
    mtk
        Add SEE ALSO entry for posixoptions(7).

time.7
    mtk
        Added SEE ALSO entry referring to timerfd_create.2.
top
==================== Changes in man-pages-2.80 ====================

Released: 2008-06-05

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Adrian Bunk
Alain Portal
Andreas Herrmann
Andrew Morton
Andries E. Brouwer
Anoop
Aurelien Gerome
Daniel Burr
Davide Libenzi
Felix Kater
Folkert van Heusden
Hamaji Shinichiro
Heikki Orsila
Ingo Molnar
Justin Pryzby
Karsten Weiss
Martin Pitt
Marty Leisner
Nicolas François
Nick Piggin
Petter Reinholdtsen
Reuben Thomas
Sam Varshavchik
Stuart Brady
Theodoros V. Kalamatianos
Thomas Huriaux
Tim Stoakes
Timothy Baldwin
Tolga Dalman

Apologies if I missed anyone!

Global changes
--------------

bdflush.2
inotify_add_watch.2
mprotect.2
sigprocmask.2
ctime.3
getusershell.3
setbuf.3
st.4
ip.7
packet.7
    mtk
        Replace "(il)legal" by "(not) permitted" or "(in)valid".

read.2
utime.2
filesystems.5
packet.7
    mtk
        s/time stamp/timestamp/, for consistency with majority use
        in other pages, and in POSIX.1.

madvise.2
mbind.2
mincore.2
mmap.2
mmap2.2
msync.2
remap_file_pages.2
    mtk
        Change name of 'start' argument to 'addr' for consistency
        with:
            * other memory-related interfaces
            * POSIX specification (for those interfaces in POSIX)
            * Linux and glibc source code (in at least some cases)

Various pages
    mtk
        s/filesystem/file system/, for consistency with majority use
        in other pages, and in POSIX.1.

Various pages
    mtk
        s/zeroes/zeros/, for consistency with majority use
        in other pages, and in POSIX.1.

abs.3
proc.5
    mtk
        s/builtin/built-in/, for consistency with majority use
        in other pages, and in POSIX.1.

mknod.2
ftw.3
    mtk
        s/normal file/regular file/

Various pages
    mtk
        s/nonempty/non-empty/

Various pages
    mtk
        s/nonzero/non-zero/

Various pages
    mtk
        s/realtime/real-time/, for consistency with majority usage.

Various pages
    mtk
        s/command line/command-line/ when used attributively.

Various pages
    mtk
        Use "run time" when non-attributive, "run-time" when attributive.

Various pages
    mtk
        Various pages that I wrote carried a slightly modified version
        of the "verbatim" license.  In the interests of minimizing
        license proliferation, I've reverted the modified form
        so that the license is exactly the same as on other pages
        carrying the verbatim license.

epoll_ctl.2
getitimer.2
getrlimit.2
unix.7
    mtk
        s/since kernel x.y.z/since Linux x.y.z/

wait.2
inotify.7
    mtk
        Reformat kernel version information for flags.

Typographical or grammatical errors have been corrected in several places.
(Special thanks to Nicolas François.)

New pages
---------

random_r.3
    mtk, after a suggestion by aeb
        Documents random_r(3), srandom_r(3), initstate_r(3), and
        setstate_r(3), which are the reentrant equivalents of
        random(3), srandom(3), initstate(3), and setstate(3).

New links
---------

lutimes.3
    mtk
        Link to futimes.3.

initstate_r.3
setstate_r.3
srandom_r.3
    mtk
        Links to random_r.3.

daylight.3
timezone.3
tzname.3
    mtk
        Links to tzset.3.

isnanf.3
isnanl.3
    mtk
        Links to finite.3.

encrypt_r.3
setkey_r.3
    mtk
        Links to encrypt.3.

Changes to individual pages
---------------------------

clone.2
    mtk
        Added note that CLONE_STOPPED (which no-one uses anyway) is
        now deprecated.

epoll_create.2
    mtk
        Add NOTES section pointing out that 'size' argument is unused
        since kernel 2.6.8.

epoll_ctl.2
    mtk
        Added portability note to BUGS text for EPOLL_CTL_DEL.

epoll_wait.2
    mtk
        If the 'sigmask' is NULL, then epoll_pwait() is equivalent
        to epoll_wait().

fork.2
    mtk
        NOTES: since glibc 2.3.3, the glibc NPTL fork() wrapper
        bypasses the fork() system call to invoke clone() with
        flags providing equivalent functionality.

futex.2
    mtk, after a note from Adrian Bunk
        FUTEX_FD has been removed, as of kernel 2.6.26.

futimesat.2
    mtk
        Note that this system call is made obsolete by utimensat(2).

getgroups.2
    Petter Reinholdtsen
        SEE ALSO: Add getgrouplist(3).
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284.
    mtk
        NGROUPS_MAX increased in kernel 2.6.4.
        SEE ALSO: Add credentials(7).
    mtk
        Reformat DESCRIPTION and RETURN VALUE sections to be more
        consistent with man-pages style.
        Add some more detail to descriptions of system calls.
        Clarified what happens if caller of getgroups() is a member of
        more than 'size' supplementary groups.
        ERRORS: Add ENOMEM.

getpriority.2
    mtk, after a note from Ingo Molnar
        Add text in NOTES about the punchier effect of nice values in
        kernel 2.6.23 and later.
        Add Documentation/scheduler/sched-nice-design.txt to SEE ALSO list.

gettid.2
    mtk
        Added VERSIONS section noting that this system call first
        appeared in 2.4.11.

kill.2
    Marty Leisner / mtk
        Add text explicitly noting that sig==0 can be used to check for
        the existence of a PID or PGID.
    mtk
        A few minor rewordings.

mbind.2
    mtk
        The location of the numactl package has changed.

mmap.2
    mtk
        Added some .SS headings to make structure of page a little
        more obvious.
    mtk, with input from Nick Piggin
        MAP_POPULATE supports both file and anonymous mappings.
        Since 2.6.23, MAP_POPULATE supports private mappings.
        Since 2.6.23, MAP_NONBLOCK causes MAP_POPULATE to be a no-op.
    mtk
        NOTES: Added details on mapping address that is selected by
        kernel when MAP_FIXED is / isn't specified.

mount.2
    mtk
        The MS_REMOUNT changes in 2.4 were at 2.4.10 (not 2.4).
    mtk
        Minor wording change.

msgctl.2
    mtk
        Clarify that "unused" fields in msginfo structure are
        "unused within the kernel".
        msginfo.msgpool is measured in kilobytes, not bytes.
        Minor rewordings in comments for msginfo structure.

msgop.2
    mtk
        Various minor rewordings and restructurings for clarity.
    mtk, after a note from Reuben Thomas
        Remove "msgop" from NAME section.

mkdir.2
    mtk
        Clarify meaning of "BSD group semantics".
        SEE ALSO: add chown(2).

mknod.2
    mtk
        SEE ALSO: add chown(2) and chmod(2).

mmap.2
    mtk
        SEE ALSO: add mprotect(2) and shmat(2).

mprotect.2
    Hamaji Shinichiro
        SYNOPSIS: s/size_t \*len/size_t len/

open.2
    mtk
        Note that O_CLOEXEC should be in the next POSIX.1 revision.
    mtk
        More than just ext2 supports "mount -o bsdgroups" nowadays,
        so make the discussion about group ownership of new files a bit
        more generic.
    mtk
        SEE ALSO: add chown(2) and chmod(2).

poll.2
    mtk
        If the 'sigmask' is NULL, then ppoll() is equivalent to poll()
        with respect to signal mask manipulations.

posix_fadvise.2
    mtk
        s/posix_madvise (2)/posix_madvise (3)/;
        (The referred-to page still doesn't exist yet, but hopefully
        will do sometime soon.)

ptrace.2
    Anoop, Acked by Roland McGrath.
        Re PTRACE_PEEKUSER: the offsets and data returned might not
        match with the definition of struct user.
        See also http://lkml.org/lkml/2008/5/8/375

recv.2
    Felix Kater / mtk
        Improve wording for EAGAIN error in discussion of MSG_DONTWAIT.

rmdir.2
    Martin Pitt
        POSIX.1 also allows EEXIST for the ENOTEMPTY error condition.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=467552.

sched_setscheduler.2
    mtk, with input from Ingo Molnar
        Add description of SCHED_IDLE policy (new in 2.6.23).
        Tweak description of SCHED_BATCH.
        Minor rewordings.

select_tut.2
    Justin Pryzby
        Various wording clean-ups.

semctl.2
    mtk
        Clarify that "unused" fields in seminfo structure are
        "unused within the kernel".
        Minor rewordings in comments for seminfo structure.

semop.2
    Aurelien Gerome
        Small fix in example code.

setpgid.2
    mtk / Karsten Weiss
        Clarify description of setpgid() a little.

shmctl.2
    mtk
        Clarify that "unused" fields in shminfo structure are
        "unused within the kernel".
        Minor rewordings in comments for shminfo structure.

shmop.2
    mtk, after a note from Reuben Thomas
        Remove "shmop" from NAME section.

signalfd.2
    mtk
        Added BUGS text noting that before kernel 2.6.25, the ssi_int
        and ssi_ptr fields are not set.
        Added comments describing fields in signalfd_siginfo structure.
        Update field names in example program (s/signo/ssi_signo/).
        Various small fixes, and remove duplicated sentence.
        Minor edits to structure definition.

sigqueue.2
    mtk
        Added some comments to code in NOTES.

stat.2
    mtk
        Minor wording change.

symlink.2
    mtk
        SEE ALSO: add lchown(2).

sync_file_range.2
    mtk / Andrew Morton
        Remove statement that (SYNC_FILE_RANGE_WAIT_BEFORE |
        SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER) is
        a traditional fdatasync(2) operation.
        See https://bugzilla.mozilla.org/show_bug.cgi?id=421482
        comments 129 to 131.

syscalls.2
    mtk
        This page is now up to date as at kernel 2.6.25.

syslog.2
    mtk
        Small tidy up of language relating to permissions/capabilities.

timerfd_create.2
    mtk
        Minor change to example program.
        Minor wording change.

utime.2
    Reuben Thomas
        Remove unnecessary subheading for utimes().
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=477402.
    mtk
        Change description in NAME line ("or" is not correct: these calls
        always change *both* timestamps).
        CONFORMING TO: utimes() is in POSIX.1-2001.
    mtk
        Rename 'buf' argument of utime() to 'times' (like utimes()).
        Clarify explanation of EACCES and EPERM errors.
        Remove BUGS section, since it doesn't seem to add useful
        information.
        Clarified discussion of capabilities, and noted that
        CAP_DAC_OVERRIDE also has a role.
        Other minor rewordings.

wait.2
    mtk, after a note by Justin Pryzby
        Add a sentence clarifying that even though the default disposition
        of SIGCHLD is "ignore", explicitly setting the disposition to
        SIG_IGN results in different treatment of zombies.

aio_cancel.3
aio_error.3
aio_fsync.3
aio_read.3
aio_return.3
aio_suspend.3
aio_write.3
    Kevin O'Gorman
        Add "Link with -lrt" to SYNOPSIS.

backtrace.3
    Nicolas François
        s/backtrace_symbols/backtrace_symbols_fd/ in one sentence.
    mtk
        Fix bogus reference to variable 'strings': should be:
        "the array of pointers".

ctime.3
    mtk
        Add warning under NOTES that asctime(), ctime(), gmtime(), and
        localtime() may each overwrite the static object returned by any
        of the other calls.
        Other minor edits.

dlopen.3
    mtk
        Add more detail to the description of the fields in the
        structure returned by dladdr().

fexecve.3
    mtk
        Clean up SYNOPSIS after work by cut-and-paste-Pete:
        the necessary header file is <unistd.h> not <sys/time.h>!

futimes.3
    mtk
        Add documentation of lutimes(), which appeared in glibc 2.6.
    mtk
        Change description in NAME line ("or" is not correct: these calls
        always change *both* timestamps).
        CONFORMING TO: futimes() did not come from 4.2BSD.  (It came from
        FreeBSD; see the FreeBSD man page.)

getenv.3
    mtk
        Noted that caller must not modify returned value string.
        Noted that getenv() is not reentrant: the buffer may be statically
        allocated and overwritten by later calls to getenv(), putenv(),
        setenv(), or unsetenv().
        Other minor rewrites.

getgrent.3
    Petter Reinholdtsen
        SEE ALSO: Add getgrouplist(3).
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284.

gethostbyname.3
    mtk
        Add 'h_errno' to NAME list.

getopt.3
    mtk
        Add 'optarg', 'optind', 'opterr', and 'optopt' to NAME section.
        Add subheading for getopt_long() and getopt_long_only()
        description.

getpt.3
    mtk
        Point out that this function should be avoided in favor of
        posix_openpt().
        Add ERRORS section referring to open(2).

getsubopt.3
    Daniel Burr
        SYNOPSIS: Fix declaration of valuep.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476672.

malloc.3
    mtk
        RETURN VALUE: Note circumstances in which successful malloc() and
        calloc() can return NULL.

mq_open.3
    mtk, after a note by Marty Leisner
        Note that <fcntl.h> is needed for O_* constants and <sys/stat.h>
        is needed for 'mode' constants.

opendir.3
    mtk
        Describe treatment of close-on-exec flag by opendir() and
        fdopendir().

openpty.3
    mtk
        SEE ALSO: add ttyname(3).

raise.3
    mtk / Timothy Baldwin
        Clarify semantics of raise() when called from a multithreaded
        program.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476484.
    mtk
        Rewrites and additions to various parts of the page.

rand.3
    Tolga Dalman / aeb / mtk
        Remove outdated warning in NOTES; encourage the use of
        random(3) instead.
    Folkert van Heusden
        Clarify wording describing range of values returned by rand().

random.3
    aeb / mtk / Tolga Dalman
        Recommend use or random_r(3) for multithreaded applications
        that need independent, reproducible sequences of random numbers.

        Move references to "The Art of Computer Programming" and
        "Numerical Recipes", formerly in rand(3), to this page.

        Add drand48(93) to SEE ALSO list.

regex.3
    Heikki Orsila
        Clarify description of 'rm_eo' field.

sem_open.3
    mtk, after a note by Marty Leisner
        Note that <fcntl.h> is needed for O_* constants and <sys/stat.h> is
        needed for 'mode' constants.

sem_post.3
    mtk
        Added pointer to example in sem_wait(3).

sem_close.3
sem_destroy.3
sem_getvalue.3
sem_init.3
sem_open.3
sem_post.3
sem_unlink.3
sem_wait.3
    mtk, after a note from Marty Leisner
        Add text to SYNOPSIS noting the need to link with "-lrt" or
        "-pthread".

setenv.3
    mtk
        setenv() copies 'name' and 'value' (contrast with putenv()).
        unsetenv() of a nonexistent variable does nothing and is
        considered successful.
        Noted that setenv() and unsetenv() need not be reentrant.

shm_open.3
    mtk, after a note by Marty Leisner
        Note that <fcntl.h> is needed for O_* constants and <sys/stat.h> is
        needed for 'mode' constants.

undocumented.3
    mtk
        initstate_r(3), setkey_r(3), setstate_r(3) are now documented.

utmp.5
    Nicolas François
        Small rewording.

resolv.conf.5
    Nicolas François
        gethostname() is in Section 2, not section 3.

ascii.7
    Stuart Brady
        Fix rendering of ' (backtick) and apostrophe (') in tables

charsets.7
    Nicolas François
        s/unicode.com/unicode.org/

credentials.7
    mtk
        NOTES: Pthreads requires that all threads share the same UIDs and
        GIDs.  But the Linux kernel maintains separate UIDs and GIDs for
        every thread.  NPTL does some work to ensure that credential
        changes by any thread are carried through to all POSIX threads in
        a process.
    mtk
        sysconf(_SC_NGROUPS_MAX) can be used to determine the number of
        supplementary groups that a process may belong to.
        Clarify that supplementary group IDs are specified in POSIX.1-2001.

epoll.7
    mtk, after a note from Sam Varshavchik
        For answer A2, change "not recommended" to "careful programming
        may be required".

inotify.7
    mtk
        Document SIGIO feature (new in 2.6.25) for inotify file descriptors.
    mtk
        Note that select()/poll()/epoll_wait() indicate a ready inotify
        file descriptor as readable.
    mtk
        Document IN_ATTRIB in a little more detail.

pthreads.7
    Justin Pryzby
        Grammar fix, plus fix typo in script.
    mtk
        Add list of thread-safe functions.

standards.7
    mtk
        Add a section on the upcoming POSIX revision.

ld.so.8
    Justin Pryzby / mtk
        Various wording improvements.
top
==================== Changes in man-pages-3.00 ====================

Released: 2008-06-12, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries Brouwer
Stuart Brady

Apologies if I missed anyone!

Global changes
--------------

The POSIX.1 man pages (sections 0p, 1p, 3p) have been moved out
of this package into the separate man-pages-posix package.
This made sense because those pages are seldom changed (only formatting
fixes, etc.) so that it was unnecessary to redistribute them with each
man-pages release.

console_codes.4
random.4
dir_colors.5
proc.5
glob.7
    Stuart Brady
        s/`/\`/ for backquotes used in command substitution, for
        proper rendering in UTF-8.

Various pages
    mtk, after a note from Stuart Brady
        Using /'x'/ to denote a character (string) renders poorly in
        UTF-8, where the two ' characters render as closing single
        quotes.  On the other hand, using /`x'/ renders nicely on UTF-8,
        where proper opening and closing single quotes are produced by
        groff(1), but looks ugly when rendered in ASCII.  Using the
        sequence /\\aqx\\aq/ produces a reasonable rendering ('\\aq'
        is a vertical "apostrophe quote") in both UTF-8 and ASCII.
        So that change is made in a number of pages.
        See also http://www.cl.cal.ac.uk/~mgk25/ucs/quotes.html.

Various pages
    mtk
        Replace form /`string'/ by /"string"/, since the former renders
        poorly in ASCII.

termios.3
console_codes.4
tty_ioctl.4
termcap.5
charsets.7
    mtk
        Control character names (^X) are written boldface, without
        quotes.

printf.3
scanf.3
proc.5
glob.7
regex.7
    mtk
        Various edits to try and bring some consistency to the use of
        quotes.

Changes to individual pages
---------------------------

tty_ioctl.4
    mtk
        Small rewordings in description of packet mode.

locale.7
    mtk
        Minor formatting fixes.
top
==================== Changes in man-pages-3.01 ====================

Released: 2008-06-25, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andreas Herrmann
Andrew P
Andrew Clayton
Bart Van Assche
Christian Borntraeger
Christoph Hellwig
Daniele Giacomini
Dorin Lazar
George Spelvin
Jason Englander
Jeff Moyer
Laurent Vivier
Masatake YAMOTO
Matt Mackall
Neil Horman
Pavel Machek
Peter Zijlstra
Petr Baudis
Petr Gajdos
Roman Zippel
Sam Varshavchik
Samuel Thibault
Stephane Chazelas
Stuart Cunningham
Thomas Gleixner
Tolga Dalman
Yao Zhao
WANG Cong

Apologies if I missed anyone!

New and rewritten pages
-----------------------

acct.5
    mtk
        A complete rewrite of this page, now with much more detail.

hostname.7
    mtk
        A description of hostname resolution.  Taken from FreeBSD 6.2,
        and lightly edited for man-pages style.

symlink.7
    mtk
        A description of symbolic links.  Taken from FreeBSD 6.2, but
        heavily edited for Linux details, improved readability, and
        man-pages style.

Newly documented interfaces in existing pages
---------------------------------------------

getrlimit.2
    mtk / Peter Zijlstra
        Add description of RLIMIT_RTTIME limit, new in 2.6.25.

mkstemp.3
    mtk
        Add description of mkostemp(), new in glibc 2.7.

core.5
    mtk, after a note by Petr Gajdos; review by Neil Horman
        Document core_pattern pipe syntax, which appeared in
        kernel 2.6.19.
        Add an example program demonstrating use of core_pattern
        pipe syntax.
    mtk
        Document /proc/PID/coredump_filter, new in kernel 2.6.23.
        Documentation was based on the text in
        Documentation/filesystems/proc.txt, plus testing, and
        checking the kernel source.

proc.5
    mtk
        Document /proc/PID/oom_score, which was new in kernel 2.6.11.
        This file displays the "badness" score of the process, which
        provides the basis for OOM-killer decisions.
    mtk
        Document /proc/PID/oom_adj, which was new in kernel 2.6.11.
        This file influences the oom_score of a process.
    mtk
        Document /proc/PID/limits, which was new in 2.6.24.
        This file displays a process's resource limits.
    mtk
        Document /proc/PID/fdinfo/*, which was new in 2.6.22.
        These files display info about each descriptor opened by the
        process: the current file offset, and the file access mode +
        file status flags as set in open() or fcntl(F_SETFL).
    mtk
        Document /proc/PID/mountinfo, which was new in 2.6.26.
        This file displays information about mount points.
        Closely based on text from Documentation/filesystems/proc.txt.
    mtk
        Document /proc/PID/mountstats, which was new in 2.6.17.
        This file displays statistics about mount points.
    mtk
        Document /proc/PID/status.
    Samuel Thibault / mtk, review by Laurent Vivier,
                Christian Borntraeger, and Andrew P
        Document guest (virtual CPU) time field in /proc/stat.
        Document guest (virtual CPU) time fields in /proc/PID/stat.

New links
---------

mkostemp.3
    mtk
        Link to mkstemp.3.

getcwd.2
    mtk
        Link to getcwd.3, which describes several interfaces, among
        them getcwd(), which is in fact a system call.

Global changes
--------------

sched_setaffinity.2
sched_setscheduler.2
set_mempolicy.2
mbind.2
    mtk
        SEE ALSO: Add cpuset(7).

chown.2
faccessat.2
fchmodat.2
fchownat.2
fstatat.2
getxattr.2
link.2
linkat.2
listxattr.2
open.2
readlink.2
removexattr.2
rename.2
setxattr.2
stat.2
symlink.2
symlinkat.2
unlink.2
futimes.3
remove.3
path_resolution.7
    mtk
        SEE ALSO: Add symlink(7).

intro.1
time.1
fcntl.2
gethostbyname.3
ioctl_list.2
    mtk
        Wrap source lines so that new sentence starts on new line.

addseverity.3
backtrace.3
dlopen.3
fmtmsg.3
getnameinfo.3
getpt.3
grantpt.3
makecontext.3
ptsname.3
tcgetsid.3
unlockpt.3
wordexp.3
    mtk
        Added VERSIONS section.

msgctl.2
msgget.2
semget.2
semop.2
pciconfig_read.2
basename.3
cmsg.3
ftok.3
console_ioctl.4
tzfile.5
mq_overview.7
pty.7
    mtk
        For consistency, "fix" cases where argument of .B or .I was
        on the following source line.

adjtimex.2
getrusage.2
io_getevents.2
poll.2
select.2
semop.2
sigwaitinfo.2
aio_suspend.3
clock_getres.3
mq_receive.3
mq_send.3
sem_wait.3
proc.5
    mtk
        SEE ALSO: add time(7)

Typographical or grammatical errors have been corrected in several places.
(Special thanks to Nicolas François and Alain Portal.)

Changes to individual pages
---------------------------

acct.2
    mtk
        Add a few more words to DESCRIPTION.
        NOTES: Add pointer to acct(5).

alarm.2
    Alain Portal
        s/process/calling process/ so as to say that the alarm signal is
        delivered to the calling process.

brk.2
    Yao Zhao / mtk
        Clarify discussion of return value of sbrk().
    mtk
        DESCRIPTION: Add some sentences giving an overview of these
        interfaces.
        Add note recommending use of malloc(3).
        Change name of brk() argument to the simpler 'addr'.
        Add "(void *)" cast to "-1" for error return of sbrk().
        Removed some incorrect text about "brk(0)".
        Note that SUSv2 specified the return value of sbrk().
        Added a detail on the glibc brk() wrapper.
        Remove discussions of old standards (C89 and POSIX.1-1990);
        CONFORMING TO already discusses the situation with respect
        to more recent standards.

chmod.2
    mtk
        Clarify description of chmod() and fchmod().
        Add further detail on S_ISUID, S_ISGID, and S_ISVTX permissions.
        Reformat list of permissions bits.

chown.2
    mtk
        Describe rules governing ownership of new files (bsdgroups
        versus sysvgroups, and the effect of the parent directory's
        set-group-ID permission bit).

chroot.2
    Alain Portal
        Clarify description a little.
        s/changes the root directory/
          changes the root directory of the calling process/

execve.2
    mtk
        Fix text that warns against use of NULL argv and envp.
        Using a NULL envp does in fact seem to be portable (works
        on Solaris and FreeBSD), but the Linux semantics for a NULL
        argv certainly aren't consistent with other implementations.
        See http://bugzilla.kernel.org/show_bug.cgi?id=8408.

getdents.2
    mtk, after a note from George Spelvin
        Document d_type field, present since kernel 2.6.4.
        Other minor edits.

getitimer.2
    mtk
        Noted that POSIX.1 leaves interactions with alarm(), sleep(),
        and usleep() unspecified.
        Linux 2.6.16 removed the MAX_SEC_IN_JIFFIES ceiling on timer
        values.
        Other minor changes.

io_cancel.2
io_destroy.2
io_getevents.2
io_setup.2
io_submit.2
    mtk, after a note by Masatake YAMOTO and input from Jeff Moyer
        Describe the unconventional error return provided by the
        wrapper function in libaio (and contrast with behavior if
        the system call is invoked via syscall(2)).
        See http://thread.gmane.org/gmane.linux.ltp/4445/
    Alain Portal / mtk
        Re-order ERRORS and SEE ALSO entries to be alphabetical.

io_getevents.2
    Alain Portal
        Small wording fix.

io_submit.2
    Jeff Moyer
        s/AIO request blocks/AIO control blocks/

mknod.2
    mtk
        Note that EEXIST applies, even if the pathname is a
        (possibly dangling) symbolic link.

nanosleep.2
    mtk, after a report from Stephane Chazelas
        Remove crufty discussion of HZ, and replace with a pointer
        to time(7).
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=485636
    mtk, after some discussions with Bart Van Assche and Roman Zippel
        NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP
        See also http://thread.gmane.org/gmane.linux.kernel/696854/
        "nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?"
    mtk
        Replace mentions of "process' by "thread".
        NOTES: describe case where clock_nanosleep() can be preferable.
        Some minor rewrites.

open.2
    mtk, after a note from Christoph Hellwig
        NOTES: Note that access mode flags are not single bits,
        and document the Linuxism "access mode 3".
        See also http://thread.gmane.org/gmane.linux.kernel/653123.

readdir.2
    mtk
        Minor wording fixes.

recv.2
    Alain Portal
        Add comment to 'ee_pad' field in structure definition.

sched_setscheduler.2
    mtk
        Add pointer to discussion of RLIMIT_RTTIME in getrlimit.2.
    mtk, after a note by Andrew Clayton
        Rewrote and restructured various parts of the page for greater
        clarity.
    mtk
        Add more detail to the rules that are applied when an
        unprivileged process with a non-zero RLIMIT_RTPRIO limit
        changes policy and priority.
        SEE ALSO: Add Documentation/scheduler/sched-rt-group.txt

sync_file_range.2
    Pavel Machek
        SYNC_FILE_RANGE_WRITE can block on writes greater than request
        queue size.  For some background, see
        http://thread.gmane.org/gmane.linux.kernel/687713/focus=688340

syscalls.2
    mtk
        Added system call history back to version 1.2.
        Fix typo on kernel version for pivot_root().

syslog.2
    WANG Cong
        Document ENOSYS error, which can occur if kernel was built without
        CONFIG_PRINTK.

utime.2
    Nicolas François
        Clarify description of 'times' array for utimes().

adjtime.3
    mtk
        The longstanding bug that if delta was NULL, olddelta
        didn't return the outstanding clock adjustment, is now fixed
        (since glibc 2.8 + kernel 2.6.26).
        http://sourceware.org/bugzilla/show_bug?id=2449
        http://bugzilla.kernel.org/show_bug.cgi?id=6761

dprintf.3
    mtk
        Note that these functions are included in the next POSIX revision.
        Remove editorial discussion about what the functions should have
        been named.

ftime.3
    mtk
        Rewrote various pieces, and added some details.

getaddrinfo.3
    mtk
        Improve description or 'hints' and 'res' arguments.
        Add details on numeric strings that can be specified for 'node'.
        Other fairly major restructurings and rewrites to improve
        logical structure and clarity of the page.
        SEE ALSO: Add hostname(7).

gethostbyname.3
    mtk
        DESCRIPTION: Add reference to inet_addr(3) for dotted notation.
        SEE ALSO: add inet(3).
    mtk
        Added BUGS section noting that gethostbyname() does not
        recognize hexadecimal components in dotted address strings;
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973

getmntent.3
    mtk, after Stuart Cunningham pointed out the typo
        Remove statement that LSB deprecates the functions
        "endmntent(), setmntent() [sic] and setmntent()".
        This doesn't seem to be true (I can't find mention of it
        being deprecated in any of the LSB specs).  Rather, LSB simply
        doesn't specify these functions.  (LSB 1.3 had a spec of
        setmntent(), but not getmntent() or endmntent(), and noted
        that having a spec of setmntent() was of little use without
        also having a spec of getmntent().)
        See also https://lists.linux-foundation.org/pipermail/lsb-discuss/2006-October/003078.html

getnameinfo.3
    Tolga Dalman
        Remove mention of sa_len field from example code.
        That field is a BSDism not present on Linux.
    mtk
        Various minor changes.

inet.3
    mtk / Stephane Chazelas
        inet_aton() is *not* in POSIX.1.
        Rewrote discussion of why inet_addr() is disfavored.
        SEE ALSO: Add getaddrinfo(3).
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482979.
    mtk, after a note by Stephane Chazelas
        Describe the various address forms supported by inet_aton().
    mtk
        Rewrite description of inet_network().
        Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr().
        Add discussion of Classful Addressing, noting that it is obsolete.
        Added an EXAMPLE program.
    mtk
        Relocate discussion of i386 byte order to NOTES.
        Note that inet_aton() returns an address in network byte order.
        SEE ALSO: Add byteorder(3) and getnameinfo(3).

inet_ntop.3
    mtk
        Remove unneeded header files from SYNOPSIS.
        SEE ALSO: Add inet(3) and getnameinfo(3).
        Make NAME line more precise.
        Move errors to an ERRORS section.
        Add EXAMPLE section pointing to inet_pton(3).

inet_pton.3
    mtk / Stephane Chazelas
        Remove statement that inet_pton() extends inet_ntoa();
        that's not really true, since inet_pton() doesn't support
        all of the string forms that are supported by inet_ntoa().
        SEE ALSO: Add getaddrinfo(3).
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482987.
    mtk
        Describe IPv6 address formats.
        Describe dotted decimal format in more detail.
        Add an example program.
    mtk
        Remove unneeded header files from SYNOPSIS.
        Make NAME line more precise.
        Make description of return value more precise.
        SEE ALSO: Add inet(3).

mkfifo.3
    mtk
        Note that EEXIST applies, even if the pathname is a
        (possibly dangling) symbolic link.

mkstemp.3
    mtk
        Fix discussion of O_EXCL flag.
        These functions may also fail for any of the errors described
        in open(2).
        Various other rewordings.

readdir.3
    mtk
        Document DT_LNK (symbolic link) for d_type field.
        Reorder DT_ entries alphabetically.

remainder.3
    mtk
        Recommend against drem(), in favor of remainder().

scanf.3
    mtk, after a note from Stephane Chazelas
        Add an ERRORS section documenting at least some of the errors
        that may occur for scanf().
        See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=487254.
    mtk, after a note from Stephane Chazelas; review by Stephane Chazelas
        Document the GNU 'a' modifier for dynamically allocating strings.
        See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=487254.
        Document the GNU 'm' modifier for dynamically allocating strings.

strcat.3
    Andreas Herrmann
        s/strcat/strncat/ (a typo that changed the semantics in
        DESCRIPTION).

strerror.3
    mtk, after a note from Daniele Giacomini
        Modify SYNOPSIS to show protoypes of both versions of strerror_r(),
        and make other small clarifications of the description regarding
        the two versions.

random.4
    George Spelvin (taking time out from his busy Broadway schedule),
    with some tweaks by Matt Mackall and mtk
        Add a Usage subsection that recommends most users to use
        /dev/urandom, and emphasizes parsimonious usage of
        /dev/random.

locale.5
    Petr Baudis
        LC_TIME: Describe first_weekday and first_workday.

proc.5
    mtk
        The vaious CPU time fields in /proc/stat and /proc/PID/stat
        return time in clock ticks (USER_HZ, cputime_to_clock_t(),
        sysconf(_SC_CLK_TCK)).
        Updated, clarified and expanded the description several
        fields in /proc/[number]/stat.
    mtk
        Clarified and expanded the description of /proc/[number]/fd.
    mtk
        Updated and clarified the description of /proc/[number]/statm.
    mtk
        Updated and clarified the description of /proc/sys/fs/dentry-state.
    mtk
        Many formatting, wording, and grammar fixes.

man-pages.7
    mtk
        Enhanced description of VERSIONS section.

mq_overview.7
    mtk
        Note that Linux does not currently support ACLs for POSIX
        message queues.

sem_overview.7
    mtk
        Note that Linux supports ACLs on POSIX named semaphores
        since 2.6.19.

time.7
    mtk, with some suggestions from Bart Van Assche and Thomas Gleixner
        Added some details about where jiffies come into play.
        Added section on high-resolution timers.
        Mentioned a few other time-related interfaces at various
        points in the page.
        See http://thread.gmane.org/gmane.linux.kernel/697378.

unix.7
    mtk, after a note by Samuel Thibault
        Provide a clear description of the three types of address that
        can appear in the sockaddr_un structure: pathname, unnamed,
        and abstract.
top
==================== Changes in man-pages-3.02 ====================

Released: 2008-07-02, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andries Brouwer
Reuben Thomas
Sam Varshavchik
Stephane Chazelas
WANG Cong

Apologies if I missed anyone!

New and rewritten pages
-----------------------

clock_nanosleep.2
    mtk
        A description of the clock_nanosleep() system call,
        which was added in kernel 2.6.

getgrouplist.3
    mtk
        A near complete rewrite, including additional information and
        a new example program.

getutmp.3
    mtk
        Documents getutmp(3) and getutmpx(3).

gnu_get_libc_version.3
    mtk
        Documents gnu_get_libc_version(3) and gnu_get_libc_release(3).

sigwait.3
    mtk
        Documents sigwait(3).

shm_overview.7
    mtk
        An overview of the POSIX shared memory API.

Newly documented interfaces in existing pages
---------------------------------------------

updwtmp.3
    mtk
        Document updwtmpx(3).

New links
---------

getutmpx.3
    mtk
        Link to getutmp.3.

gnu_get_libc_release.3
    mtk
        Link to gnu_get_libc_version.3

updwtmpx.3
    mtk
        Link to updwtmp.3

utmpxname.3
    mtk
        Link to getutent.3.

utmpx.5
    mtk
        Link to utmp.5.

Global changes
--------------

Various pages
    mtk
        s/user name/username/

Various pages
    mtk
        s/host name/hostname/

Changes to individual pages
---------------------------

fchmodat.2
    Alain Portal
        SEE ALSO: add symlink.7.  (3.01 changelog wrongly said this
        had been done.)

io_setup.2
    Alain Portal
        Remove superfluous text from RETURN VALUE.

mmap.2
    mtk
        SEE ALSO: Add mmap(2), shm_overview(7).

shmget.2
shmop.2
    mtk
        SEE ALSO: add shm_overview(7).

sigreturn.2
    mtk
        Added a bit more detail on what sigreturn() actually does.

signalfd.2
sigsuspend.2
    mtk
        SEE ALSO: Add sigwait(3).

sigwaitinfo.2
    mtk
        Describe behavior when multiple threads are blocked in
        sigwaitinfo()/sigtimedwait().
        SEE ALSO: Add sigwait(3).

dirfd.3
    mtk
        RETURN VALUE: describe return value on success.
        Add an ERRORS section documenting POSIX.1-specified errors.

getaddrinfo.3
    mtk, after a note by Stephane Chazelas
        getaddrinfo() supports specifying IPv6 scope-IDs.

getlogin.3
    mtk
        ERRORS: add ENOTTY.
        SEE ALSO: add utmp(5).

getutent.3
    WANG Cong
        utmpname() does return a value.
    mtk
        Add paragraph to start of DESCRIPTION recommending
        use of POSIX.1 "utmpx" functions.
        CONFORMING TO: mention utmpxname().
        Add an ERRORS section.
        There are no utmpx equivalents of the _r reentrant functions.
        Clarify discussion of return values.
        Add pointer to definition of utmp structure in utmp(5).
        Clarify discussion of utmpx file on other systems (versus
        Linux situation).

getutent.3
    mtk
        SEE ALSO: add getutmp(3)

inet_pton.3
    Stephane Chazelas
        Fix error in description of IPv6 presentation format:
        s/x.x.x.x.x.x.x.x/x:x:x:x:x:x:x:x/.

setbuf.3
    Reuben Thomas / mtk
        Fix confused wording for return value of setvbuf().
        Fixes http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=488104.
    mtk
        Other minor rewordings.

shm_open.3
    mtk
        SEE ALSO: add shm_overview(7).

random.4
    mtk, after a note by Alain Portal
        Slight rewording to make life easier for non-native English
        speakers.

utmp.5
    mtk
        Add discussion of POSIX.1 utmpx specification.
        Provide a little more detail on fields of utmp structure.
        Added comments to macros for ut_type field.
        Correct the description of the ut_id field.
    mtk
        Consolidate duplicated information about ut_tv and ut_session
        on biarch platforms.
    mtk
        Move some text from CONFORMING TO to NOTES.
        Removed some crufty text.
        SEE ALSO: add login(3), logout(3), logwtmp(3).
        UT_LINESIZE is 32 (not 12).
    mtk
        SEE ALSO: add getutmp(3)

man-pages.7
    mtk
        Enhanced the discussion of font conventions.

signal.7
    mtk
        Note that the delivery order of multiple pending standard
        signals is unspecified.
        SEE ALSO: Add sigwait(3).
top
==================== Changes in man-pages-3.03 ====================

Released: 2008-07-08, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andi Kleen
Hidetoshi Seto
Li Zefan
Paul Jackson
Sam Varshavchik

Apologies if I missed anyone!

New and rewritten pages
-----------------------

getcpu.2
    Andi Kleen, with some text and edits by mtk
        Documents the getcpu(2) system call, introduced in Linux 2.6.19.

sched_getcpu.3
    mtk
        Documents sched_getcpu(3), a wrapper for getcpu(2), provided
        since glibc 2.6.

cpuset.7
    Paul Jackson, with review and editing by mtk, and comments by
    Hidetoshi Seto and Li Zefan
        A description of the cpuset file system, the mechanism introduced
        kernel 2.6.12 for confining processes to designated processors
        and nodes.  (Becomes the fourth largest page in man-pages!)

Newly documented interfaces in existing pages
---------------------------------------------

readdir.3
    mtk
        Add documentation of readdir_r().

New links
---------

updwtmpx.3
    Alain Portal
        Link to updwtmp.3 (3.02 changelog wrongly said this had been done).

readdir_r.3
    mtk
        Link to readdir.3.

Global changes
--------------

get_mempolicy.2
mbind.2
sched_setaffinity.2
set_mempolicy.2
    mtk
        SEE ALSO: Add getcpu(2).

accept.2
close.2
connect.2
dup.2
epoll_wait.2
fcntl.2
flock.2
futex.2
msgop.2
poll.2
read.2
recv.2
select.2
semop.2
send.2
sigwaitinfo.2
spu_run.2
wait.2
write.2
aio_suspend.3
mq_receive.3
mq_send.3
scanf.3
sem_wait.3
usleep.3
inotify.7
    mtk
        ERRORS: Added reference to signal(7) in discussion of EINTR.

Various pages
    mtk
        Wrapped very long source lines.

Changes to individual pages
---------------------------

accept.2
    mtk
        Small wording change.

io_getevents.2
    mtk
        ERRORS: Add EINTR error.

open.2
    mtk
        ERRORS: Add EINTR error.

sigaction.2
    mtk
        Note circumstances in which each SA_* flag is meaningful.
    mtk
        Describe POSIX specification, and Linux semantics for
        SA_NOCLDWAIT when establishing a handler for SIGCHLD.
    mtk
        Add pointer under SA_RESTART to new text in signal(7)
        describing system call restarting.
    mtk
        Other minor edits.

truncate.2
    mtk
        ERRORS: Added EINTR error.
        A few minor rewordings.

wait.2
    mtk
        Remove statement that WUNTRACED and WCONTINUED only have effect
        if SA_NOCLDSTOP has not been set for SIGCHLD.  That's not true.

errno.3
    mtk
        Add a pointer to signal(7) for further explanation of EINTR.

getgrouplist.3
    mtk
        SEE ALSO: Add passwd(5).

readdir.3
    mtk
        Remove <sys/types.h> from SYNOPSIS; POSIX.1-2001 does not
        require it.
        Some minor rewordings.

sleep.3
    mtk
        RETURN VALUE: explicitly mention interruption by signal handler.
        SEE ALSO: add signal(7).

usleep.3
    mtk
        POSIX.1-2001 also only documents EINVAL.

group.5
    mtk
        SEE ALSO: Add getgrent(3), getgrnam(3).

passwd.5
    mtk
        SEE ALSO: Add getpwent(3), getpwnam(3).

proc.5
    mtk
        Add pointer to description of /proc/PID/cpuset in cpuset(7).

signal.7
    mtk
        Add a section describing system call restarting, and noting
        which system calls are affected by SA_RESTART, and which
        system calls are never restarted.
    mtk
        Describe the aberrant Linux behavior whereby a stop signal
        plus SIGCONT can interrupt some system calls, even if no
        signal handler has been established, and note the system
        calls that behave this way.
    mtk
        Note a few more architectures on which signal numbers are valid.
        SEE ALSO: added a number of pages.
    mtk
        Update async-signal-safe function list for POSIX.1-2004 (which
        adds sockatmark()).
top
==================== Changes in man-pages-3.04 ====================

Released: 2008-07-15, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andrea Arcangeli
Andreas Mohr
Andrew Morgan
Erik Bosman
John Brooks
Nikanth Karthikesan
Pavel Heimlich
Petr Gajdos
Sam Varshavchik
Serge Hallyn
Sripathi Kodi
Vincent Lefevre

Apologies if I missed anyone!

Web site
--------

licenses.html
    mtk
        A page describing the preferred licenses for new pages that
        are contributed to man-pages.

New and rewritten pages
-----------------------

utimensat.2
    mtk
        New page documenting the utimensat() system call, new in 2.6.22,
        and futimens() library function.

end.3
    mtk
        Documents etext, edata, and end symbols.

Newly documented interfaces in existing pages
---------------------------------------------

memchr.3
    mtk
        Add description of rawmemchr().

proc.5
    mtk
        Document /proc/config.gz (new in kernel 2.6).
    mtk, based on text from Documentation/vm/sysctl.txt
        Document /proc/sys/vm/oom_kill_allocating_task
        (new in Linux 2.6.24).
        Document /proc/sys/vm/oom_dump_tasks
        (new in Linux 2.6.25).
        Document /proc/sys/vm/panic_on_oom
        (new in Linux 2.6.18).

New links
---------

edata.3
etext.3
    mtk
        Links to end.3.

futimens.3
    mtk
        Link to new utimensat.2.

getdate_err.3
    mtk
        Link to getdate.3.

h_errno.3
    mtk
        Link to gethostbyname.3.

optarg.3
opterr.3
optind.3
optopt.3
    mtk
        Links to getopt.3.

rawmemchr.3
    mtk
        Link to memchr.3.

sys_errlist.3
sys_nerr.3
    mtk
        Links to perror.3.

Global changes
--------------

Various pages
    mtk
        s/parameter/argument/ when talking about the things given
        to a function call, for consistency with majority usage.

Various pages
    mtk
        s/UNIX/Unix/, when not used as part of a trademark,
        for consistency with majority usage in pages.

Various pages
    mtk, after a note from Alain Portal
        Put SEE ALSO entries into alphabetical order.

Various pages
    mtk
        Remove period at end of SEE ALSO list.

Various pages
    mtk, after a note by Alain Portal
        Even when the CONFORMING TO section is just a list of standards,
        they should be terminated by a period.

getpriority.2
MB_LEN_MAX.3
MB_CUR_MAX.3
fwide.3
mblen.3
rtime.3
st.4
proc.5
bootparam.7
man-pages.7
utf-8.7
tcp.5
    mtk / Alain Portal
        Small wording fixes -- express <=, <, >=, > in words when in
        running text.

sched_setparam.2
sched_setscheduler.2
getgrent_r.3
hash.3
    mtk
        Minor rewording w.r.t. use of the term "parameter".

Typographical or grammatical errors have been corrected in several
other places.  (Many, many thanks to Alain Portal!)

Changes to individual pages
---------------------------

capget.2
    Andrew Morgan
        Update in line with addition of file capabilities and
        64-bit capability sets in kernel 2.6.2[45].

clock_nanosleep.2
    mtk
        Add "Link with -lrt" to SYNOPSIS.

getrusage.2
    Sripathi Kodi
        Document RUSAGE_THREAD, new in 2.6.26.
    mtk
        Improve description of RUSAGE_CHILDREN.
        Add pointer to /proc/PID/stat in proc(5).
        Other minor clean-ups.

ioprio_set.2
    Nikanth Karthikesan
        Since Linux 2.6.25, CAP_SYS_ADMIN is longer required to set
        a low priority (IOPRIO_CLASS_IDLE).

mount.2
    mtk
        Since Linux 2.6.26, MS_RDONLY honors bind mounts.

openat.2
    mtk
        SEE ALSO: add utimensat(3).

prctl.2
    Serge Hallyn, with some edits/input from mtk
        Document PR_CAPBSET_READ and PR_CAPBSET_DROP.
    Erik Bosman
        Document PR_GET_TSC and PR_SET_TSC.
    mtk, reviewed by Andrea Arcangeli
        Document PR_SET_SECCOMP and PR_GET_SECCOMP.
    mtk
        PR_SET_KEEPCAPS and PR_GET_KEEPCAPS operate on a per-thread
        setting, not a per-process setting.
    mtk
        Clarify fork(2) details for PR_SET_PDEATHSIG.
    mtk
        Add description of PR_SET_SECUREBITS and PR_GET_SECUREBITS,
        as well as pointer to further info in capabilities(7).
    mtk
        PR_GET_ENDIAN returns endianness info in location pointed to by
        arg2 (not as function result, as was implied by previous text).
    mtk
        Expand description of PR_SET_NAME and PR_GET_NAME.
    mtk
        RETURN VALUE: bring up to date for various options.
    mtk
        Various improvements in ERRORS.
    mtk
        Note that PR_SET_TIMING setting of PR_TIMING_TIMESTAMP is not
        currently implemented.
    mtk
        Minor changes:
        * Clarify wording for PR_GET_UNALIGN, PR_GET_FPEMU, and
          PR_GET_FPEXC.
        * Some reformatting of kernel version information.
        * Reorder PR_GET_ENDIAN and PR_SET_ENDIAN entries.

readlinkat.2
    John Brooks / mtk
         Fix and reword erroneous RETURN VALUE text.

recv.2
    mtk
        Noted which flags appeared in Linux 2.2.

sched_setaffinity.2
    mtk, after a Fedora downstream patch
        Update type used for cpusetsize argument in SYNOPSIS.

select.2
    Andreas Mohr / mtk
        Clarify "zero timeout" case.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=490868.

send.2
    mtk
        Noted which flags appeared in Linux 2.2.

sigaction.2
    mtk
        Document si_overrun and si_tid fields of siginfo structure.
        Add some text for si_trapno field.
        The si_errno field is *generally* unused.
    mtk
        Put descriptions of SA_* constants in alphabetical order.

signal.2
    mtk
        Rewrote and expanded portability discussion.
        NOTES: Show the raw prototype of signal() (without use of
        sighandler_t).

signalfd.2
    mtk
        Modify description of ssi_trapno field.

swapon.2
    mtk
        Fix two version number typos for MAX_SWAPFILES discussion:
        s/2.6.10/2.4.10/

utime.2
    mtk
         SEE ALSO: add utimensat(2), futimens(3).

dl_iterate_phdr.3
    Alain Portal
        SEE ALSO: Add elf(5).

crypt.3
    mtk, after a Fedora downstream patch
        Describe additional encryption algorithms.
    See also: https://bugzilla.redhat.com/show_bug.cgi?id=428280.

errno.3
    mtk
        Small rewrites in DESCRIPTION.

exec.3
    mtk, after a note from Alain Portal
        Small rewording.

exp10.3
    Alain Portal
        SEE ALSO: Add log10(3).

exp2.3
    Alain Portal
        Add C99 to CONFORMING TO.

fgetgrent.3
    Alain Portal
        Add references to group(5).
    mtk
        Minor rewordings.
        SEE ALSO: add fopen(3).

fgetpwent.3
    Alain Portal
        Add reference to passwd(5).
    mtk
        Minor rewordings.
        SEE ALSO: add fopen(3).

frexp.3
    Alain Portal
        Add C99 to CONFORMING TO.

futimes.3
    mtk
         SEE ALSO: remove futimesat(2); add utimensat(2).

getopt.3
    mtk
        Add details on initial value of optind, and note that it can
        be reset (to 1) to restart scanning of an argument vector.
        Add a NOTES section describing the glibc-specific behavior
        when optind is reset to 0 (rather than 1).
        See http://groups.google.com/group/comp.unix.programmer/browse_thread/thread/be0d0b7a07a165fb
    mtk
        Note glibc extensions under CONFORMING TO.

getspnam.3
    mtk
        Improve comments on struct spwd.

getpw.3
    Alain Portal
        RETURN VALUE: note that errno is set on error.
    mtk
        Add EINVAL error.

insque.3
    mtk / Alain Portal
        Minor rewordings.

log.3
    Alain Portal
        Remove unnecessary sentence in ERRORS.

log10.3
    mtk
        SEE ALSO: Add exp10(3).

offsetof.3
    Alain Portal
        Small wording improvement.

pow.3
    Alain Portal
        Remove unnecessary sentence in ERRORS.

printf.3
    mtk / Alain Portal
        Many small formatting fixes.

proc.5
    mtk
        Remove redundant summary list of files in description of
        /proc/sys/kernel.
        Make kernel version for /proc/sys/kernel/panic_on_oops more precise.
        Make kernel version for /proc/sys/kernel/pid_max more precise.
        Add Documentation/sysctl/vm.txt to SEE ALSO.
        Other minor edits.

profil.3
    mtk / Alain Portal
         Small wording improvement.

rtime.3
    mtk, after a note by Alain Portal
        Clarify meaning of midnight on 1 Jan 1900/1970.
    mtk
        Remove netdate(1) and rdate(1) from SEE ALSO, since these pages
        don't seem to exist on Linux systems.

scanf.3
    Vincent Lefevre / mtk
        Clarify treatment of initial white space by %% conversion
        specification.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435648.
    mtk
        Many small formatting fixes.

stdin.3
    Alain Portal
        Rename CONSIDERATIONS section to NOTES, and relocate
        to appropriate place on page.

tmpfile.3
    mtk, after a note by Alain Portal
        Prepend "POSIX.1-2001 specifies that: " to the sentence stating
        that tmpfile() may write to stdout.  (AFAICS, glibc's tmpfile()
        does not do this.)

ttyname.3
    Alain Portal
        Remove unnecessary sentence in ERRORS.

wcsdup.3
    Alain Portal
        Make wording more precise: the memory allocated by wcsdup(3)
        *should* be freed with free(3).

wordexp.3
    Alain Portal / mtk
        Move example into proper EXAMPLE section.

tty_ioctl.4
    mtk / Petr Gajdos
        The features in the "Get and Set Window Size" subsection
        require the inclusion of <sys/ioctl.h>.

capabilities.7
    Serge Hallyn, plus a bit of work by mtk
        Document file capabilities, per-process capability bounding set,
        changed semantics for CAP_SETPCAP, and other changes in 2.6.2[45].
        Add CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP.
        Various smaller fixes.
    mtk, plus review by Serge Hallyn and Andrew Morgan
        Add text detailing how CAP_SETPCAP (theoretically) permits -- on
        pre-2.6.25 kernels, and 2.6.25 and later kernels with file
        capabilities disabled -- a thread to change the capability sets
        of another thread.
        Add section describing rules for programmatically adjusting
        thread capability sets.
        Add some words describing purpose of inheritable set.
        Note existence of CONFIG_SECURITY_CAPABILITIES config option.
        Describe rationale for capability bounding set.
        Document securebits flags (new in 2.6.26).
        Remove obsolete BUGS section.
        SEE ALSO: Add getcap(8), setcap(8), and various libcap pages.
    mtk
        Add text noting that if we set the effective flag for one
        file capability, then we must also set the effective flag for all
        other capabilities where the permitted or inheritable bit is set.
    mtk
        Since Linux 2.6.25, CAP_SYS_ADMIN is no longer required for
        ioprio_set() to set IOPRIO_CLASS_IDLE class.
    mtk
        Reword discussion of CAP_LINUX_IMMUTABLE to be file-system neutral.

man-pages.7
   mtk
       A list of standards in the CONFORMING TO list should be
       terminated by a period.
       The list of pages in a SEE ALSO list should not be
       terminated by a period.

tcp.7
    mtk
        Correct a detail for sysctl_tcp_adv_win_scale.
        Formatting fixes.
top
==================== Changes in man-pages-3.05 ====================

Released: 2008-07-23, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andries Brouwer
Brian M. Carlson
Fabian Kreutz
Franck Jousseaume
Sam Varshavchik
Uli Schlacter

Apologies if I missed anyone!

New and rewritten pages
-----------------------

matherr.3
    mtk, with review by Andries Brouwer
        A description of the SVID-specified mechanism for reporting
        math exceptions.
        See http://thread.gmane.org/gmane.linux.man/266.

math_error.7
    mtk, with review and suggested input from Andries Brouwer
        A description of how math functions report errors.
        See http://thread.gmane.org/gmane.linux.man/249.

Global changes
--------------

Various pages
    mtk
        s/floating point/floating-point/ when used attributively.

Various pages
    mtk
        For consistency with majority usage:
        s/plus infinity/positive infinity/
        s/minus infinity/negative infinity/

Typographical or grammatical errors have been corrected in several
other places.

Changes to individual pages
---------------------------

brk.2
    mtk
        SEE ALSO: add end(3).

open.2
    Brian M. Carlson / mtk
        Remove ambiguity in description of support for O_EXCL on NFS.
        As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=491791.

prctl.2
    mtk
        Place options in some semblance of alphabetical order.
        (No content or formatting changes were made.)

cerf.3
    mtk
        Bump version number: these functions are still missing in
        glibc 2.8.

fenv.3
    mtk
        SEE ALSO: Add math_error(7).

INFINITY.3
    mtk
        SEE ALSO: Add math_error(7).

nan.3
    mtk
        Remove unneeded "Compile with" piece in SYNOPSIS.
        SEE ALSO: Add math_error(7).

rpc.3
    mtk / Franck Jousseaume
        Fix errors introduced into a few prototypes when converting
        function declarations to use modern C prototypes in man-pages-2.75.

ipv6.7
    mtk, after a report from Uli Schlacter
        Document the IPV6_V6ONLY flag.
top
==================== Changes in man-pages-3.06 ====================

Released: 2008-08-05, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andreas Jaeger
Andries Brouwer
Fabian Kreutz
Gernot Tenchio
Sam Varshavchik
Tolga Dalman

Apologies if I missed anyone!

New and rewritten pages
-----------------------

erfc.3
    mtk
        Created after removing the erfc() material from erf.3.
        Documents the complementary error function.

y0.3
    mtk
        Created after removing the y*() material from j0.3.
        Documents the Bessel functions of the second kind.
        Included ERRORS section; noted that an exception is not
        raised on underflow, see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6806;
        and errno is not set on overflow, see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808;
        Included BUGS section noting that errno is incorrectly
        set for pole error; see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6807.

scalbln.3
    mtk
        Created after removing the scalbln*() and scalbn*() material
        from scalb.3.  Documents scalbln() and scalbn() functions.
        Included ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6803.

New and changed links
---------------------

erfcf.3
erfcl.3
    mtk
        Changed these links to point to new erfc.3 page.

scalblnf.3
scalblnl.3
scalbn.3
scalbnf.3
scalbnl.3
    mtk
        Changed these links to point to new scalbln.3 page.

y0f.3
y0l.3
y1.3
y1f.3
y1l.3
yn.3
ynf.3
ynl.3
    mtk
        Changed these links to point to new y0.3 page.

Global changes
--------------

Various pages
    mtk
        s/floating point/floating-point/ when used attributively.

Typographical or grammatical errors have been corrected in several
other places.

Changes to individual pages
---------------------------

crypt.3
    mtk
        Tweak discuss text describing support for Blowfish.

ctime.3
    mtk / Gernot Tenchio
        Added some words to make clear that the string returned by
        ctime() and asctime() is null-terminated.

math_error.7
    Sam Varshavchik
        Reverse order of SYNOPSIS and NAME sections.
    mtk
        NOTES: Summarize the state of glibc support for exceptions
        and errno for error reporting.

Changes to individual pages (math functions)
--------------------------------------------

Almost all of the changes in this release relate to math man pages.
Very many changes were made to the math pages, including:

* Fixed feature test macros (FTMs).  Often, the FTM requirements
  for the "float" and "long double" versions of a math function are
  different from the requirements for the "double" version.  Each math
  page now shows the correct FTM requirements for all three versions
  of the function(s) it describes.  This may have required either
  a change to the existing FTM text (if the requirements for the
  "double" function were already described), or the addition of an FTM
  description to a SYNOPSIS where one was not previously present
  (typically because the "double" version of the function does not
  require any FTMs to be defined).
* CONFORMING TO: in many cases, POSIX.1-2001 was not mentioned.
  Where a function is specified in POSIX.1-2001, this is now noted.
  Also, statements about what other standards a function conforms to
  were generally clarified.  (The wording about which functions conformed
  to C99 was previously often done as an add on sentence; now it is made
  part of the first sentence of the CONFORMING TO section, along with
  POSIX.1-2001.)
* RETURN VALUE: in many cases, pages lacked descriptions of the return
  value when the function arguments are special values such as +0, -0,
  NaN (not-a-number), +infinity, -infinity, etc.  This has been fixed.
  I carried out tests on glibc 2.8 to ensure that all of these
  functions match the RETURN VALUE descriptions (and the POSIX.1-2001
  requirements).
* ERRORS: many pages lacked a clear (or indeed any) description of
  how errno is set on error and what exception is raised for each error.
  This has been fixed.  The ERRORS sections are now generally headed up
  as per the POSIX.1 way of doing things, describing Pole / Range /
  Domain errors, as applicable.
  I carried out tests on glibc 2.8 to ensure that all of these
  functions match the ERRORS descriptions.  Deviations from POSIX.1-2001
  requirements have been filed as glibc bug reports, and noted in the
  man pages.  (The pages now describe the situation for ERRORS as at glibc
  2.8; I may eventually try and extend the text with descriptions of
  changes in older versions of glibc.)
  NOTE: one point that has not been covered in any page is the
  circumstances that generate inexact (FE_INEXACT) exceptions.
  (The details for these exceptions are not specified in POSIX.1-2001,
  and I haven't gone looking for the standards that describe the details.)

acos.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

acosh.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

asin.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

asinh.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Some rewording.
        RETURN VALUE: Added details for special argument cases.
        Added (null) ERRORS section.
        Updated CONFORMING TO.

atan.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Some rewording.
        RETURN VALUE: Added details for special argument cases.
        Added (null) ERRORS section.
        Updated CONFORMING TO.

atan2.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Some rewording.
        RETURN VALUE: Added details for special argument cases.
        Added (null) ERRORS section.
        Updated CONFORMING TO.

atanh.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.
        Added BUGS section noting that pole error sets errno to EDOM,
        when it should be ERANGE instead; see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6759.

cbrt.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE section.
        Added (null) ERRORS section.
        Updated CONFORMING TO.

ceil.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Enhanced.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section.
        Updated CONFORMING TO.
        NOTES: Added some details.

copysign.3
    mtk
        Added RETURN VALUE section.
        Updated CONFORMING TO.

cos.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Rewrote RETURN VALUE section.
        Added ERRORS section; noted errno is not set:
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6780.
        Updated CONFORMING TO.

cosh.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section.
        Updated CONFORMING TO.

erf.3
    mtk
        Removed the erfc() material (there is now a new erfc page).
        Reason: the functions are logically separate; also their
        return values differ, and it would have been confusing
        to document them on the same page.
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6785.
        Updated CONFORMING TO.

exp.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6786.
        Updated CONFORMING TO.

exp10.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set for underflow;
        see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6787.

exp2.3
    mtk
        Added RETURN VALUE and ERRORS sections.
        Updated CONFORMING TO.

expm1.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set for overflow;
        see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6788.
        Updated CONFORMING TO.
        Added BUGS section, describing bogus underflow exception for -large,
        see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6778;
        and describing bogus invalid exception for certain +large,
        see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6814.

fabs.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Updated CONFORMING TO.

fdim.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Some rewording.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6796.
        Updated CONFORMING TO.

fenv.3
    mtk
        Make style of writing exception names consistent with other
        pages and POSIX.1-2001.
        Updated CONFORMING TO.

finite.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.

floor.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Enhanced.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

fma.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        DESCRIPTION: Some rewording.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801.
        Updated CONFORMING TO.

fmax.3
fmin.3
    mtk
        NAME: Make description clearer
        SYNOPSIS: Added feature test macro requirements.
        SYNOPSIS: Remove unneeded "Compile with" piece.
        CONFORMING TO: Added POSIX.1-2001.
        Added RETURN VALUE and ERRORS sections.

fmod.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section; noted that errno is not always set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783.
        Updated CONFORMING TO.

fpclassify.3
    mtk
        Minor wording changes.
        CONFORMING TO: Added POSIX.1-2001.
        SEE ALSO: Add signbit(3).

frexp.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added details to RETURN VALUE section.
        Added (null) ERRORS section.
        CONFORMING TO: Added POSIX.1-2001.

gamma.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        Added (null) RETURN VALUE section referring to tgamma(3).
        Added (null) ERRORS section referring to tgamma(3).
        CONFORMING TO: Rewrote.

hypot.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        DESCRIPTION: note that calculation is done without causing
        undue overflow or underflow.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not always set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6795.
        Updated CONFORMING TO.

ilogb.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Rewrote RETURN VALUE section.
        Rewrote ERRORS section; noted that errno is not set, and in some
        cases an exception is not raised; see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6794.
        CONFORMING TO: Added POSIX.1-2001.

isgreater.3
    mtk
        NAME: Make description clearer
        Improve the description of isunordered().
        Added RETURN VALUE and ERRORS sections.
        Formatting fixes.
        A few wording improvements.

j0.3
    mtk
        Removed material for the y*() functions to a separate y0.3 page.
        Reason: the return values and errors/exceptions differ, and it
        would have been confusing to document them on the same page.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6805.

ldexp.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE and ERRORS sections.
        Updated CONFORMING TO.

lgamma.3
    mtk
        Note that these functions are deprecated.
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE and ERRORS sections referring to lgamma(3).
        Added BUGS section noting that pole error sets errno to EDOM,
        when it should be ERANGE instead; see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6777.

log.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

log10.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

log1p.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6792.
        Updated CONFORMING TO.

log2.3
    mtk
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

logb.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        DESCRIPTION: added a little detail; some rewordings.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6793.
        CONFORMING TO: Added POSIX.1-2001.

lrint.3
    mtk
        DESCRIPTION: some rewording.
        RETURN VALUE: Added details for special argument cases.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6798.
        CONFORMING TO: Added POSIX.1-2001.

lround.3
    mtk
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6797.
        CONFORMING TO: Added POSIX.1-2001.

modf.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        RETURN VALUE: Added details for special argument cases.
        Added (null) ERRORS section.
        CONFORMING TO: Added POSIX.1-2001.

nan.3
    mtk
        Small wording changes.
        CONFORMING TO: Added POSIX.1-2001.

nextafter.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        RETURN VALUE: Added details for special argument cases.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799.
        CONFORMING TO: Added POSIX.1-2001.

pow.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.
        Added BUGS section noting that pole error sets errno to EDOM,
        when it should be ERANGE instead; see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776.

remainder.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        DESCRIPTION: added some details.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section; noted that errno is not always set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783.
        Updated CONFORMING TO.
        Added BUGS section noting that remainder(nan(""), 0)
        wrongly causes a domain error; see
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779

remquo.3
   mtk
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801.
        Updated CONFORMING TO.

fmax.3
fmin.3
    mtk
        NAME: Make description clearer
        SYNOPSIS: Added feature test macro requirements.
        SYNOPSIS: Remove unneeded "Compile with" piece.
        CONFORMING TO: Added POSIX.1-2001.
        Added RETURN VALUE and ERRORS sections.

fmod.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        RETURN VALUE: Added details for special argument cases.
        Rewrote ERRORS section; noted that errno is not always set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783.
        Updated CONFORMING TO.

fpclassify.3
        CONFORMING TO: Added POSIX.1-2001.

rint.3
    mtk
        SYNOPSIS: Fixed feature test macro requirements.
        DESCRIPTION: added some details.
        RETURN VALUE: Added details for special argument cases.
        ERRORS: no errors can occur (previous text was misleading).
        CONFORMING TO: Added POSIX.1-2001.
        NOTES: point out that lrint() may be preferred in some cases.

round.3
    mtk
        DESCRIPTION: added some details.
        RETURN VALUE: Added details for special argument cases.
        ERRORS: no errors can occur (previous text was misleading).
        CONFORMING TO: Added POSIX.1-2001.
        NOTES: point out that lround() may be preferred in some cases.

scalb.3
    mtk
        Removed the scalbn() and scalbln() material to a separate
        scalbln.3 page.  Reason: scalb() is obsolete; also the
        exception/error conditions differ somewhat, so that it
        would have been confusing to document them on the same page.
        SYNOPSIS: Fixed feature test macro requirements.
        DESCRIPTION: some rewrites and added details.
        Added RETURN VALUE section.
        Added ERRORS section; noted that errno is not set; see
        also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6803
        and http://sources.redhat.com/bugzilla/show_bug.cgi?id=6804.
        CONFORMING TO: Rewrote.

signbit.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        SYNOPSIS: Remove unneeded "Compile with" piece.
        Added RETURN VALUE section.
        Added (null) ERRORS section.
        CONFORMING TO: Added POSIX.1-2001.

sin.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section; noted errno is not set:
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6781.
        Updated CONFORMING TO.

sincos.3
    mtk
        DESCRIPTION: Added details for special argument cases.
        Added (null) RETURN VALUE section.
        Added ERRORS section.

sinh.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section.
        Updated CONFORMING TO.

sqrt.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Rewrote ERRORS section.
        Updated CONFORMING TO.

tan.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added ERRORS section.
        Added ERRORS section; noted errno is not set:
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6782.
        Updated CONFORMING TO.

tanh.3
    mtk
        SYNOPSIS: Added feature test macro requirements.
        Added RETURN VALUE section.
        Added (null) ERRORS section.
        Updated CONFORMING TO.

tgamma.3
    mtk
        Added RETURN VALUE section.
        Rewrote ERRORS section; noted that errno is not set /
        incorrectly set in some cases; see also
        http://sources.redhat.com/bugzilla/show_bug.cgi?id=6809
        and http://sources.redhat.com/bugzilla/show_bug.cgi?id=6810.
        CONFORMING TO: Added POSIX.1-2001.
        Added NOTES section to hold text explaining origin of tgamma().

trunc.3
    mtk
        RETURN VALUE: small rewording.
        CONFORMING TO: Added POSIX.1-2001.
        Added NOTES section explaining that result may be too large
        to store in an integer type.
top
==================== Changes in man-pages-3.07 ====================

Released: 2008-08-12, Konolfingen

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alain Portal
Andries Brouwer
Christoph Lameter
Cliff Wickman
Fabian Kreutz
Filippo Santovito
Gerrit Renker
Heikki Orsila
Khalil GHORBAL
Lee Schermerhorn
Maxin John
Reuben Thomas
Samuel Thibault
Sam Varshavchik
Soh Kam Yung
Stephane Chazelas
Pavel Heimlich
Reuben Thomas

Apologies if I missed anyone!

New and rewritten pages
-----------------------

move_pages.2
    Christoph Lameter, various edits and improvements by mtk
        Documentation of the move_pages() system call.
        This page was formerly part of the numactl package, but really
        belongs in man-pages (since it describes a kernel interface).

clock_getcpuclockid.3
    mtk
        New page documenting the clock_getcpuclockid() library function,
        available since glibc 2.2.

udplite.7
    Gerrit Renker
        Document the Linux implementation of the UDP-Lite protocol,
        new in Linux 2.6.20.

Newly documented interfaces in existing pages
---------------------------------------------

proc.5
    Christoph Lameter, minor edits and improvements by mtk
        Documentation of the /proc/PID/numa_maps file.
        This material was formerly the numa_maps.5 page in the numactl
        package, but really belongs in man-pages (since it describes
        a kernel interface).

Global changes
--------------

nanosleep.2
inet_ntop.3
inet_pton.3
scanf.3
initrd.4
    mtk
        Fix mis-ordered (.SH) sections.

connect.2
socket.2
rtnetlink.3
arp.7
ddp.7
ip.7
ipv6.7
netlink.7
packet.7
raw.7
rtnetlink.7
socket.7
tcp.7
udp.7
unix.7
x25.7
    mtk
        s/PF_/AF_/ for socket family constants.  Reasons: the AF_ and
        PF_ constants have always had the same values; there never has
        been a protocol family that had more than one address family,
        and POSIX.1-2001 only specifies the AF_* constants.

Typographical or grammatical errors have been corrected in several
other places.

Changes to individual pages
---------------------------

execve.2
    mtk
        The floating-point environment is reset to the default
        during an execve().

get_mempolicy.2
    Lee Schermerhorn
        Misc cleanup of get_mempolicy(2):
        + mention that any mode flags will be saved with mode.
          I don't bother to document mode flags here because we
          already have a pointer to set_mempolicy(2) for more info
          on memory policy.  mode flags are discussed there.
        + remove some old, obsolete [IMO] NOTES and 'roff comments.
    Lee Schermerhorn
        Update the get_mempolicy(2) man page to add in the description of
        the MPOL_F_MEMS_ALLOWED flag, added in 2.6.23.
    mtk
        Document additional EINVAL error that occurs is MPOL_F_MEMS_ALLOWED
        is specified with either MPOL_F_ADDR or MPOL_F_NODE.

getitimer.2
    mtk
        CONFORMING TO: POSIX.1-2008 marks getitimer() and setitimer()
        obsolete.

mbind.2
    Lee Schermerhorn
        Fix error conditions, now that the kernel silently ignores
        nodes outside the task's cpuset, as long as one valid node
        remains.

        Now that cpuset man page exists, we can refer to it.  Remove
        stale comment regarding lack thereof.
    Lee Schermerhorn
        Add brief discussion of mode flags.
    Lee Schermerhorn
        Attempt to clarify discussion of MPOL_DEFAULT.
    mtk
        Fix URI reference for libnuma.

mprotect.2
    mtk / Maxin John
        Remove EFAULT from errors.  Under ENOMEM error, note that
        EFAULT was the error produced in some cases for kernels before
        2.4.19.

msgctl.2
    mtk, after a note from Filippo Santovito
        In the ipc_perm structure definition, some fields were
        incorrectly named: s/key/__key/ and s/seq/__seq/.

set_mempolicy.2
    Lee Schermerhorn
        Fix up the error return for nodemask containing nodes disallowed by
        the process' current cpuset.  Disallowed nodes are now silently ignored,
        as long as the nodemask contains at least one node that is on-line,
        allowed by the process' cpuset and has memory.

        Now that we have a cpuset man page, we can refer to cpusets directly
        in the man page text.

    Lee Schermerhorn
        Another attempt to rationalize description of MPOL_DEFAULT.

        Since ~2.6.25, the system default memory policy is "local allocation".
        MPOL_DEFAULT itself is a request to remove any non-default policy and
        "fall back" to the surrounding context.  Try to say that without delving
        into implementation details.

    Lee Schermerhorn
        Add discussion of mempolicy mode flags to set_mempolicy(2).
        This adds another reason for EINVAL.

setpgid.2
    mtk
        CONFORMING TO: POSIX.1-2008 marks setpgrp() obsolete.

semctl.2
    mtk, after a note from Filippo Santovito
        In the ipc_perm structure definition, some fields were
        incorrectly named: s/key/__key/ and s/seq/__seq/.

shmctl.2
    Filippo Santovito / mtk
        In the ipc_perm structure definition, some fields were
        incorrectly named: s/key/__key/ and s/seq/__seq/.

utime.2
    mtk
        CONFORMING TO: POSIX.1-2008 marks utime() obsolete.
        CONFORMING TO: POSIX.1-2008 removes the POSIX.1-2001 LEGACY
        marking of utimes(), so mention of this point has been
        removed from the page.

vfork.2
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of vfork().

atan2.3
    Fabian Kreutz
        SEE ALSO Add carg(3).

bcmp.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of bcmp().

bsd_signal.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification ofcw
        bsd_signal().

bzero.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of bzero().

cexp2.3
    mtk
        AVAILABILITY: These functions are still not in glibc
        as at version 2.8.

clock_getres.3
    mtk
         SEE ALSO: Add clock_getcpuclockid(3).

clog2.3
    mtk
        AVAILABILITY: These functions are still not in glibc
        as at version 2.8.

ctime.3
    mtk
        POSIX.1-2008 marks asctime(), asctime_r(), ctime(), and ctime_r()
        as obsolete.

dprintf.3
    mtk
       CONFORMING TO: These functions are nowadays in POSIX.1-2008.

ecvt.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specifications of
        ecvt() and fcvt().

ftime.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of ftime().

ftw.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks ftw() as obsolete.

gcvt.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of gcvt().

getcwd.3
    Reuben Thomas / mtk
        Clarify description of getcwd() for buf==NULL case;
        CONFORMING TO: According to POSIX.1, the behavior of getcwd()
        is unspecified for the buf==NULL case.
    mtk
        Add an introductory paragraph giving an overview of what these
        functions do.
        Fix error in description of getwd(): it does not truncate the
        pathname; rather, it gives an error if the pathname exceeds
        PATH_MAX bytes.
        Rewrote RETURN VALUE section.
        Add EINVAL ENAMETOOLONG errors for getwd().
        Various other clarifications and wording fixes.
        CONFORMING TO: POSIX.1-2001 does not define any errors for
        getwd().
        CONFORMING TO: POSIX.1-2008 removes the specification of getwd().

gethostbyname.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specifications of
        gethostbyname(), gethostbyaddr(), and h_errno.

gets.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of gets().

iconv.3
iconv_close.3
iconv_open.3
    mtk
        VERSIONS: These functions are available in glibc since version 2.1.

index.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specifications of
        index() and rindex().

isalpha.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks isalpha() as obsolete.

makecontext.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specifications of
        makecontext() and swapcontext().

memchr.3
    mtk
        VERSIONS: memrchr() since glibc 2.2; rawmemchr() since glibc 2.1.

mempcpy.3
    mtk
        VERSIONS: mempcpy() since glibc 2.1.

mktemp.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of mktemp().

opendir.3
    mtk
        CONFORMING TO: POSIX.1-2008 specifies fdopendir().

rand.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks rand_r() as obsolete.

siginterrupt.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks siginterrupt() as obsolete.

sigset.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks sighold(), sigignore(),
        sigpause(), sigrelse(), and sigset() as obsolete.

strchr.3
    mtk
        VERSIONS: strchrnul() since glibc 2.1.1.

tempnam.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks tempnam() as obsolete.

tmpnam.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks tmpnam() as obsolete.

toascii.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks toascii() as obsolete.

ualarm.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of ualarm().

ulimit.3
    mtk
        CONFORMING TO: POSIX.1-2008 marks ulimit() as obsolete.

usleep.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of usleep().

standards.7
    mtk
        Updated details for POSIX.1-2008, and noted that if
        POSIX.1-2001 is listed in the CONFORMING TO section of a man
        page, then the reader can assume that the interface is also
        specified in POSIX.1-2008, unless otherwise noted.

time.7
    mtk
         SEE ALSO: Add clock_getcpuclockid(3).

udp.7
    mtk
        SEE ALSO: add udplite(7).

Changes to individual pages (math functions)
--------------------------------------------

Various changes here following on from the big update to the
math pages in the previous release.  Test results going back
glibc 2.3.2 (so far) allowed updates to various pages to note
changes in historical behavior for error reporting by math
functions.  Thanks to the following people for providing me
with test results on various distributions and glibc versions:
Alain Portal, Andries Brouwer, Fabian Kreutz, Heikki Orsila,
Khalil GHORBAL, Pavel Heimlich, Reuben Thomas, Samuel Thibault,
Soh Kam Yung, and Stephane Chazelas

cabs.3
cacos.3
cacosh.3
carg.3
casin.3
casinh.3
catan.3
catanh.3
ccos.3
ccosh.3
cexp.3
cimag.3
clog.3
clog10.3
conj.3
cpow.3
cproj.3
creal.3
csin.3
csinh.3
csqrt.3
ctan.3
ctanh.3
exp10.3
exp2.3
fdim.3
fenv.3
fma.3
fmax.3
fmin.3
log2.3
lrint.3
lround.3
nan.3
pow10.3
remquo.3
round.3
scalbln.3
sincos.3
tgamma.3
trunc.3
    mtk
        Added VERSIONS section noting that these functions first
        appeared in glibc in version 2.1.

cosh.3
    mtk
        BUGS: In glibc 2.3.4 and earlier, an FE_OVERFLOW exception is not
        raised when an overflow occurs.

fenv.3
    mtk / Fabian Kreuz
        Provide more detail in the description of rounding modes.
        Add text describing FLT_ROUNDS (formerly in fma.3).
        Add BUGS section pointing out the FLT_ROUNDS does not reflect
        changes by fesetround().

fma.3
    mtk
        Remove text about FLT_ROUNDS, replacing with a cross-reference
        to fenv(3).

fpclassify.3
    mtk
        CONFORMING TO: Note that the standards provide a weaker guarantee
        for the return value of isinf().

log.3
    mtk
        BUGS: In glibc 2.5 and earlier, log(nan("")) produces a bogus
        FE_INVALID exception.

lround.3
    mtk
        Add reference to fenv(3) for discussion of current rounding mode.

nextafter.3
    mtk
        BUGS: In glibc 2.5 and earlier these functions do not raise an
        FE_UNDERFLOW exception on underflow.

pow.3
    mtk
        BUGS: described buggy NaN return when x is negative and y is large.
        See also: http://sources.redhat.com/bugzilla/show_bug.cgi?id=3866.
        BUGS: Note the bogus FE_INVALID exception that occurred in glibc
        2.3.2 and earlier on overflow and underflow.

remainder.3
    mtk
        Add reference to fenv(3) for discussion of current rounding mode.

round.3
    mtk
        Add reference to fenv(3) for discussion of current rounding mode.

scalb.3
    mtk
        CONFORMING TO: POSIX.1-2008 removes the specification of scalb().

tgamma.3
    mtk
        BUGS: In glibc 2.3.3, tgamma(+-0) produced a domain error
        instead of a pole error.

y0.3
    mtk
        In glibc 2.3.2 and earlier, these functions do not raise an
        FE_INVALID exception for a domain error.

math_error.7
    mtk
        Rewrite introductory paragraph.
        Point out that a NaN is commonly returned by functions that report
        a domain error.
top
==================== Changes in man-pages-3.08 ====================

Released: 2008-08-27, Zurich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Gerrit Renker
Li Zefan
Mike Bianchi
Sam Varshavchik
Venkatesh Srinivas
Vijay Kumar

Apologies if I missed anyone!

New and rewritten pages
-----------------------

getnetent_r.3
    mtk
        Documents getnetent_r(), getnetbyname_r(),
        and getnetbyaddr_r(), the reentrant equivalents of
        getnetent(), getnetbyname(), and getnetbyaddr().

getprotoent_r.3
     mtk
        Documents getprotoent_r(), getprotobyname_r(), and
        getprotobynumber_r(), the reentrant equivalents of
        getprotoent(), getprotobyname(), and getprotobynumber().

getrpcent_r.3
     mtk
        Documents getrpcent_r(), getrpcbyname_r(), and
        getrpcbynumber_r(), the reentrant equivalents of
        getrpcent(), getrpcbyname(), and getrpcbynumber().

getservent_r.3
     mtk
        Documents getservent_r(), getservbyname_r(), and
        getservbyport_r(), the reentrant equivalents of
        getservent(), getservbyname(), and getservbyport().

numa.7
    mtk
        A new page giving overview details for the Linux NUMA interfaces.
        Incorporates some material from mbind.2, and the description
        of /proc/PID/numa_maps from proc.5.

Newly documented interfaces in existing pages
---------------------------------------------

crypt.3
    mtk
        Add description of crypt_r().

New and changed links
---------------------

crypt.3
    mtk
        New link to crypt.3.

getnetbyname_r.3
getnetbyaddr_r.3
    mtk
        New links to new getnetent_r.3.

getprotobyname_r.3
getprotobynumber_r.3
    mtk
        New links to new getprotoent_r.3.

getrpcbyname_r.3
getrpcbynumber_r.3
    mtk
        New links to new getrpcent_r.3.

getservbyname_r.3
getservbyport_r.3
    mtk
        New links to new getservent_r.3.

numa_maps.5
    mtk
        Link to new numa(7) page, which incorporates the
        /proc/PID/numa_maps description.
        As part of the numactl() package, the /proc/PID/numa_maps
        documentation was in a numa_maps.5 page; this link
        ensures that "man 5 numa_maps" still works.
        (Eventually, we may want to remove this link.)

Global changes
--------------

get_mempolicy.2
mbind.2
move_pages.2
set_mempolicy.2
    mtk
        Add reference to numa(7) for information on library support.
        Added  a VERSIONS section.
        SEE ALSO: Add numa(7).

faccessat.2
fchmodat.2
fchownat.2
fstatat.2
mkdirat.2
mknodat.2
linkat.2
openat.2
readlinkat.2
renameat.2
symlinkat.2
unlinkat.2
mkfifoat.3
psignal.3
strsignal.3
    mtk
        These interfaces are specified in POSIX.1-2008.

Changes to individual pages
---------------------------

eventfd.2
    Vijay Kumar
        When an eventfd overflows, select() indicates the file as both
        readable and writable (not as having an exceptional condition).

fcntl.2
    mtk
        F_DUPFD_CLOEXEC is specified in POSIX.1-2008.

getrlimit.2
    mtk
        NOTES: Add text mentioning the shell 'ulimit' (or 'limit')
        built-in command for setting resource limits.

gettimeofday.2
    mtk
        CONFORMING TO: POSIX.1-2008 marks gettimeofday() as obsolete.

link.2
    mtk
        Note kernel version where Linux stopped following symbolic
        links in 'oldpath'; see also http://lwn.net/Articles/294667.
        POSIX.1-2008 makes it implementation-dependent whether or not
        'oldpath' is dereferenced if it is a symbolic link.
        Add a reference to linkat(2) for an interface that allows
        precise control of the treatment of symbolic links.

mbind.2
    mtk
        Remove material on library support and numactl; that material
        is now in numactl.7.

mmap.2
    mtk
        Add kernel version numbers for MAP_32BIT.
        Add some details on MAP_32BIT (see http://lwn.net/Articles/294642).

move_pages.2
    mtk
        Added VERSIONS (from kernel 2.6.18) and CONFORMING TO sections.

open.2
    mtk
        O_CLOEXEC is specified in POSIX.1-2008.

socket.2
    mtk
        s/d/domain/ for name of argument.
        Add reference to socket(2) for further information on
        domain, type, and protocol arguments.

utimensat.2
    mtk
        CONFORMING TO: POSIX.1-2008 specifies utimensat() and futimens().

dirfd.3
    mtk
        CONFORMING TO: Add POSIX.1-2008; other minor changes.

exec.3
    mtk
        Small rewording: "s/returned/failed with/ [an error]".

fmemopen.3
    mtk
        Since glibc 2.7, it is possible to seek past the end of
        a stream created by open_memstream().  Add a BUGS section
        describing the bug in earlier glibc versions.

gethostbyname.3
    mtk
        Clarify exactly which functions are obsoleted by getnameinfo()
        and getaddrinfo().

getnetent.3
    mtk
        Rephrase description in terms of a database, rather than a file.
        Note that each of the get*() functions opens a connection to
        the database if necessary.
        The database connection is held open between get*() calls if
        'stayopen' is non-zero (not necessarily 1).
        s/zero terminated list/NULL-terminated list/
    mtk
        In glibc 2.2, the type of the 'net' argument for getnetbyaddr()
        changed from 'long' to 'uint32_t'.
    mtk
        Note that the gethostbyaddr() 'net' argument is in host byte order.
    mtk
        RETURN VALUE: emphasize that returned pointer points to a
        statically allocated structure.
        SEE ALSO: add getnetent_r.3.

getprotoent.3
    mtk
        Rephrase description in terms of a database, rather than a file.
        Note that each of the get*() functions opens a connection to
        the database if necessary.
        The database connection is held open between get*() calls if
        'stayopen' is non-zero (not necessarily 1).
        s/zero terminated list/NULL-terminated list/
    mtk
        RETURN VALUE: emphasize that returned pointer points to a
        statically allocated structure.
        SEE ALSO: add getprotoent_r.3.

getrpcent.3
    mtk
        s/rpc/RPC/.
        Rephrase description in terms of a database, rather than a file.
        Note that each of the get*() functions opens a connection to
        the database if necessary.
        s/zero terminated list/NULL-terminated list/
    mtk
        RETURN VALUE: emphasize that returned pointer points to a
        statically allocated structure.
        SEE ALSO: add getrpcent_r.3.

getservent.3
    mtk
        Rephrase description in terms of a database, rather than a file.
        Note that each of the get*() functions opens a connection to
        the database if necessary.
        The database connection is held open between get*() calls if
        'stayopen' is non-zero (not necessarily 1).
        s/zero terminated list/NULL-terminated list/
    mtk
        RETURN VALUE: emphasize that returned pointer points to a
        statically allocated structure.
        SEE ALSO: add getservent_r.3.

mkdtemp.3
    mtk
        CONFORMING TO: this function is specified in POSIX.1-2008.

mq_notify.3
    Venkatesh Srinivas
        s/sigev_notify_function/sigev_thread_function/
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494956.

realpath.3
    mtk
        Relocate text for resolved_path==NULL case to DESCRIPTION.
        POSIX.1-2001 leaves the resolved_path==NULL case as
        implementation-defined; POSIX.1-2008 specifies the behavior
        described in this man page.

sem_init.3
    mtk
        POSIX.1-2008 rectifies the POSIX.1-2001 omission, specifying
        that zero is returned by a successful sem_init() call.

core.5
    Mike Bianchi / mtk
        Make the page more helpful to non-programmers by referencing
        the documentation of the shell's 'ulimit' command in the
        discussion of RLIMIT_CORE and RLIMIT_FSIZE.
        SEE ALSO: Add bash(1).
    mtk
        Note that a core dump file can be used in a debugger.

proc.5
    mtk
        Remove /proc/PID/numa_maps material (it is now in numa(7)).

cpuset.7
    mtk
        SEE ALSO: Add numa(7).

inotify.7
    mtk / Li Zefan
         Explain bug that occurred in coalescing identical events in
         kernels before 2.6.25.
         (See commit 1c17d18e3775485bf1e0ce79575eb637a94494a2
         "A potential bug in inotify_user.c" in the 2.6.25 Changelog.)

pthreads.7
    mtk
        Update thread-safe functions list with changes in POSIX.1-2008.
        SEE ALSO: add proc(5).

signal.7
    mtk
        Update list of async-signal-safe functions for POSIX.1-2008.
top
==================== Changes in man-pages-3.09 ====================

Released: 2008-09-10, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Bernd Eckenfels
Bruno Haible
Carsten Emde
Christopher Head
H. Peter Anvin
Jan Engelhardt
Joe Korty
Marko Kreen
Martin (Joey) Schulze
Mats Wichmann
Michael Schurter
Mike Bianchi
Mike Frysinger
Sam Varshavchik
Suka
Timothy S. Nelson
Tolga Dalman
Török Edwin

Apologies if I missed anyone!

New and rewritten pages
-----------------------

fopencookie.3
    mtk
        Document fopencookie(3), a library function that allows
        custom implementation of a stdio stream.

networks.5
    Martin (Joey) Schulze, with a few light edits by mtk
        Documents the /etc/networks file.

Global changes
--------------

Various pages
    mtk
        s/time zone/timezone/ for consistency across pages and
        with POSIX.1.

kill.2
sigaction.2
sigpending.2
sigprocmask.2
sigsuspend.2
confstr.3
ctermid.3
ctime.3
ferror.3
flockfile.3
fopen.3
getaddrinfo.3
getgrnam.3
getnameinfo.3
getopt.3
getpwnam.3
longjmp.3
popen.3
rand.3
readdir.3
setjmp.3
sigsetops.3
sigwait.3
strtok.3
tzset.3
unlocked_stdio.3
    mtk
        Add/fix feature test macro requirements.

Changes to individual pages
---------------------------

fcntl.2
    mtk, after a note by Mike Bianchi
        More clearly and consistently describe whether
        or not the third argument to fcntl() is required,
        and what its type should be.
    mtk
        Move description of negative l_len  from NOTES, integrating
        it into the discussion of file locking.
        Minor rewrites of the text on file locking.

getrusage.2
    Bernd Eckenfels
        SEE ALSO: Add clock(3), clock_gettime(3).
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=353475

ioctl_list.2
    mtk
        Remove old sentence about where to send updates for this page.
        Add more detail on mount options that prevent updates to atime.

sched_setscheduler.2
    Carsten Emde
        Update kernel version numbers relating to real-time support.

stat.2
    H. Peter Anvin
        Note that lstat() will generally not trigger automounter
        action, whereas stat() will.

clock.3
    Bernd Eckenfels
        SEE ALSO: Add clock_gettime(3).
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=353475

clock_getres.3
    Tolga Dalman / mtk
        Add "Link with -lrt" to SYNOPSIS; remove now redundant
        sentence mentioning librt from NOTES.

getdate.3
    mtk
        Rewrite description of getdate_r() and integrate into main text
        (rather than describing in NOTES).
        Other parts rewritten for greater clarity.
        Make it clearer in the main text that glibc does not implement %Z;
        remove discussion of that point from NOTES.
        Added an example program.

hsearch.3
    mtk
        Noted that table size as specified by 'nel' is immutable.
        Described differences between hsearch() and hsearch_r().
        Added missing pieces to RETURN VALUE.
        Added a number of new entries under ERRORS.
        NOTES: added some basic advice on sizing the hash table;
        noted that when a table is destroyed, the caller is responsible
        for freeing the buffers pointed to by 'key' and 'data' fields.
        One of the BUGS was fixed in glibc 2.3.
        Rewrote and clarified various other pieces.
        Rename arguments for reentrant functions, using same name as
        glibc headers: s/ret/retval/; s/tab/htab/.
    mtk, after a suggestion by Timothy S. Nelson
        Integrate discussion of reentrant functions into main discussion
        (rather than as a short paragraph at the end).

iconv.3
    Bruno Haible
        Describe "shift sequence" input.

ptsname.3
    sukadev
        Fix return type of ptsname_r() in SYNOPSIS.

readdir.3
    H. Peter Anvin
        s/stat(2)/lstat(2)/ when discussing d_type (since we
        are talking about a case where we might be interested to
        whether the file itself is a symbolic link).

sigsetops.3
    Chris Head, signed-off-by: Mike Frysinger
        Fix typo: s/sigdelset/sigorset/

proc.5
    Mats Wichmann / mtk
        s/\[number]/[pid]/ in file names for /proc/PID files.
        And similar changes for task/[tid] sub-directories.
    mtk / Mats Wichmann
        In the description if /proc/[pid]/environ, remove reference to
        lilo(8)/grub(8) since there seems to be nothing in those pages
        that related to this /proc file.
    Michael Schurter / mtk
        Remove sentence wrongly saying that /proc/meminfo reports
        info in bytes;
        see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=462969
    mtk
        Note that /proc/meminfo reports system-wide memory usage
        statistics.
    Joe Korty
        Document new fields in /proc/interrupts that were added in
        Linux 2.6.24.

unix.7
    Marko Kreen
        Since glibc 2.8, _GNU_SOURCE must be defined in order to get
        the definition of the ucred structure from <sys/socket.h>.
top
==================== Changes in man-pages-3.10 ====================

Released: 2008-09-23, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

André Goddard Rosa
George Spelvin
Pavel Heimlich
Sam Varshavchik
John Reiser

Apologies if I missed anyone!

Global changes
--------------

closedir.3
dirfd.3
readdir.3
rewinddir.3
scandir.3
seekdir.3
telldir.3
    mtk
        Fix 'dir' argument name: should be 'dirp'.
        POSIX.1-2008 and glibc call this argument 'dirp' (consistent
        with the fact that it is a *pointer* to a DIR structure).

Changes to individual pages
---------------------------

clone.2
    mtk, after a comment by John Reiser
        Clarify text describing getpid() caching bug for clone() wrapper.
        See also:
        http://sourceware.org/bugzilla/show_bug.cgi?id=6910
        https://bugzilla.redhat.com/show_bug.cgi?id=417521

getpid.2
    mtk, after a comment by John Reiser
        Describe getpid()'s PID caching and its consequences.

timerfd_create.2
    Sam Varshavchik
        s/it_interval/it_value/ when talking about TIMERFD_ABSTIME.

closedir.3
    George Spelvin
        Clarify closedir()'s treatment of underlying file descriptor.

tsearch.3
    André Goddard Rosa
        Fix memory leak in example program.
        Add use of tdestroy to example program.
    mtk
        Add "#define _GNU_SOURCE" to example program.

protocols.5
    mtk, after a note from Pavel Heimlich
        Remove SEE ALSO references to nonexistent Guides to Yellow Pages

services.5
    mtk
        Remove some out-of-date bugs.
    mtk, after a note from Pavel Heimlich
        Remove SEE ALSO references to nonexistent Guides to Yellow Pages
        and Bind/Hesiod docs.
    mtk
        Remove crufty text about use of comma instead of slash to separate
        port and protocol.
top
==================== Changes in man-pages-3.11 ====================

Released: 2008-10-07, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

André Goddard Rosa
Eugene V. Lyubimkin
Gergely Soos
Kirill A. Shutemov
Marko Kreen
Maxin B. John
Maxin John
Michael Kerrisk
Nicolas François
Pavel Heimlich
Ricardo Catalinas Jiménez
Sam Varshavchik

Apologies if I missed anyone!

New and rewritten pages
-----------------------

umount.2
    Michael Kerrisk
        Create a new page for umount() and umount2() by extracting
        existing material from mount.2 page.

New and changed links
---------------------

umount2.2
    Michael Kerrisk
        Change link to point to new umount.2
            The umount2() material migrated from mount.2 to umount.2

Changes to individual pages
---------------------------

execve.2
    Michael Kerrisk
        _SC_ARG_MAX is no longer necessarily constant
            POSIX.1-2001 says that the values returned by sysconf()
            are constant for the life of the process.
            But the fact that, since Linux 2.6.23, ARG_MAX is settable
            via RLIMIT_STACK means _SC_ARG_MAX is no longer constant,
            since it can change at each execve().
    Michael Kerrisk
        Linux now imposes a floor on the ARG_MAX limit
            Starting with Linux 2.6.23, the ARG_MAX limit became
        settable via (1/4 of) RLIMIT_STACK.  This broke ABI
        compatibility if RLIMIT_STACK was set such that ARG_MAX
        was < 32 pages.  Document the fact that since 2.6.25
        Linux imposes a floor on ARG_MAX, so that the old limit
        of 32 pages is guaranteed.

            For some background on the changes to ARG_MAX in
        kernels 2.6.23 and 2.6.25, see:
                http://sourceware.org/bugzilla/show_bug.cgi?id=5786
                http://bugzilla.kernel.org/show_bug.cgi?id=10095
                http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101,
                checked into 2.6.25 as
            commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2.

            Also some reordering/rewording of the discussion of ARG_MAX.

fallocate.2
    Michael Kerrisk
        Note lack of glibc wrapper; caller must use syscall(2)
            Glibc doesn't (and quite probably won't) include a
        wrapper for this system call.  Therefore, point out that
        potential callers will need to use syscall(2), and rewrite
        the RETURN VALUE text to show things as they would be if
        syscall() is used.

    Michael Kerrisk
        Refer reader to posix_fallocate(3) for portable interface
            Add a para to start of page that points out that this is the
            low-level, Linux-specific API, and point the reader to
        posix_fallocate(3) for the portable API.

getdents.2
readdir.3
    Michael Kerrisk
        d_type is currently only supported on ext[234]
            As at kernel 2.6.27, only ext[234] support d_type.
            On other file systems, d_type is always set to DT_UNKNOWN (0).

getdents.2
    Michael Kerrisk
        Add an example program
    Michael Kerrisk
        comment out linux_dirent fields with varying location
            The location of the fields after d_name varies according to
            the size of d_name.  We can't properly declare them in C;
            therefore, put those fields inside a comment.
    Michael Kerrisk
        The DT_* constants are defined in <dirent.h>
    Michael Kerrisk
        Remove header files from SYNOPSIS
            None of the header files provides what is needed.
            Calls are made via syscall(2).
    Michael Kerrisk
        The programmer must define the linux_dirent structure
            Point out that this structure is not defined in glibc headers.
    Michael Kerrisk
        s/dirent/linux_dirent/
            The structure isn't currently defined in glibc headers,
        and the kernel name of the structure is 'linux_dirent' (as
            was already used in some, but not all, places in this page).

getrlimit.2
    Michael Kerrisk
        Reword/relocate discussion of BSD's historical RLIMIT_OFILE
            The old sentence sat on its own in an odd place, and anyway the
            modern BSDs use the name RLIMIT_NOFILE.
    Michael Kerrisk
        Refer to execve(2) for RLIMIT_STACK's effect on ARG_MAX
            Refer the reader to new text in execve(2) that describes how
            (since Linux 2.6.23) RLIMIT_STACK determines the value of ARG_MAX.

getrusage.2
    Michael Kerrisk
        Rusage measures are preserved across execve(2)

mlock.2
    Maxin John
        Add EAGAIN error.

move_pages.2
    Nicolas François
        Make a detail of EPERM error more precise

mount.2
    Michael Kerrisk
        Add description of per-process namespaces
            Describe per-process namespaces, including discussion
            of clone() and unshare CLONE_NEWNS, and /proc/PID/mounts.
    Michael Kerrisk
        List a few other file systems that we may see in /proc/filesystems
            Add some modern file systems to that list (xfs, jfs, ext3,
            reiserfs).
    Michael Kerrisk
        Document MS_SILENT (and MS_VERBOSE)

mount.2
umount.2
    Michael Kerrisk
        Split umount*() out into a separate page
            The length of this page means that it's becoming difficult
        to parse which info is specific to mount() versus
        umount()/umount2(), so split the umount material out into
        its own page.

pause.2
    Michael Kerrisk
        Remove mention of words "library function"
            This really is a system call.

readdir.2
    Michael Kerrisk
        The programmer must declare the old_linux_dirent structure
            Glibc does not provide a definition of this structure.
    Michael Kerrisk
        s/dirent/old_linux_dirent/
            Nowadays, this is the name of the structure in the
        kernel sources.
    Michael Kerrisk
        Remove words "which may change"
            These words are slightly bogus: although the interface
        is obsolete, for ABI-compatibility reasons, the kernel folk
        should never be changing this interface.
    Michael Kerrisk
        Remove header files from SYNOPSIS
            glibc doesn't provide any support for readdir(2),
            so remove these header files (which otherwise suggest
            that glibc does provide the required pieces).

recv.2
    Nicolas François
        Move kernel version number to first mention to MSG_ERRQUEUE.

semop.2
    Kirill A. Shutemov
        Fix typo in example
            (The '&' before sop in the semop() call is unneeded.)

send.2
    Michael Kerrisk
        Make kernel version for MSG_CONFIRM more precise
            s/2.3+ only/Since Linux 2.3.15/

sigaction.2
    Michael Kerrisk
        Refer reader to signal(7) for an overview of signals
        Explain semantics of signal disposition during fork() and execve()
        Refer to signal(7) for more details on signal mask.

sigaltstack.2
    Michael Kerrisk
        Explain inheritance of alternate signal stack across fork(2)

sigwaitinfo.2
    Michael Kerrisk
        Distinguish per-thread and process-wide signals
            A sentence clarifying that pending signal set is union of
            per-thread and process-wide pending signal sets.

    Michael Kerrisk
        These interfaces have per-thread semantics
            The page was previously fuzzy about whether the these interfaces
            have process-wide or per-thread semantics.  (E.g., now the
            page states that the calling *thread* (not process) is suspended
            until the signal is delivered.)

sigpending.2
    Michael Kerrisk
        Explain effect of fork() and execve() for pending signal set
    Michael Kerrisk
        Explain how thread's pending signal set is defined
            The pending set is the union of per-thread pending signals
        and process-wide pending signals.

sigprocmask.2
    Michael Kerrisk
        Explain effects of fork() and execve() for signal mask

splice.2
    Michael Kerrisk
        Note that SPLICE_F_MOVE is a no-op since kernel 2.6.21

syscall.2
    Michael Kerrisk
        Add more detail about wrapper functions
            Add a few more details about work generally done by wrapper
            functions.  Note that syscall(2) performs the same steps.

tkill.2
    Michael Kerrisk
        EINVAL error can also occur for invalid TGID
            The EINVAL error on an invalid TGID for tgkill() was
            not documented; this change documents it.

utimensat.2
    Michael Kerrisk
        POSIX.1-2008 revision will likely affect FTMs for futimens()
            Make it clear that the POSIX.1 revision that is likely
            to affect the feature test macro requirements for futimens()
            is POSIX.1-2008.
    Nicolas François
        Make various wordings a little more precise.
            The times argument point to *an array of* structures, and the
            man-page should say that consistently.

wait4.2
    Michael Kerrisk
        wait3() is a library function layered on wait4().
            On Linux wait3() is a library function implemented on top
            of wait4().  (Knowing this is useful when using strace(2),
            for example.)

atan2.3
    Nicolas François
        Fix error in description of range or return value
            In recent changes to the man page, mtk accidentally changed
            the description of the return value range to -pi/2..pi/2;
            the correct range is -pi..pi.

cmsg.3
    Nicolas François
        Add parentheses after macro names.

ctime.3
    Michael Kerrisk
        Clarify mktime()'s use of tm_isdst
            Describe use of tm_isdst for input to mktime();
            explain how mktime() modifies this field.
            (This field is left unchanged in case of error.)

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=500178
    Michael Kerrisk
        Clarify wording for ctime_r() and asctime_r() to indicate that
        the buffer must be at least 26 *bytes*.
    Michael Kerrisk
        Minor rewording of mktime() description.

floor.3
    Nicolas François
        floor.3: Fix error in description: s/smallest/largest/

hsearch.3
    André Goddard Rosa
        Call hdestroy() after using hash table created by hcreate(),
    for the sake of completeness

mq_getattr.3
    Michael Kerrisk
        mq_getattr() and mq_setattr() are layered on mq_getsetattr(2)
            mq_getattr() and mq_setattr() are library functions layered on
            top of the mq_getsetattr(2) system call.
            (This is useful info for users of strace(1).)

mq_receive.3
    Michael Kerrisk
        mq_send() is a library function layered on mq_timedreceive() syscall
             This info is useful for users of strace(1).

mq_send.3
    Michael Kerrisk
        mq_send() is a library function layered on mq_timedsend() syscall
             This info is useful for users of strace(1).

nextafter.3
    Nicolas François
        Make description more precise: s/next/largest/

readdir.3
    Michael Kerrisk
        SEE ALSO: add getdents(2)
             Because readdir() is implemented on top of getdents(2).

realpath.3
    Michael Kerrisk
        Clarify that returned pathname is NULL terminated
            Also clarify that null-byte is included in PATH_MAX limit.

proc.5
    Michael Kerrisk
        Rewrite and simplify description of /proc/mounts
            Most of the relevant discussion is now under /proc/PID/mounts;
            all that needs to be here is a mention of the pre-2.4.19
            system-wide namespace situation, and a reference to the
            discussion under /proc/PID/mounts.
    Michael Kerrisk
        Add description of /proc/PID/mounts
            Largely cribbed from existing /proc/mounts discussion, which is
            about to be rewritten.

mq_overview.7
    Michael Kerrisk
        Add mq_notify() to list of lib. functions and syscalls in MQ API

signal.7
    Michael Kerrisk
        Improve description in NAME section
        Add mention of sigaltstack(2).
        Describe syscalls that synchronously wait for a signal,
        Give overview of syscalls that block until a signal is caught
        Add overview of interfaces for sending signals.

    Michael Kerrisk
        Describe semantics w.r.t. fork() and execve()
            Include text describing semantics of fork() and execve() for
            signal dispositions, signal mask, and pending signal set.
top
==================== Changes in man-pages-3.12 ====================

Released: 2008-10-29, Bucaramanga

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Bert Wesarg
Christian Grigis
Christoph Hellwig
Didier
Halesh S
J.H.M. Dassen (Ray)
Jason Spiro
Lefteris Dimitroulakis
Michael B. Trausch
Pierre Cazenave
Stefan Puiu

Apologies if I missed anyone!

New and rewritten pages
-----------------------

pthread_attr_init.3
    Michael Kerrisk
        New page for pthread_attr_init(3) and pthread_attr_destroy(3)

pthread_attr_setdetachstate.3
    Michael Kerrisk
        New page for pthread_attr_setdetachstate(3) and
        pthread_attr_getdetachstate(3)

pthread_attr_setguardsize.3
    Michael Kerrisk
        New page for pthread_attr_setguardsize(3) and
        pthread_attr_getguardsize(3)

pthread_attr_setscope.3
    Michael Kerrisk
        New page for pthread_attr_setscope(3) and pthread_attr_getscope(3)

pthread_attr_setstack.3
    Michael Kerrisk
        New page for pthread_attr_setstack(3) and pthread_attr_getstack(3)

pthread_attr_setstackaddr.3
    Michael Kerrisk
        New page for pthread_attr_setstackaddr(3) and
        pthread_attr_getstackaddr(3)

pthread_attr_setstacksize.3
    Michael Kerrisk
        New page for pthread_attr_setstacksize(3) and
        pthread_attr_getstacksize(3)

pthread_create.3
    Michael Kerrisk
        New page describing pthread_create(3)

pthread_detach.3
    Michael Kerrisk
        New page for pthread_detach(3)

pthread_equal.3
    Michael Kerrisk
        New page for pthread_equal(3)

pthread_exit.3
    Michael Kerrisk
        New page describing pthread_exit(3)

pthread_getattr_np.3
    Michael Kerrisk
        New page for pthread_getattr_np(3)

pthread_join.3
    Michael Kerrisk
        New page for pthread_join(3)

pthread_self.3
    Michael Kerrisk
        New page for pthread_self(3)

pthread_tryjoin_np.3
    Michael Kerrisk
        New page for pthread_tryjoin_np(3) and pthread_timedjoin_np(3)

Newly documented interfaces in existing pages
---------------------------------------------

dup.2
    Michael Kerrisk
        Add description of dup3()
            dup3() was added in kernel 2.6.27.

epoll_create.2
    Michael Kerrisk
        Add description of new epoll_create1()
            The new epoll_create1() system call appeared in Linux 2.6.27.

eventfd.2
    Michael Kerrisk
        Describe eventfd2() and EFD_NONBLOCK and EFD_CLOEXEC
            Linux 2.6.27 added eventfd(), which supports a flags argument
            that eventfd() did not provide.  The flags so far implemented
            are EFD_NONBLOCK and EFD_CLOEXEC,

inotify_init.2
    Michael Kerrisk
        Add description of inotify_init1()
            The inotify_init1() system call was added in Linux 2.6.27.

pipe.2
    Michael Kerrisk
        Add description of new pipe2() syscall
            pipe2() was added in 2.6.27.  Describe the O_NONBLOCK and
            O_CLOEXEC flags.

signalfd.2
    Michael Kerrisk
        Describe signalfd4() and SFD_NONBLOCK and SFD_CLOEXEC
            Linux 2.6.27 added signalfd4(), which supports a flags argument
            that signalfd() did not provide.  The flags so far implemented
            are SFD_NONBLOCK and SFD_CLOEXEC.

New and changed links
---------------------

dup3.2
    Michael Kerrisk
        New link to dup.2
            dup.2 now contains the description of the new dup3() syscall.

epoll_create1.2
    Michael Kerrisk
        New link to epoll_create.2
            epoll_create.2 now includes a description of the new
            epoll_create1() system call.

eventfd2.2
    Michael Kerrisk
        New link to eventfd.2
            The eventfd.2 page has some details on the eventfd2() system call,
            which was new in Linux 2.6.27.

inotify_init1.2
    Michael Kerrisk
        New link to inotify_init.2
            inotify_init.2 now includes a description of the new
            inotify_init1() system call.

pipe2.2
    Michael Kerrisk
        New link to pipe.2
            pipe(2) now contains a description of the new pipe2() syscall.

pthread_attr_destroy.3
    Michael Kerrisk
        New link to new pthread_attr_init.3

pthread_attr_getdetachstate.3
    Michael Kerrisk
        New link to new pthread_attr_setdetachstate.3

pthread_attr_getguardsize.3
    Michael Kerrisk
        New link to new pthread_attr_setguardsize.3

pthread_attr_getscope.3
    Michael Kerrisk
        New link to new pthread_attr_setscope.3

pthread_attr_getstack.3
    Michael Kerrisk
        New link to new pthread_attr_setstack.3

pthread_attr_getstackaddr.3
    Michael Kerrisk
        New link to new pthread_attr_setstackaddr.3

pthread_attr_getstacksize.3
    Michael Kerrisk
        New link to new pthread_attr_setstacksize.3

pthread_timedjoin_np.3
    Michael Kerrisk
        New link to new pthread_tryjoin_np.3

signalfd4.2
    Michael Kerrisk
        New link to signalfd.2
            signalfd.2 now includes text describing signalfd4() system call,
            new in Linux 2.6.27.

Global changes
--------------

eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2,
wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3,
fopencookie.3, getdate.3, getgrouplist.3, getprotoent_r.3,
getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3,
makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3,
pthread_create.3, pthread_getattr_np.3, sem_wait.3, strtol.3, core.5
    Michael Kerrisk
        Add ".SS Program source" to EXAMPLE
            Add ".SS Program source" to clearly distinguish shell session and
            descriptive text from actual program code.

eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2,
signalfd.2, timerfd_create.2, wait.2, backtrace.3,
clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3,
getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3,
gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3,
malloc.3, matherr.3, offsetof.3, pthread_attr_init.3,
pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3,
strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7
    Michael Kerrisk
        Format user input in shell sessions in boldface

frexp.3, strftime.3, strtok.3
    Michael Kerrisk
        Relocate shell session above example program
            Move the shell session text that demonstrates the use of
            the example program so that it precedes the actual
            example program.  This makes the page consistent with the
            majority of other pages.

Changes to individual pages
---------------------------

epoll_create.2
    Michael Kerrisk
        Say more about unused epoll_create() 'size' arg
            Supply a little more explanation about why the 'size' argument
            of epoll_create() is nowadays ignored.

eventfd.2
    Michael Kerrisk
        Remove crufty text relating to flags argument
            Remove sentence saying that glibc adds a flags argument
            to the syscall; that was only relevant for the older
            eventfd() system call.
getdents.2
    Christoph Hellwig
        Fix text relating to DT_UNKNOWN and 'd_type' support
            Some file systems provide partial support for 'dt_type',
            returning DT_UNKNOWN for cases they don't support.
            Update the discussion of 'd_type' and DT_UNKNOWN to
            support this.

getpeername.2, getsockname.2
    Michael Kerrisk
        SEE ALSO: add ip(7) and unix(7)

getsockopt.2
    Michael Kerrisk
        EINVAL can also occur if 'optval' is invalid
            In some cases, EINVAL can occur if 'optval' is invalid.
            Note this, and point reader to an example in ip(7).
            In response to:
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=216092

inotify_init.2
pipe.2
timerfd_create.2
    Michael Kerrisk
        Clarify *_NONBLOCK description
            Make it clear that the NONBLOCK flag sets an attribute in the new
            open file description.

sched_yield.2
    Michael Kerrisk
        Rewrite description in terms of threads
            The text formerly described the operation of sched_yield() in
            terms of processes.  It should be in terms of threads.
    Michael Kerrisk
        Add NOTES text on appropriate use of sched_yield()
            Strategic calls to sched_yield() can be used to improve
            performance, but unnecessary use should be avoided.

sigaction.2
    Michael Kerrisk
        Clarify that sa_mask affects the *per-thread* signal mask
            The page didn't previously clearly explain the scope of the
            signal mask that is affected by sa_mask.

signalfd.2
    Michael Kerrisk
        Remove crufty text relating to flags argument
            Remove sentence saying that glibc adds a flags argument
            to the syscall; that was only relevant for the older
            signalfd() system call.

sigprocmask.2
    Michael Kerrisk
        Clarify that sigprocmask() operates on a per-thread mask
            The first sentence of the page was vague on the scope of the
            attribute changed by sigprocmask().  Reword to make this
            clearer and add a sentence in NOTES to explicitly state that
            the signal mask is a per-thread attribute.

socket.2
    Michael Kerrisk
        Document SOCK_NONBLOCK and SOCK_CLOEXEC flags
            These flags, specified in the 'type' argument, are supported
            since Linux 2.6.27.

socketpair.2
    Michael Kerrisk
        Refer to socket(2) for SOCK_CLOEXEC and SOCK_NONBLOCK
            Refer the reader to socket(2) for a description of the SOCK_CLOEXEC
            and SOCK_NONBLOCK flags, which are supported by socketpair() since
            Linux 2.6.27.

syscalls.2
    Michael Kerrisk
        Add new 2.6.27 system calls
            Add pipe2(), dup3(), epoll_create1(), inotify_init1(),
            eventfd2(), signalfd4().

timerfd_create.2
    Michael Kerrisk
        Document timerfd_create() TFD_CLOEXEC and TFD_NONBLOCK
            TFD_CLOEXEC and TFD_NONBLOCK are supported since LInux 2.6.27.

vfork.2
    Michael Kerrisk
        Clarify meaning of "child releases the parent's memory"
            The man page was not explicit about how the memory used by
            the child is released back to the parent.

ctime.3
    Michael Kerrisk
        ctime_r() and localtime_r() need not set 'timezone' and 'daylight'
            The man page already noted that these functions need not set
            'tzname', but things could be clearer: it tzset() is not called,
            then the other two variables also are not set.

            Also, clarify that ctime() does set 'timezone' and 'daylight'.

dlopen.3
    Michael Kerrisk
        LD_LIBRARY_PATH is inspected once, at program start-up
            Make it clear that LD_LIBRARY_PATH is inspected *once*, at
            program start-up.  (Verified from source and by experiment.)

fmemopen.3
    Michael Kerrisk
        Document binary mode (mode 'b')
            Glibc 2.9 adds support to fmemopen() for binary mode opens.
            Binary mode is specified by inclusion of the letter 'b' in
            the 'mode' argument.

getaddrinfo.3
    Michael Kerrisk
        Clarify error descriptions with some examples
            Clarify the description of some errors by giving examples
            that produce the errors.  (Text added for EAI_SERVICE and
            EAI_SOCKTYPE.)

            Also, add an error case for EAI_BADFLAGS.

gethostbyname.3
    Michael Kerrisk
        Rationalize text on POSIX.1-2001 obsolete interfaces
            POSIX.1 marks gethostbyname(), gethostbyaddr(), and 'h_errno'
            as obsolete.  The man page explained this, but with some
            duplication.  Remove the duplication, and otherwise tidy up
            discussion of this point.

popen.3
    Michael Kerrisk
        Change one-line description in NAME
            s%process I/O%pipe stream to or from a process%
    Michael Kerrisk
        Document 'e' (close-on-exec) flag
            glibc 2.9 implements the 'e' flag in 'type', which sets the
            close-on-exec flag on the underlying file descriptor.

raise.3
    Michael Kerrisk
        SEE ALSO: add pthread_kill(3)

readdir.3
    Christoph Hellwig
        Fix text relating to DT_UNKNOWN and 'd_type' support
            (This mirrors the previous change to getdents.2)
            Some file systems provide partial support for 'dt_type',
            returning DT_UNKNOWN for cases they don't support.
            Update the discussion of 'd_type' and DT_UNKNOWN to
            support this.

strcpy.3
    Jason Spiro
        Strengthen warning about checking against buffer overruns
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=413940

tty_ioctl.4
    Michael Kerrisk
        Explain capability requirements for TIOCCONS
            Explain capability requirements for TIOCCONS, and describe
            changes in 2.6.10 relating to capabilities.
    Michael Kerrisk
        Explain capability requirements for various ioctls
            For TIOCSLCKTRMIOS, TIOCSCTTY, TIOCEXCL, explain the exact
            capability that is required (the text formerly just said "root"
            in each case).

proc.5
    Michael Kerrisk
        Document /proc/sys/kernel/threads-max
            Defines the system-wide limit on the number of threads (tasks).

utmp.5
    Pierre Cazenave
        It is just "other" who should not have write perms on utmp
            The page was vague before, saying that utmp should not be
            writable by any user.  This isn't true: it can be, and
            typically is, writable by user and group.

epoll.7
    Michael Kerrisk
        Mention epoll_create1() as part of epoll API
            epoll_create1() was added in Linux 2.6.27, and extends the
            functionality of epoll_create().

inotify.7
    Michael Kerrisk
        Mention inotify_init1() in overview of API
            Discuss the new inotify_init1() system call in the overview of
            the inotify API.

ip.7
    Michael Kerrisk
        Detail EINVAL error for IP_ADD_MEMBERSHIP socket option
            In response to:
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=216092

iso_8859-7.7
    Lefteris Dimitroulakis
        Add Drachma, Euro, and Greek Ypogegrammeni
            Also, amend description of characters 0241 and 0242.

man-pages.7
    Michael Kerrisk
        Example shell sessions should have user input boldfaced

pthreads.7
    Michael Kerrisk
        Describe return value from pthreads functions
            Describe the usual success (0) and failure (non-zero) returns,
            and note that POSIX.1-2001 specifies that pthreads functions
            can never fail with the error EINTR.

signal.7
    Michael Kerrisk
        Timeouts make socket interfaces non-restartable
            If setsockopt() is used to set a timeout on a socket(),
            then the various socket interfaces are not automatically
            restarted, even if SA_RESTART is specified when
            establishing the signal handler.  Analogous behavior occurs
            for the "stop signals" case.

socket.7
    Michael Kerrisk
        SEE ALSO: add unix(7)

ld.so.8
    Michael Kerrisk
        Document LD_USE_LOAD_BIAS
            Drawing heavily on Jakub Jelinek's description in
            http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html
            (Subject: [PATCH] Support LD_USE_LOAD_BIAS)
        --inhibit-rpath is ignored for setuid/setgid ld.so
            The --inhibit-rpath option is ignored if ld.so is setuid/setgid
            (not if the executable is setuid/setgid).
    Michael Kerrisk
        Since glibc 2.4, setuid/setgid programs ignore LD_ORIGIN_PATH
    Michael Kerrisk
        Fix description of LD_PROFILE and LD_PROFILE_OUTPUT
            Clarify that LD_PROFILE is pathname or a soname,
            and identify name of profiling output file.
            Fix description of LD_PROFILE_OUTPUT, which wasn't even close to
            the truth.  (But why did it remain unfixed for so many years?)
    Michael Kerrisk
        Since glibc 2.3.4, setuid/setgid programs ignore LD_DYNAMIC_WEAK
    Michael Kerrisk
        Since version 2.3.5, setuid/setgid programs ignore LD_SHOW_AUXV
    Michael Kerrisk
        Reorder lists of LD_* environment variables alphabetically
    Michael Kerrisk
        Since glibc 2.3.4, setuid/setgid programs ignore LD_DEBUG
top
==================== Changes in man-pages-3.13 ====================

Released: 2008-11-07, Bucaramanga

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Bert Wesarg
Karsten Weiss
Lefteris Dimitroulakis
Olaf van der Spek
Sam Varshavchik
Török Edwin
Ulrich Mueller
Valdis Kletnieks

Apologies if I missed anyone!

New and rewritten pages
-----------------------

pthread_attr_setaffinity_np.3
    Michael Kerrisk
        New page for pthread_attr_setaffinity_np(3) and
        pthread_attr_getaffinity_np(3)

pthread_attr_setschedparam.3
    Michael Kerrisk
        New page for pthread_attr_setschedparam(3) and
        pthread_attr_getschedparam(3)

pthread_attr_setschedpolicy.3
    Michael Kerrisk
        New page for pthread_attr_setschedpolicy(3) and
        pthread_attr_getschedpolicy(3)

pthread_setaffinity_np.3
    Michael Kerrisk
        New page for pthread_setaffinity_np(3) and pthread_getaffinity_np(3)

pthread_setschedparam.3
    Michael Kerrisk
        New page for pthread_setschedparam(3) and pthread_getschedparam(3)

pthread_setschedprio.3
    Michael Kerrisk
        New page for pthread_setschedprio(3)

New and changed links
---------------------

pthread_attr_getaffinity_np.3
    Michael Kerrisk
        New link to new pthread_attr_setaffinity_np.3

pthread_attr_getschedparam.3
    Michael Kerrisk
        New link to new pthread_attr_setschedparam.3

pthread_attr_getschedpolicy.3
    Michael Kerrisk
        New link to new pthread_attr_setschedpolicy.3

pthread_getaffinity_np.3
    Michael Kerrisk
        New link to new pthread_setaffinity_np.3

pthread_getschedparam.3
    Michael Kerrisk
        New link to new pthread_setschedparam.3

Global changes
--------------

pthread_attr_setaffinity_np.3
pthread_getattr_np.3
pthread_setaffinity_np.3
pthread_tryjoin_np.3
    Michael Kerrisk
        Explain _np suffix
            Add text to CONFORMING TO explaining that the "_np"
            suffix is because these functions are non-portable.

Changes to individual pages
---------------------------

sched_setaffinity.2
    Michael Kerrisk
        SEE ALSO: add sched_getcpu(3)

sched_setaffinity.2
    Michael Kerrisk
        SEE ALSO: Add pthread_setaffinity_np(3)

sched_setaffinity.2
    Michael Kerrisk
        Clarify EINVAL error for cpusetsize < kernel mask size
            For sched_setaffinity(), the EINVAL error that occurs
            if 'cpusetsize' is smaller than the kernel CPU set size only
            occurs with kernels before 2.6.9.

vfork.2
    Michael Kerrisk
        Child holds parent's memory until execve() or *termination*
            The page was phrased in a few places to describe the child as
            holding the parent's memory until the child does an execve(2)
            or an _exit(2).  The latter case should really be the more
            general process termination (i.e., either _exit(2) or abnormal
            termination).

clock_getres.3
    Michael Kerrisk
        CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID not setabble
            According to POSIX.1-2001, the CLOCK_PROCESS_CPUTIME_ID and
            CLOCK_THREAD_CPUTIME_ID clocks should be settable, but
            currently they are not.

pthread_attr_setstacksize.3
    Michael Kerrisk, after a report by Karsten Weiss
        EINVAL occurs on some systems if stacksize != page-size
            On MacOS X at least, pthread_attr_setstacksize(3) can fail
            with EINVAL if 'stacksize' is not a multiple of the system
            page size.  Best to mention this so as to aid people writing
            portable programs.

pthread_create.3
    Karsten Weiss
        Fix bug in EXAMPLE program
            The calloc() line should read like this instead:

                tinfo = calloc(num_threads, sizeof(struct thread_info));

pthread_exit.3
    Michael Kerrisk
        BUGS: thread group with a dead leader and stop signals
            Document the bug that can occur when a stop signal
            is sent to a thread group whose leader has terminated.
            http://thread.gmane.org/gmane.linux.kernel/611611
            http://marc.info/?l=linux-kernel&m=122525468300823&w=2

resolver.3
    Michael Kerrisk
        Fix prototype of dn_expand()
            The 4th argument is "char *", not "unsigned char *".
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504708

epoll.7
    Michael Kerrisk
        Fix error handling after accept() in example code
            Simply continuing after an error is in most cases wrong,
            and can lead to infinite loops (e.g., for EMFILE).
            So handle an error by terminating.
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504202

epoll.7
    Michael Kerrisk
        Add error handling for epoll_wait() call in example code

epoll.7
    Michael Kerrisk
        Improve example code
            Fill in some gaps in example code (variable declarations,
            adding listening socket to epoll set).
            Give variables more meaningful names.
            Other minor changes.
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504202

iso_8859-7.7
    Lefteris Dimitroulakis
        Add characters for Drachma and Greek Ypogegrammeni
            Lines for these two characters were added in the previous patch,
            but the actual characters were not included in the 4th column
            of the table.  This fixes that.

pthreads.7
    Michael Kerrisk
        Add a section describing thread IDs
            In particular, note that in each pthreads function that takes
            a thread ID argument, that ID by definition refers to a thread
            in the same process as the caller.
top
==================== Changes in man-pages-3.14 ====================

Released: 2008-11-25, Bucaramanga

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andreas Henriksson
Bert Wesarg
Cedric Le Goater
Chris Heath
Eric Biederman
Eugen Dedu
Ivana Varekova
Jen Axboe
Jens Axboe
Loïc Domaigne
Masanari Iida
Paul Evans
Pavel Emelyanov
Pierre-Paul Paquin
Serge E. Hallyn
Stefano Teso
Stew Benedict
Vegard Nossum

Apologies if I missed anyone!

New and rewritten pages
-----------------------

CPU_SET.3
    Michael Kerrisk
        New page documenting CPU_* macros
            This page contains material moved out of sched_setscheduler(2).
            It overwrites a previously existing link file with the same name.
    Michael Kerrisk
        Add description of macros for dynamically allocated CPU sets
            Add descriptions of CPU_ALLOC(), CPU_ALLOC_SIZE(), CPU_FREE(),
            CPU_SET_S(), CPU_CLR_S(), CPU_ISSET_S(), CPU_ZERO_S(),
            CPU_COUNT_S(), CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and
            CPU_EQUAL_S().
    Michael Kerrisk
        Add documentation of CPU_COUNT()
    Michael Kerrisk
        Add description of CPU_AND(), CPU_OR, CPU_XOR(), and CPU_EQUAL()
            Plus a few other small clean-ups of the text
    Michael Kerrisk
        Various improvements in DESCRIPTION
            After review comments by Bert Wesarg:
            * Explain that cpu_set_t is a bitset, but should be considered
              opaque.
            * A CPU set can be duplicated with memset().
            * Size of a CPU set is rounded up to size of long.
            * CPU_SETSIZE is in bits, but the setsize argument is in bytes.
    Michael Kerrisk
        Document CPU_ALLOC()/CPU_ALLOC_SIZE() bug
            These macros return twice what they should because of thinko
            in glibc 2.8 and earlier.  The bug is fixed for glibc 2.9.
            http://sourceware.org/bugzilla/show_bug.cgi?id=7029
    Michael Kerrisk
        NOTES: Discuss use of types in "prototypes" for these macros
            The SYNOPSIS shows types for arguments and return values, but
            these are really just suggestions: since the interfaces are
            macros, the compiler won't catch all violations of
            the "type rules".  Warn the reader of this.

pthread_attr_setinheritsched.3
    Michael Kerrisk
        New page for pthread_attr_setinheritsched(3) and
        pthread_attr_getinheritsched(3)

pthread_cancel.3
    Michael Kerrisk
        New page for pthread_cancel(3)

pthread_cleanup_push.3
    Michael Kerrisk
        New page for pthread_cleanup_push(3) and pthread_cleanup_pop(3)

pthread_setcancelstate.3
    Michael Kerrisk
        New page for pthread_setcancelstate(3) and pthread_setcanceltype(3)

pthread_testcancel.3
    Michael Kerrisk
        New page for pthread_testcancel(3)

Newly documented interfaces in existing pages
---------------------------------------------

clone.2
    Jens Axboe
        Document CLONE_IO (new in Linux 2.6.25)
            Some text also by mtk.
    Michael Kerrisk
        Document CLONE_NEWNET
    Michael Kerrisk
        Document CLONE_NEWUTS (new in Linux 2.6.19)
    Michael Kerrisk
        Document CLONE_NEWIPC flag (new in Linux 2.6.19)
    Michael Kerrisk
        Document CLONE_NEWPID flag (new in Linux 2.6.24)

mmap.2
    Michael Kerrisk
        Document MAP_STACK flag (new in Linux 2.6.27)

arp.7
    Michael Kerrisk
        Document /proc file retrans_time_ms (new in Linux 2.6.12)
    Michael Kerrisk
        Document /proc file base_reachable_time_ms (new in Linux 2.6.12)

icmp.7
    Michael Kerrisk
        Document icmp_ignore_bogus_error_responses (new in Linux 2.2)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document icmp_ratelimit and icmp_ratemask (new in Linux 2.4.10)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document icmp_echo_ignore_broadcasts (new in Linux 2.6.12)
            Text taken from Documentation/networking/ip-sysctl.txt

tcp.7
    Michael Kerrisk
        Document /proc file tcp_slow_start_after_idle (new in Linux 2.6.18)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_base_mss (new in Linux 2.6.17)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_frto_response (new in Linux 2.6.22)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_moderate_rcvbuf (new in Linux 2.4.17/2.6.7)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_congestion_control (new in Linux 2.4.13)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_no_metrics_save (new in Linux 2.6.6)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_mtu_probing (new in Linux 2.6.17)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_dma_copybreak (new in Linux 2.6.24)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_tso_win_divisor (new in Linux 2.6.9)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_allowed_congestion_control (new in Linux 2.4.20)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_workaround_signed_windows (new in Linux 2.6.26)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_available_congestion_control (new in Linux 2.4.20)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_abc (new in Linux 2.6.15)
            Text taken from Documentation/networking/ip-sysctl.txt

udp.7
    Michael Kerrisk
        Document /proc files udp_mem, udp_rmem_min, and udp_wmem_min
            All of these are new in Linux 2.6.25

New and changed links
---------------------

CPU_ALLOC.3
CPU_ALLOC_SIZE.3
CPU_AND.3
CPU_AND_S.3
CPU_CLR_S.3
CPU_COUNT.3
CPU_COUNT_S.3
CPU_EQUAL.3
CPU_EQUAL_S.3
CPU_FREE.3
CPU_ISSET_S.3
CPU_OR.3
CPU_OR_S.3
CPU_SET_S.3
CPU_XOR.3
CPU_XOR_S.3
CPU_ZERO_S.3
    Michael Kerrisk
        New link to new CPU_SET.3

CPU_CLR.3
CPU_ISSET.3
CPU_ZERO.3
    Michael Kerrisk
        Update links to point to CPU_SET.3
            The documentation of the CPU_* macros migrated to a new
            location: CPU_SET.3.

pthread_attr_getinheritsched.3
    Michael Kerrisk
        New link to new pthread_attr_setinheritsched.3

pthread_cleanup_pop.3
    Michael Kerrisk
        New link to new pthread_cleanup_push.3

pthread_setcanceltype.3
    Michael Kerrisk
        New link to new pthread_setcancelstate.3

Global changes
--------------

clone.2
mount.2
unshare.2
proc.5
path_resolution.7
    Michael Kerrisk
        Global fix: s/namespace/mount-point namespace/, as appropriate
            In recent times, a number of other namespace flags have been
            added to clone(2).  As such, it is no longer clear to use
            the generic term "namespace" to refer to the particular
            namespace controlled by CLONE_NEWNS; instead, use the
            term "mount-point namespace".
    Michael Kerrisk
        Global fix: s/mount-point namespace/mount namespace/
            This is more consistent with the term "mounts namespace"
            used in the 2008 ACM SIGOPS paper, "Virtual servers
            and and checkpoint/restart in mainstream Linux".
            (I avoided the "s", because using the plural strikes me
            as klunky English, and anyway we don't talk about
            the "PIDs namespace" or the "networks namespace", etc..)

connect.2
listen.2
send.2
uname.2
cmsg.3
proc.5
arp.7
ddp.7
icmp.7
ip.7
raw.7
socket.7
tcp.7
udp.7
    Michael Kerrisk
        Global fix: eliminate mention of the obsolete sysctl(2) interface
            Many pages still mention use of the obsolete sysctl(2) system
            call, or used the term "sysctls"; rewrite these mentions to
            instead be in terms of /proc interfaces.

fcntl.2
signal.2
mbsnrtowcs.3
mbsrtowcs.3
mbtowc.3
wcrtomb.3
wcsnrtombs.3
wcsrtombs.3
wctomb.3
    Michael Kerrisk
        Global fix: s/multi-thread/multithread/

getdents.2
pthread_attr_init.3
pthread_create.3
pthread_getattr_np.3
pthread_setaffinity_np.3
pthread_setschedparam.3
pthread_tryjoin_np.3
    Michael Kerrisk
        Use consistent error-handling function names
            Many older pages use a handle_error() macro to do simple
            error handling from system and library function calls.
            Switch these pages to do similar.

Changes to individual pages
---------------------------

time.1
    Michael Kerrisk
        Note that some shells have a 'time' built-in command
            Therefore, to access the functionality described on this page,
            it may be necessary to specify the full pathname.

clone.2
    Michael Kerrisk
        Place list of CLONE_* flags in alphabetical order
            (No content changes.)
fsync.2
    Michael Kerrisk
        Update feature test macro requirements for fsync()
            Since glibc 2.8, the fsync() declaration is also exposed if
            _POSIX_C_SOURCE >= 200112L

sched_setaffinity.2
    Michael Kerrisk
        Add note on system-imposed restrictions on CPUs actually used
            After Loic Domaigne's suggestion for pthread_setaffinity_np(3), add
            similar text to this page noting that the system silently
            limits the set of CPUs on which the process actually runs to
            the set of CPUs physically present and the limits imposed by
            cpuset(7).

sched_setaffinity.2
    Michael Kerrisk
        Removed discussion of CPU_* macros()
            These macros are now moving to a separate page.
    Michael Kerrisk
        Refer reader to pthread_setaffinity_np(3)
            pthread_setaffinity_np() is preferable for setting
            thread CPU affinity if using the POSIX threads API.

sysctl.2
    Michael Kerrisk
        Add prominent warning against using this system call
            This was already stated under NOTES, but make it even more
            prominent by adding a sentence at the start of the DESCRIPTION.

uname.2
    Michael Kerrisk
        Add C comments describing fields in utsname structure

atan2.3
    Stefano Teso
        Fix description of range of function value return
            The range is not [-pi/2, pi/2], but [-pi, pi].

            (mtk: This error was reported by Nicolas Francois, and
            should have been fixed in 3.11, but somewhere along the way,
            the fix got lost.)

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=506299

bindresvport.3
    Michael Kerrisk
        Since glibc 2.8, EPFNOSUPPORT error is now EAFNOSUPPORT
            Glibc switched to using a POSIX-specified error code for
            this error case.

            http://bugs.linuxbase.org/show_bug.cgi?id=2375

clock_getres.3
    Michael Kerrisk
        CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID not settable
            According to POSIX.1-2001, the CLOCK_PROCESS_CPUTIME_ID and
            CLOCK_THREAD_CPUTIME_ID clocks should be settable, but
            currently they are not.

getgrnam.3
    Michael Kerrisk
        Clarify and add more detail in RETURN VALUE description
            The page was a bit fuzzy in describing the return values for
            various cases.  In particular, it needed to be more explicit
            in describing what happens for the "not found" case.

            This is an analogous change to the change for
            getpwnam.3, made after Andreas Henriksson's report.
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787
    Michael Kerrisk
        Rename arguments to getgrnam_r() and getgrgid_r()
            s/gbuf/grp/ and s/gbufp/result/, for consistency
            with POSIX.1 argument names.
    Michael Kerrisk
        Clarify RETURN VALUE description
            The page was a bit fuzzy in describing the return values for
            various cases.  In particular, it needed to be more explicit
            in describing what happens for the "not found" case.

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504708

getpwnam.3
    Michael Kerrisk
        Rename arguments to getpwnam_r() and getpwuid_r()
            s/pwbuf/pwd/ and s/pwbufp/result/, for consistency
            with POSIX.1 argument names.
    Michael Kerrisk
        Clarify and add more detail in RETURN VALUE description
            The page was a bit fuzzy in describing the return values for
            various cases.  In particular, it needed to be more explicit
            in describing what happens for the "not found" case.

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787
    Michael Kerrisk
        Add an EXAMPLE program for getpwnam_r()

inet_ntop.3
    Michael Kerrisk
        Rename 'cnt' argument to 'size'
            This is consistent with POSIX.1, and also a more sensible name.
    Michael Kerrisk
        Rework text describing 'size' argument
            (After a suggestion by Vegard Nossum.)
            Also made a few other small rewordings to in the initial
            paragraph.

makecontext.3
    Michael Kerrisk
        Add text on use of pointer arguments to makecontext()
            Passing pointer arguments to makecontext() is possible,
            but only on some architectures, and with no guarantees
            of portability.

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504699

pthread_attr_setaffinity_np.3
    Michael Kerrisk
        Various fixes after review by Loic Domaigne
            Reviewed-by: Loic Domaigne

pthread_attr_setaffinity_np.3
pthread_setaffinity_np.3
    Michael Kerrisk
        Update to reflect new location of CPU_*() documentation
            The CPU_*() macros are now documented in CPU_SET.3;
            update to reflect that fact.
    Michael Kerrisk
        Remove redundant text relating to CPU sets
            Information about CPU_SETSIZE can be found in CPU_SET.3, so
            remove discussion of it here.

pthread_attr_setschedparam.3
pthread_setschedparam.3
    Michael Kerrisk
        Remove text saying that only sched_priority is required by POSIX.1
            Loic Domaigne points out that if a system implements
            SCHED_SPORADIC (which Linux does not), then other
            fields are also specified in sched_param.  The simple
            solution is just to remove that phrase from the man
            page.

pthread_cancel.3
pthread_detach.3
pthread_join.3
pthread_setaffinity_np.3
    Michael Kerrisk
        Make text of ESRCH error consistent

pthread_setaffinity_np.3
    Michael Kerrisk
        Add text to EINVAL error mentioning cpuset(7)
    Michael Kerrisk
        Various improvements after review by Loïc Domaigne
            Various fix-ups after Loïc's review.

            Reviewed-by: Loïc Domaigne

pthread_setschedparam.3
    Michael Kerrisk
        PTHREAD_INHERIT_SCHED is default for inherit scheduler attribute
            In EXAMPLE, note that PTHREAD_INHERIT_SCHED is the default for
            the inherit scheduler attribute attribute.

syslog.3
    Masanari Iida
        LOG_KERN messages can't be generated from user processes
            Masanari notes that this is an FAQ for logger(1) and that
            Solaris and FreeBSD document this point in syslog(3).
            The glibc info page also hides this comment in its source:

                Internally, there is also LOG_KERN, but LOG_KERN == 0,
                which means if you try to use it here, just selects default.

proc.5
    Ivana Varekova
        Fix reference to kernel source file
            Use relative reference to Documentation/mtrr.txt.

arp.7
    Michael Kerrisk
        Add kernel version numbers for /proc interfaces

cpuset.7
    Michael Kerrisk
        SEE ALSO: add CPU_SET(3)

epoll.7
    Michael Kerrisk
        Note glibc version that added epoll support

icmp.7
    Michael Kerrisk
        Add kernel version numbers to /proc file descriptions

inotify.7
    Vegard Nossum
        Fix description of max_user_watches
            It seems that inotify(7) is wrong here:

            "/proc/sys/fs/inotify/max_user_watches
                This specifies a limit on the number of watches that can be
                associated with each inotify instance."

            On my system, the default value for this variable is 8192. But I
            cannot create more than 8192 watches in total for the same UID
            even when they are on different inotify instances. So I suggest
            to rephrase this as: "This specifies an upper limit on the
            number of watches that can be created per real user ID."

ip.7
    Michael Kerrisk
        Reorder socket options alphabetically
    Michael Kerrisk
        Added kernel version numbers for IP_* socket options
    Michael Kerrisk
        Relocate kernel version information for IP_PMTUDISC_PROBE
    Michael Kerrisk
        Add kernel version numbers for /proc/sys/net/ipv4/ip_* files
    Michael Kerrisk
        Remove mention of kernel header from description of IP_RECVERR
            Looks like glibc has had this definition since about version 2.1.
    Michael Kerrisk
        Relocate kernel version information for ip_mreqn structure
    Michael Kerrisk
        Relocate info about Linux-specific sockopts to NOTES
            Also add some source comments about non-standard Linux-specific
            options that are not yet documented.

netlink.7
    Vegard Nossum
        Fix incorrect variable names in example code
            s/snl/sa/ * 2

pthreads.7
    Michael Kerrisk
        Add section on cancellation points
            This section includes a list of the functions that must and
            may be cancellation points.
    Michael Kerrisk
        Rework, and fix small error in, thread-safe function list
            Integrate the changes that occurred in POSIX.1-2008 into the
            main list (to be consistent with the list, elsewhere on this
            page, of functions that are cancellation points).

            Also, fix an error that said that strerror() was added to
            the list in POSIX.1-2008.  It was strsignal() that was
            added.  (strerror() was already in the list in POSIX.1-2001.)
    Michael Kerrisk
        Tweak text on sigpause() cancellation point
            In POSIX.1-2009, this function moves from the "must be"
            to the "may be" list.
    Michael Kerrisk
        Add ref to signal(7) for further info on use of real-time signals
            signal(7) provides some further details on the use of real-time
            signals by the two Linux threading implementations.
    Michael Kerrisk
        SEE ALSO: add pthread_attr_init() and pthread_cancel()

tcp.7
    Michael Kerrisk
        Update description of tcp_rmem defaults for Linux 2.6
    Michael Kerrisk
        Add kernel version numbers for TCP_* socket options
            Note kernel version were each socket option first appeared.
    Michael Kerrisk
        The tcp_bic* proc files disappeared in Linux 2.6.13
    Michael Kerrisk
        tcp_vegas_cong_avoid disappeared in Linux 2.6.13
    Michael Kerrisk
        Add mention of RFC 4138 for 'tcp_frto' /proc file
    Michael Kerrisk
        Remove mention of /proc in VERSIONS
            This information is not indicated for each /proc interface
    Michael Kerrisk
        Clarify that tcp_mem measures in units of the system page size
    Michael Kerrisk
        Update tcp_frto description for 2.6.22 changes
            Linux 2.6.22 added a mode value 2 ("Enable SACK-enhanced
            F-RTO if flow uses SACK").
    Michael Kerrisk
        Fix alphabetical order in /proc file list
            A few entries were slightly out of order.
    Michael Kerrisk
        Remove obsolete statement about /proc from VERSIONS
            Much of the text has been updated to 2.6.27 or so,
            so this statement no longer applies.
    Michael Kerrisk
        Add kernel version numbers for each /proc interface
            Note kernel version where each /proc interface first appeared
    Michael Kerrisk
        tcp_westwood /proc file disappeared in Linux 2.6.13
    Michael Kerrisk
        Update description of tcp_wmem defaults for Linux 2.6
top
==================== Changes in man-pages-3.15 ====================

Released: 2008-12-05, Bucaramanga

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andre Majorel
Andries E. Brouwer
Chris Heath
Drake Wilson
Mats Wichmann
Mel Gorman
Michael Kerrisk
Mike Fedyk
Pavel Machek
Petr Baudis
Phil Endecott
Rob Landley
Sam Varshavchik

Apologies if I missed anyone!

New and rewritten pages
-----------------------

makedev.3
    Michael Kerrisk
        New page for makedev(), major(), and minor() macros

pthread_cleanup_push_defer_np.3
    Michael Kerrisk
        New page for pthread_cleanup_push_defer_np(3) and
        pthread_cleanup_pop_restore_np(3)

Newly documented interfaces in existing pages
---------------------------------------------

accept.2
    Michael Kerrisk
        Document accept4() system call, new in Linux 2.6.28

fmemopen.3
    Petr Baudis
        Add description of open_wmemstream(3)

tcp.7
    Michael Kerrisk
        Document MSG_TRUNC flag for TCP sockets

New and changed links
---------------------

accept4.2
    Michael Kerrisk
        New link to accept.2
            accept.2 now documents the new accept4() system call.

open_wmemstream.3
    Petr Baudis
        New link to fmemopen.3
            fmemopen.3 now documents open_wmemstream().
pthread_cleanup_pop_restore_np.3
    Michael Kerrisk
        New link to new pthread_cleanup_push_defer_np.3

Global changes
--------------

accept.2
listen.2
recv.2
getpeername.2
getsockname.2
shutdown.2
socketpair.2
    Michael Kerrisk
        Global fix: SEE ALSO: add socket(7)

bind.2
rcmd.3
capabilities.7
ip.7
    Michael Kerrisk
        Global fix: s/reserved port/privileged port/
            Some pages used one term, some pages the other term;
            make some consistency.

connect.2
getpeername.2
getsockname.2
    Michael Kerrisk
        Use consistent argument names
            Most other sockets pages are using the names 'addr'
            and 'addrlen'; make these pages do the same.

getpeername.2
getsockname.2
getsockopt.2
recv.2
send.2
shutdown.2
sockatmark.3
socket.7
udplite.7
    Michael Kerrisk
        SYNOPSIS: Rename socket file descriptor argument to 'sockfd'
            Many sockets man pages use the name 'sockfd' already.
            For consistency, changes the others to do so as well.

gnu_dev_major.3
gnu_dev_makedev.3
gnu_dev_minor.3
major.3
minor.3
    Michael Kerrisk
        New links to new makedev(3) page

Changes to individual pages
---------------------------

_exit.2
    Michael Kerrisk
        Since glibc 2.3, the exit() wrapper function invokes exit_group(2)
            This information is useful to users of strace(1).

accept.2
    Michael Kerrisk
        Clarify details when returned address is truncated
            If the returned address is truncated, the 'addrlen' argument
            indicates the actual size of the address, rather than a count
            of the number of bytes in the truncated buffer.

            Also clarify that if 'addr' argument is NULL, then 'addrlen'
            should is unused, and should also be NULL.
    Michael Kerrisk
        Reorder ERRORS list
            Some errors were listed under a separate "may" heading.
            There's probably no real need to do this; integrate
            those errors into the main list.

exit_group.2
    Michael Kerrisk
        Note that since glibc 2.3, exit(2) invokes exit_group()

futex.2
    Michael Kerrisk
        Mention that glibc provides no wrapper function for futex()

get_thread_area.2
    Michael Kerrisk
        Note that glibc provides no wrapper for this system call

getdomainname.2
    Michael Kerrisk
        Substantial rewrite
            Expand description of setdomainname() and getdomainname().
            Note that getdomainname() is implemented as a library function
            in glibc.
            Note limits on size of domain name.
            Reorganize ERRORS list.

gethostname.2
    Michael Kerrisk
        Various parts rewritten
            Write a paragraph describing sethostname().

            Clarify differences between glibc's gethostbyname() and
            the kernel gethostbyname() system calls.

gethostname.2
    Michael Kerrisk
        Note that HOST_NAME_MAX is 64 on Linux
            Also note that in pre-1.0 days, the limit on hostnames
            was 8 bytes.

getpeername.2
    Michael Kerrisk
        Note that returned address may be truncated if buffer is too small

getsid.2
    Michael Kerrisk
        Simplified version information and moved to a new VERSIONS section

getsockname.2
    Michael Kerrisk
        Note that returned address is truncated if buffer is too small

mknod.2
    Michael Kerrisk
        Refer reader to makedev(3) to build a device ID

mmap.2
    Michael Kerrisk
        Loosen language around how 'addr' hint is interpreted
            Mel Gorman reported that in Linux 2.6.27, 'addr' is rounded
            down to a page boundary.

            Before kernel 2.6.26, if 'addr' was taken as a hint, it was
            rounded up to the next page boundary.  Since Linux 2.6.24,
            it is rounded down.  Therefore, loosen the description of
            this point to say that the address is rounded to "a nearby
            page boundary".

open.2
    Michael Kerrisk
        EFBIG error is now EOVERFLOW (since Linux 2.6.24)
            When a 32-bit app opens a file whose size is too big to be
            represented in 31-bits, POSIX.1 specifies the error EOVERFLOW.
            Linux used to give EFBIG for this case, but 2.6.24 fixed this.

            Also, add some text to describe the error scenario in
            more detail.

pread.2
    Michael Kerrisk
        Note that glibc emulation for these calls uses lseek(2)
            (This makes it clearer that the emulated calls are not atomic.)

recv.2
send.2
    Michael Kerrisk
        Make names of "address" and "address length" args more consistent
            Make the names of these arguments more consistent with other
            sockets man pages.

recv.2
    Michael Kerrisk
        Clarify details when returned address is truncated
            If the recvfrom() returned address is truncated, the 'fromlen'
            argument indicates the actual size of the address, rather than
            a count of the number of bytes in the truncated buffer.

            Also clarify that the 'from' argument can be NULL, in which
            case 'fromlen' should is unused, and should also be NULL.
    Michael Kerrisk
        Internet datagram and netlink sockets support MSG_TRUNC for recv(2)
            Internet datagram (since Linux 2.4.27/2.6.8),
            and netlink (since Linux 2.6.22) sockets support
            the MSG_TRUNC flag for recv(2).

select.2
    Michael Kerrisk
        Rewrote text describing feature test macros requirement for pselect()

select_tut.2
    Michael Kerrisk
        Fix SHUT_FD* macros in example program
            Add "do {} while (0)"

set_thread_area.2
    Michael Kerrisk
        Note that glibc provides no wrapper for this system call

setfsgid.2
setfsuid.2
    Michael Kerrisk
        Simplify version information and move to a VERSIONS section

setsid.2
    Michael Kerrisk
        Rework RETURN VALUE section; add an ERRORS section

setup.2
    Michael Kerrisk
        Relocate some CONFORMING TO text to VERSIONS and NOTES

stat.2
    Michael Kerrisk
        Document EOVERFLOW error
    Michael Kerrisk
        Refer reader to major() and minor() to decompose a device ID

syscalls.2
    Michael Kerrisk
        Fix version numbers for a few system calls
            Some 2.6 system calls were wrongly mentioned as also being
            backported into a 2.4.x kernel.

uname.2
    Michael Kerrisk
        DESCRIPTION: Point reader at NOTES for further info on field lengths

atan.3
    Andries E. Brouwer
        Fix return value description
            The correct range for the return value is [-pi/2,pi/2].
            (mtk's fix in the last change to the return value text was
            a botch-up of a (correct) suggestion by Nicolas Francois.)

atexit.3
    Michael Kerrisk
        atexit() and on_exit(3) register functions on the same list
    Michael Kerrisk
        Terminating registered function using longjmp() is undefined
            According to POSIX.1, using longjmp() to terminate execution of
            a function registered using atexit() produces undefined results.
    Michael Kerrisk
        Calling exit(3) more than once produces undefined results
            If an exit handler itself calls exit(3), the results are
            undefined (see the POSIX.1-2001 specification of exit(3)).
    Michael Kerrisk
        The same exit handler may be registered multiple times
    Michael Kerrisk
        Calling _exit(2) terminates processing of exit handlers
    Michael Kerrisk
        Terminating registered function using longjmp() is undefined
            According to POSIX.1, using longjmp() to terminate execution of
            a function registered using atexit() produces undefined results.

bindresvport.3
    Mats Wichmann
        SYNOPSIS: s/\*\*/*/ in prototype
    Michael Kerrisk
        Fix errors regarding port used, plus other rewrites
            Glibc's bindresvport() takes no notice of sin->sin_port:
            it always returns an arbitrary reserved port in the
            anonymous range (512-1023).  (Reported by Mats Wichmann.)

            Also:
            * Add EADDRINUSE and EACCES errors.
            * Mention use of getsockname(2).
            * Other minor rewrites and reorderings of the text.
            * Explicitly note that glib's bindresvport() ignores
              sin->sin_port.
            * Change license There's now virtually no text remaining from
              the 1.70 version of this page.

            Reviewed-by: Mats Wichmann
            Reviewed-by: Petr Baudis

dlopen.3
    Petr Baudis
        Describe confusing dladdr() behavior
            dladdr() will act unexpectedly if called from non-pic code on a
            compile-time-generated function pointer.

fmemopen.3
    Michael Kerrisk
        Add VERSIONS section
    Petr Baudis
        SEE OPEN: Add fopencookie(3)
            fopencookie(3) is used to implement fmemopen().

fopen.3
    Petr Baudis
        SEE ALSO: Add fmemopen(3) and fopencookie(3)

fopencookie.3
    Petr Baudis
        fopencookie() needs _GNU_SOURCE feature test macro

getaddrinfo.3
    Petr Baudis
        Document results ordering and /etc/gai.conf
            This patch documents the order of the getaddrinfo(3) results
            (RFC 3484), how should the application deal with that,
            mentions the extremely common cause of having multiple
            results per query (both IPv4 and IPv6 addresses available)
            and mentions /etc/gai.conf.

            (mtk: Minor tweaks, and note glibc version for /etc/gai.conf)

isatty.3
    Michael Kerrisk
        Complete rewrite of this page, with rather more detail

memmem.3
    Michael Kerrisk
        Remove sentence saying that libc 5.0.9 is still widely used
            That was a *long* time ago.

on_exit.3
    Michael Kerrisk
        Document handling of registrations on fork(2) and execve(2)
            Treatment in these cases is the same as for atexit(3).
    Michael Kerrisk
        Arg given to registered function is status from *last* call to exit()
            It's a subtle point, but if a registered function itself
            calls exit(3), then subsequent functions that were registered
            with on_exit(3) will see the exit status given to the more
            recent exit(3) call.
    Michael Kerrisk
        Note that same function may be registered multiple times

setlocale.3
locale.7
    Michael Kerrisk
        Clean up the description of LANGUAGE environment variable
            Clean up the $LANGUAGE description, by removing bogus comments
            from setlocale(3) and expanding the mention in locale(7).

            Maybe you will decide that a more detailed description
            should be left to the gettext(3) documentation, but I
            actually care about the invisible part of the patch more
            since the comments have put me off the track initially
            ($LANGUAGE has nothing to do with setlocale(3) and is
             completely isolated to gettext, as obvious from the
             glibc sources).

proc.5
    Michael Kerrisk
        /proc/stat: s/minor/disk_idx/ in description of /proc/stat
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=225619

capabilities.7
    Drake Wilson
        Various minor fixes as per Debian bug 471029
            The relevant pieces of
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=471029 are:

              - Delete duplicate subentry for KEYCTL_CHOWN/KEYCTL_SETPERM
                operations in the CAP_SYS_ADMIN entry.  (It feels like that
                capability entry should be converted to a list, but I've
                left it in semicolon-delimited form for now.)

              - Remove text about ENFILE from the text about the
                /proc/sys/fs/file-max limit in the CAP_SYS_ADMIN entry, since
                this is already described in the man pages for the relevant
                ofile-creating system calls.

              - Correct or clarify a few other bits of grammar and such;
                see the diff file itself for details.

socket.7
    Michael Kerrisk
        SEE ALSO: add tcp(7) and udp(7)

tcp.7
    Michael Kerrisk
        Relocate out-of-band data discussion
            Move to a new subsection entitled "Sockets API".
    Michael Kerrisk
        Note that MSG_PEEK can be used on out-of-band data

time.7
    Michael Kerrisk
        SEE ALSO: add clock_gettime(3)

unix.7
    Michael Kerrisk
        Unix domain sockets don't support the recv() MSG_TRUNC flag
    Michael Kerrisk
        Retitled subsection "(Un)supported features" to "Sockets API"
            This is consistent with the recent change in tcp(7).
top
==================== Changes in man-pages-3.16 ====================

Released: 2009-01-13, Christchurch

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Colin Watson
Florentin Duneau
Petr Baudis

Apologies if I missed anyone!

New and rewritten pages
-----------------------

pthread_getcpuclockid.3
    Michael Kerrisk
        New page documenting pthread_getcpuclockid(3)

libc.7
    Michael Kerrisk
        New page giving brief overview of C libraries on Linux

rtld-audit.7
    Michael Kerrisk
        New page documenting dynamic linker auditing API

Newly documented interfaces in existing pages
---------------------------------------------

ld.so.8
    Petr Baudis
        Document LD_AUDIT
    Petr Baudis
        Document LD_POINTER_GUARD

New and changed links
---------------------

gethostid.2
    Michael Kerrisk
        New link to new page location in Section 3

sethostid.2
    Michael Kerrisk
        Change link to point to new page location in Section 3

sethostid.3
    Michael Kerrisk
        New link to relocated page in Section 3

glibc.7
    Michael Kerrisk
        New link to new libc.7

Global changes
--------------

syscalls.2
feature_test_macros.7
standards.7
    Michael Kerrisk
        SEE ALSO: add libc(7)

dlopen.3
ld.so.8
    Michael Kerrisk
        SEE ALSO: add rtld-audit(7)

Changes to individual pages
---------------------------

gethostid.2
    Michael Kerrisk
        Move to Section 3
            The interfaces documented in this page are purely glibc.

syscalls.2
    Michael Kerrisk
        Kernel 2.6.28 adds accept4()

clock_getres.3
    Michael Kerrisk
        SEE ALSO: Add pthread_getcpuclockid(3)

fmemopen.3
    Michael Kerrisk
        Fix VERSIONS information

gethostid.3
    Michael Kerrisk
        Before version 2.2, glibc stored the host ID in /var/adm/hostid
            Also: rewrite some text describing the /etc/hostid file, so that
            this location is referred to just once on the page.
    Michael Kerrisk
        RETURN VALUE: describe return value of sethostid()
    Michael Kerrisk
        Added BUGS section noting that ID can't be guaranteed to be unique
    Michael Kerrisk
        Added ERRORS section describing errors for sethostid()
    Michael Kerrisk
        Update section number to reflect relocation into Section 3

printf.3
    Michael Kerrisk
        Source and destination buffers may not overlap for *s*printf()
            http://sourceware.org/bugzilla/show_bug.cgi?id=7075

            Some existing code relies on techniques like the following to
            append text to a buffer:

                $ cat s.c
                #include <stdio.h>
                char buf[80] = "not ";
                main()
                {
                    sprintf(buf, "%sfail", buf);
                puts(buf);
                return 0;
                }

                $ cc s.c
                $ ./a.out
                not fail

            However, the standards say the results are undefined if source
            and destination buffers overlap, and with suitable compiler
            options, recent changes can cause unexpected results:

                $ cc -v 2>&1 | grep gcc
                gcc version 4.3.1 20080507 (prerelease) [gcc-4_3-branch revision 135036] (SUSE Linux)
                $ cc -D_FORTIFY_SOURCE -O2 s.c
                $ ./a.out
                fail

readdir.3
    Michael Kerrisk
        Rewrite text describing 'dirent' fields standardized in POSIX.1
    Michael Kerrisk
        Clarify text for return value/errno setting for end-of-stream case

nscd.8
    Petr Baudis
        Correct NOTES section on reloading configuration files
            It behaved this way at least since
            "Sun Oct 18 15:02:11 1998 +0000",
            some four months after including the nscd implementation
            in glibc. But there does seem to be a short window between
            glibc-2.1 and glibc-2.1.3 when nscd -i was not available,
            I don't think it's worth muddling the point of the page
            with that, though.
top
==================== Changes in man-pages-3.17 ====================

Released: 2009-01-19, Hobart

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Adeodato Simó
Bastien ROUCARIES
Davide Libenzi
Lefteris Dimitroulakis
Mads Martin Joergensen
Marc Lehmann
Martin (Joey) Schulze
Michael Kerrisk
Petr Baudis
Sam Varshavchik
Vegard Nossum

Apologies if I missed anyone!

New and rewritten pages
-----------------------

endian.3
    Michael Kerrisk
        New page documenting byte order conversion functions
            Document functions (new in glibc 2.9) for conversion between
            host byte order and big-/little- endian byte order:
            htobe16(), htole16(), be16toh(), le16toh(),
            htobe32(), htole32(), be32toh(), le32toh(),
            htobe64(), htole64(), be64toh(), le64toh()

getifaddrs.3
    Petr Baudis
        New page documenting getifaddrs(3) and freeifaddrs(3)
            Many edits and changes of Petr's initial draft by mtk

cp1251.7
    Lefteris Dimitroulakis
        New page documenting CP 1251 (Windows Cyrillic) character set

iso-8859-10.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-10 character set

iso_8859-13.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-13 character set

iso_8859-14.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-14 character set

iso_8859-3.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-3 character set

iso_8859-5.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-5 character set

iso_8859-8.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-8 character set

koi8-u.7
    Lefteris Dimitroulakis
        New page documenting KOI8-U character set

Newly documented interfaces in existing pages
---------------------------------------------

epoll.7
    Michael Kerrisk
        Document /proc interfaces for limiting kernel memory usage
            Document the following /proc files that were added in
            Linux 2.6.28:
            /proc/sys/fs/epoll/max_user_instances
            /proc/sys/fs/epoll/max_user_watches

netdevice.7
    Michael Kerrisk
        Document recently added interface flags
            IFF_LOWER_UP (since Linux 2.6.17)
            IFF_DORMANT (since Linux 2.6.17)
            IFF_ECHO (since Linux 2.6.25)

            Documentation taken from comments in <linux/if.h>

New and changed links
---------------------

freeifaddrs.3
    Michael Kerrisk
        New link to new getifaddrs.3

htobe16.3
htole16.3
be16toh.3
le16toh.3
htobe32.3
htole32.3
be32toh.3
le32toh.3
htobe64.3
htole64.3
be64toh.3
le64toh.3
    Michael Kerrisk
        New links to new endian.3

iso-8859-10.7
iso_8859_10.7
latin6.7
    Michael Kerrisk
        New links to new iso_8859-10.7

iso-8859-13.7
iso_8859_13.7
latin7.7
    Michael Kerrisk
        New links to new iso_8859-13.7

iso-8859-14.7
iso_8859_14.7
latin8.7
    Michael Kerrisk
        New links to new iso_8859-14.7

iso-8859-3.7
iso_8859_3.7
latin3.7
    Michael Kerrisk
        New links to new iso_8859-3.7

iso-8859-5.7
iso_8859_5.7
    Michael Kerrisk
        New links to new iso_8859-5.7

iso-8859-8.7
iso_8859_8.7
    Michael Kerrisk
        New links to new iso_8859-8.7

Changes to individual pages
---------------------------

bind.2
    Michael Kerrisk
        SEE ALSO: Add getifaddrs(3)

epoll_create.2
    Michael Kerrisk
        Document EMFILE error
            This error is encountered when the limit imposed by
            /proc/sys/fs/epoll/max_user_instances is encountered.
    Michael Kerrisk
        Clarify distinction between epoll instance and epoll file descriptor
            Reword so that the notion of an epoll instance is made clear,
            and made distinct from the notion of an epoll file descriptor.
            Some other minor rewordings also.

epoll_ctl.2
    Michael Kerrisk
        Reordered parts of the text
    Michael Kerrisk
        Introduce notion of epoll instance
            Introduce notion of epoll instance as distinct from
            epoll file descriptor.  Plus other wording clean-ups.
    Michael Kerrisk
        Document ENOSPC error (new in Linux 2.6.28)
            This error results when the limit imposed by
            /proc/sys/fs/epoll/max_user_watches is encountered.

epoll_wait.2
    Michael Kerrisk
        Introduce the notion of an epoll instance into text

getdents.2
    Michael Kerrisk
        Before kernel < 2.6.4, 'd_type' was effectively always DT_UNKNOWN

gethostid.2
    Michael Kerrisk
        Rename file (was misnamed gethostd.2 in previous release)

getsockname.2
    Michael Kerrisk
        SEE ALSO: Add getifaddrs(3)

signalfd.2
    Michael Kerrisk
        Fix description of fork() semantics
            The page text described the semantics of the initial
            implementation of signalfd().  These were changed early on,
            but the man page wasn't updated.

byteorder.3
    Michael Kerrisk
        SEE ALSO: add endian(3)

longjmp.3
    Michael Kerrisk
        Clarify wording re saving/restoring signal mask
    Michael Kerrisk
        siglongjmp() restores signal mask iff 'savesigs' was non-zero
            Note that siglongjmp() restores signal mask if, and only
            if, 'savesigs' argument of sigsetjmp() was non-zero.  (Previous
            text omitted the "and only if".)

memccpy.3
    Michael Kerrisk
        Fix CONFORMING TO: s/C99/POSIX.1-2001/
    Michael Kerrisk
        If the memory areas overlap, the results are undefined

sethostid.3
    Michael Kerrisk
        Rename file (was misnamed sethostd.3 in previous release)

setjmp.3
    Michael Kerrisk
        Clarify wording re saving/restoring signal mask
    Michael Kerrisk
        Clarify when setjmp() provides BSD vs System V signal mask semantics

strsep.3
    Michael Kerrisk
        BUGS: explicitly list problems afflicting strsep()
            Previously, the page said this function suffered the same
            problems as strtok(), but in fact strsep() doesn't suffer
            from all of the same problems as strtok(), so explicitly
            list just the problems of strsep() in the strsep.3 page.

proc.5
    Michael Kerrisk
        Add pointer to epoll(7) for description of epoll /proc files

epoll.7
    Michael Kerrisk
        Various wording changes to improve clarity and consistency
top
==================== Changes in man-pages-3.18 ====================

Released: 2009-02-10, Christchurch

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
Bastien ROUCARIES
Christian Siebert
Christopher Head
Florentin Duneau
Guillem Jover
Lefteris Dimitroulakis
Lucio Maciel
Michael Kerrisk
Mike Frysinger
Peter Zijlstra
Petr Baudis
Sam Varshavchik
Satyam Sharma
Sebastian Kienzl
Timo Sirainen
Vegard Nossum

Apologies if I missed anyone!

New and rewritten pages
-----------------------

armscii-8.7
    Lefteris Dimitroulakis
        New page documenting ArmSCII-8 character set

iso_8859-11.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-11 character set

iso_8859-4.7
    Lefteris Dimitroulakis
        New page documenting ISO 8859-4 character set

iso_8859-6.7
    Lefteris Dimitroulakis
        New page describing ISO 8859-6 character set

pthread_kill.3
    Michael Kerrisk
        New page documenting pthread_kill(3)

pthread_kill_other_threads_np.3
    Michael Kerrisk
        New page documenting pthread_kill_other_threads_np(3)

pthread_sigmask.3
    Michael Kerrisk
        New page documenting pthread_sigmask(3)

Newly documented interfaces in existing pages
---------------------------------------------

clock_getres.3
    Michael Kerrisk
        Document CLOCK_MONOTONIC_RAW, new in 2.6.28

New and changed links
---------------------

clock_gettime.2
clock_settime.2
clock_getres.3
clock_gettime.3
clock_settime.3
    Michael Kerrisk
        Update links to reflect the fact that clock_* pages are now in
        Section 2

iso-8859-11.7
iso_8859_11.7
    Michael Kerrisk
        New links to new iso_8859-11.7

iso-8859-4.7
iso_8859_4.7
latin4.7
    Michael Kerrisk
        New links to new iso_8859-4.7

iso-8859-6.7
iso_8859_6.7
    Michael Kerrisk
        New links to new iso_8859-6.7

tis-620.7
    Michael Kerrisk
        New link to new iso_8859-11.7

Global changes
--------------

clock_nanosleep.2
getrusage.2
timerfd_create.2
clock.3
clock_getcpuclockid.3
ftime.3
pthread_create.3
pthread_getcpuclockid.3
pthread_tryjoin_np.3
sem_wait.3
time.7
    Michael Kerrisk
        Global fix: Fix xrefs to clock_*.? pages to reflect move to section 2

clock_nanosleep.2
execve.2
fork.2
nanosleep.2
sigaction.2
timerfd_create.2
pthread_getcpuclockid.3
ualarm.3
usleep.3
pthreads.7
time.7
    Michael Kerrisk
        Global fix: s/(3)/(2)/ in section number xrefs for timer_*() API
            The POSIX timers API is implemented (mostly) within the kernel,
            so thse interfaces are system calls.  Although there are as yet
            no man pages, when they are added they should be in Section 2,
            not 3.  Therefore fix those pages that currently refer to these
            interfaces as being in Section 3.

Changes to individual pages
---------------------------

capget.2
    Andi Kleen
        Add some details and relocate a paragraph
            While writing a little program using capset
            I found the capset manpage quite light on crucial
            details and I had to resort to RTFS.

            This patch improves the points I found unclear
            and also moves one misplaced paragraph around.

clock_getres.2
    Michael Kerrisk
        Move page from Section 3 to Section 2

eventfd.2
    Michael Kerrisk
        glibc eventfd() supports the use of eventfd2() since version 2.9

fork.2
    Michael Kerrisk
        SEE ALSO: add daemon(3)

getdents.2
    Michael Kerrisk
        Remove unneeded HAVE_D_TYPE from example program
            Since d_type will always just return DT_UNKNOWN before
            kernel 2.6.4, we don't need to use a conditional for
            determining whether we use this flag.

nanosleep.2
    Michael Kerrisk
        Relocated misplaced BUGS heading

select_tut.2
    Michael Kerrisk
        Clean up error checking in example program (no semantic changes)
    Michael Kerrisk
        Many parts tidied and rewritten
            Remove some redundant text, clarify various pieces,
            tidy example code, etc.
    Michael Kerrisk
        Bug fixes + rewrites in example program
            Sebastien pointed out that the first example program
            wrongly thinks it can count signals.
            Also, some further rewrites by mtk.

socket.2
    Michael Kerrisk
        BUGS: Remove discussion SOCK_UUCP
            As time goes on, this sentence becomes less a piece of humor,
            and more a puzzle.

stat.2
    Michael Kerrisk
        Note that open(O_NOATIME) also causes st_atime not to be updated

timerfd_create.2
    Michael Kerrisk
        Add BUGS noting that timerfd supports fewer clock types than
        timer_create()

btowc.3
    Michael Kerrisk
        SEE ALSO: add wctob(3)

clock_getcpuclockid.3
    Michael Kerrisk
        SEE ALSO: add pthread_getcpuclockid(3)

cos.3
    Michael Kerrisk
        SEE ALSO: add sincos(3)

fexecve.3
    Timo Sirainen
        Note that fexecve() depends on a mounted /proc
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=514043
    Michael Kerrisk
        CONFORMING TO: note addition of fexecve() in POSIX.1-2008
    Michael Kerrisk
        'fd' must be opened read-only and refer to a file that is executable

fmemopen.3
    Michael Kerrisk
        CONFORMING TO: note that these functions are in POSIX.1-2008

getifaddrs.3
    Lucio Maciel
        Fix memory leak in example program
    Petr Baudis
        Various small fixes

getpwnam.3
    Michael Kerrisk
        SEE ALSO: add getspnam(3)

getumask.3
    Michael Kerrisk
        Updated glibc version number in NOTES

ilogb.3
    Michael Kerrisk
        SEE ALSO: add significand(3)

intro.3
    Michael Kerrisk
        SEE ALSO: add libc(7)

isalpha.3
    Michael Kerrisk
        Fix statement that isalpa() is obsolete; should be isascii()
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=512709
    Michael Kerrisk
        SEE ALSO: add toascii(3)

mq_notify.3
    Michael Kerrisk
        Add cross reference to pthread_attr_init(3)

pthread_attr_setaffinity_np.3
    Michael Kerrisk
        SYNOPSIS: Fix declaration of 'attr'

pthread_getcpuclockid.3
    Michael Kerrisk
        SYNOPSIS: fix type of 'thread'

qsort.3
    Michael Kerrisk
        EXAMPLE: remove unnecessary "#include <unistd.h>"

random.3
    Michael Kerrisk
        SEE ALSO: add random_r(3)

remainder.3
    Michael Kerrisk
        SEE ALSO: add div(3)

scandir.3
    Michael Kerrisk
        CONFORMING TO: alphasort() and scandir() are added to POSIX.1-2008
    Michael Kerrisk
        CONFORMING TO: note that versionsort() was added to glibc in
        version 2.1

sem_wait.3
    Michael Kerrisk
        SEE ALSO: add clock_gettime(2)

significand.3
    Michael Kerrisk
        Add CONFORMING TO noting that this function is unstandardized

sigwait.3
    Michael Kerrisk
        Add EXAMPLES section referring to pthread_sigmask(3)

sin.3
    Michael Kerrisk
        SEE ALSO: add sincos(3)

stpcpy.3
    Michael Kerrisk
        Add BUGS section noting the possibility of buffer overruns
    Michael Kerrisk
        Add missing pieces/fix various problems in example program
    Michael Kerrisk
        CONFORMING TO: stpcpy() is nowadays on the BSDs
    Michael Kerrisk
        SEE ALSO: add stpcpy.3

wcscasecmp.3
    Michael Kerrisk
        CONFORMING TO: note that this function is added in POSIX.1-2008

wcsdup.3
    Michael Kerrisk
        CONFORMING TO: note that this function was added in POSIX.1-2008

wcsncasecmp.3
    Michael Kerrisk
        CONFORMING TO: note that this function is added in POSIX.1-2008

wctob.3
    Michael Kerrisk
        SEE ALSO: add btowc(3)

proc.5
    Michael Kerrisk
        Remove mention of epoll/max_user_instances
            (Since this interface appeared in 2.6.28, and then
            disappeared in 2.6.29.)

ascii.7
    Michael Kerrisk
        Update SEE ALSO list to include pages added in 3.17
    Michael Kerrisk
        SEE ALSO: add recently added iso_8859-*(7) pages

epoll.7
    Michael Kerrisk
        remove documentation of /proc/sys/fs/epoll/max_user_instances
            This /proc interface appeared in 2.6.28. but will be
            removed in 2.6.29.

            Also, document change in default value of
            /proc/sys/fs/epoll/max_user_watches (was 1/32 of lowmem,
            now 1/25 of lowmem).

koi8-r.7
    Michael Kerrisk
        SEE ALSO: add koi8-u(7); remove crufty text

standards.7
    Michael Kerrisk
        Update to note that latest POSIX/SUS was ratified in 2008

time.7
    Michael Kerrisk
        SEE ALSO: add pthread_getcpuclockid(3)
top
==================== Changes in man-pages-3.19 ====================

Released: 2009-02-20, Putaruru

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Christian Siebert
Jan Engelhardt
Jens Thoms Toerring
Kir Kolyshkin
Mark Hills
Michael Kerrisk
Parag Warudkar
Peter Zijlstra
Sami Liedes

Apologies if I missed anyone!

New and rewritten pages
-----------------------

timer_create.2
    Michael Kerrisk
        New page documenting timer_create(2)

timer_delete.2
    Michael Kerrisk
        New page documenting timer_delete(2)

timer_getoverrun.2
    Michael Kerrisk
        New page documenting timer_getoverrun(2)

timer_settime.2
    Michael Kerrisk
        New page documenting timer_settime(2) and timer_gettime(2)

New and changed links
---------------------

timer_gettime.2
    Michael Kerrisk
        New link to new timer_settime.2

Global changes
--------------

Various pages
    Kir Kolyshkin
        Trivial punctuation fixes in SEE ALSO
            In SEE ALSO, when a few man pages are referenced, those
            are divided by commas.  Every reference is on a separate
            line, and all lines but the last one should end with
            comma. I spotted one place where there is no comma in
            between references, and mocked up an awk script to find
            similar places:

            for f in man*/*; do
                awk '
                    /^.SH ["]SEE ALSO["]/ {
                        sa=1; print "== " FILENAME " =="; print; next
                    }
                    /^\.(PP|SH)/ {
                        sa=0; no=0; next
                    }
                    /^\.BR/ {
                        if (sa==1) {
                            print;
                            if (no == 1)
                                print "Missing comma in " FILENAME " +" FNR-1; no=0
                        }
                    }
                    /^\.BR .*)$/ {
                        if (sa==1)
                            no=1;
                        next
                    }
                    /\.\\"/ {next}
                    /.*/ {
                        if (sa==1) {
                            print; next
                        }
                    }
                ' $f;
            done | fgrep 'Missing comma'

            This patch fixes all the places found by the above script.

            Also, there is an extra dot at the end of uri.7 "SEE ALSO"
            section.  Removed as per man-pages(7) recommendation.

Changes to individual pages
---------------------------

getitimer.2
clock_getcpuclockid.3
time.7
    Michael Kerrisk
        SEE ALSO: add timer_create(2)

getitimer.2
    Michael Kerrisk
        Rename arguments for consistency with other timer pages
            Also some other minor wording improvements

splice.2
    Mark Hills
        ERRORS: Add EINVAL case for file opened O_APPEND
            Target file cannot be opened in append (O_APPEND) mode

            In kernels prior to v2.6.27 splice() to a file in
            append mode is broken, and since that version it is
            disallowed. It is possible this behaviour may change
            in the future; see the kernel commit message
            (efc968d450e013049a662d22727cf132618dcb2f) for more
            information.

syscalls.2
    Michael Kerrisk
        Note that getpmsg(2) and putmsg(2) are unimplemented
            See See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=514771

timerfd_create.2
    Michael Kerrisk
        ERRORS: add EFAULT

timerfd_create.2
    Michael Kerrisk
        Rename timerfd_settime() 'curr_value' arg to 'old_value'
            For consistency with related pages.

vm86.2
    Parag Warudkar
        CONFORMING TO: Add 32-bit specific
            Note that this call is only on *32-bit* Intel

mq_open.3
    Michael Kerrisk
        ERRORS: add ENOENT error for name == "/"

mq_open.3
    Michael Kerrisk
        ERRORS: Add EACCES error for name containing > 1 slash

sem_open.3
    Michael Kerrisk
        ERRORS: add EINVAL error where name == "/"

sem_open.3
    Jens Thoms Toerring
        Add case of non-well-formed name to ENOENT

shm_open.3
    Michael Kerrisk
        Clarify rules for construction of shared memory object names

proc.5
    Michael Kerrisk
        Add description of /proc/sys/kernel/sysrq
            Reported by: Goerghe Cosorea

proc.5
    Michael Kerrisk
        Put /proc/modules entry in correct alphabetical order

ascii.7
    Kir Kolyshkin
        Fix formatting of tables on second page to use monospaced font

mq_overview.7
    Michael Kerrisk
        Clarify construction rules for message queue object names

sem_overview.7
    Michael Kerrisk
        Clarify construction rules for semaphore object names
            See also http://groups.google.com/group/comp.os.linux.development.apps/browse_thread/thread/b4a67caa765cb65f
top
==================== Changes in man-pages-3.20 ====================

Released: 2009-03-31, Christchurch

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alan Curry
Américo Wang
Andi Kleen
Carlos O'Donell
Chunming Chang
Colin Watson
Eelco Dolstra
Jan Engelhardt
Jens Thoms Toerring
Johannes Stezenbach
Leandro A. F. Pereira
Martin Gebert
Michael Kerrisk
Mike O'Connor
Mike Frysinger
Nikanth Karthikesan
Reuben Thomas
Reuben Thomas
Roland McGrath
Sam Varshavchik
Simon Gomizelj
Tanaka Akira
Teddy Hogeborn
Walter Jontofsohn

Apologies if I missed anyone!

New and rewritten pages
-----------------------

cpuid.4
    Andi Kleen
        New page for cpuid access device

msr.4
    Andi Kleen
        New page documenting x86 CPU MSR access device

Newly documented interfaces in existing pages
---------------------------------------------

proc.5
    Américo Wang
        Document /proc/sys/vm/swappiness
    Michael Kerrisk
        Document /proc/sysrq-trigger

Global changes
--------------

timer_create.2
timer_delete.2
timer_getoverrun.2
timer_settime.2
numa.7
    Michael Kerrisk
        Make source layout of 'Link with' text consistent with other pages
            No actual change to formatted output, but this makes the
            page sources more consistent for the purpose of grepping, etc.

mempcpy.3
signbit.3
significand.3
    Michael Kerrisk
        Global fix: acknowledge FSF in copyright
            These pages are heavily based on original material in
            glibc info pages, but the comments in the source of the pages
            did not acknowledge the FSF copyright on the original material.
            Fix that.

accept.2
read.2
recv.2
send.2
write.2
    Michael Kerrisk
        Fix discussion of EAGAIN/EWOULDBLOCK errors
            For a non-blocking socket, POSIX.1-2001/2008 allow either
            EAGAIN or EWOULDBLOCK to be returned in cases where a call
            would have blocked.  Although these constants are defined
            with the same value on most Linux architectures (PA-RISC
            is the exception), POSIX.1 does not require them to have
            the same value.  Therefore, a portable application using
            the sockets API should test for both errors when checking
            this case.

            (NB POSIX.1 only mentions EWOULDBLOCK in the context of
            the sockets interfaces.)

            Change made after a note cross-posted on linux-arch@vger,
            http://thread.gmane.org/gmane.linux.debian.ports.hppa/5615
            and a suggestion for write(2) from Carlos O'Donell

basename.3
getgrent.3
getgrnam.3
getpwent.3
getpwnam.3
readdir.3
    Michael Kerrisk
        Note that returned pointer should not be given to free()

armscii-8.7
cp1251.7
iso_8859-10.7
iso_8859-11.7
iso_8859-13.7
iso_8859-14.7
iso_8859-15.7
iso_8859-16.7
iso_8859-2.7
iso_8859-3.7
iso_8859-4.7
iso_8859-5.7
iso_8859-6.7
iso_8859-7.7
iso_8859-8.7
iso_8859-9.7
koi8-r.7
koi8-u.7
    Michael Kerrisk
        Add explicit character set encoding to first line of source
            Nowadays mandb has provision to understand a character set
            encoding that is explicitly indicated in the first line
            of the source.  As pointed out by Colin Watson, including
            such an explicit indication on pages encoded in anything
            other than ISO 8859-1 or UTF-8 is useful for man-pages
            that aren't shipped in UTF-8.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519209
            and for some other background (responded to by Colin Watson
            in the above report):
            http://thread.gmane.org/gmane.comp.internationalization.linux/6040
            ("man page encoding", 5 Jul 2005)

Changes to individual pages
---------------------------

fallocate.2
    Michael Kerrisk
        VERSIONS: glibc support is provided since version 2.10

fcntl.2
    Michael Kerrisk
        Remove mention of EWOULDBLOCK from discussion of mandatory locking
            In the kernel, the error on encountering a mandatory lock is
            EAGAIN.  Although EAGAIN and EWOULDBLOCK are the same on
            most Linux architectures, on some they are not, so don't
            mention EWOULDBLOCK as it is misleading.  (Mea culpa.)

getcontext.2
    Michael Kerrisk
        Note that POSIX.1-2008 removes the specification of getcontext()

getitimer.2
    Michael Kerrisk
        Note that POSIX.1-2008 recommends POSIX timers API instead of this API

gettimeofday.2
    Michael Kerrisk
        Note that POSIX.1-2008 recommends clock_gettime() instead of this API

ptrace.2
    Michael Kerrisk
        Note use of 'data' for PTRACE_SYS{CALL,EMU} and PTRACE_*_SINGLESTEP
            These operations use the 'data' argument as a signal number,
            like PTRACE_CONT.

ptrace.2
    Mike Frysinger
        only reference <sys/user.h>
            The kernel no longer installs linux/user.h, so update
            references to sys/user.h.

recv.2
    Michael Kerrisk
        Add 'iovec' defn to defn of 'msghdr' structure
            The 'msghdr' structure includes a field of type 'iovec',
            so show the definition of that structure in this page.

rename.2
    Michael Kerrisk
        Make ENOENT description consistent with POSIX.1-2008

timerfd_create.2
    Michael Kerrisk
        ERRORS: add EINVAL for invalid 'flags' for timer_settime()

truncate.2
    Michael Kerrisk
        SYNOPSIS: Fix description of feature test macro requirements
            After a report by Arvid Norlander.

bcopy.3
    Michael Kerrisk
        Note that POSIX.1-2008 removes specification of bcopy()

bsd_signal.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sigaction(2) instead of this API

ctime.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends strftime(3) instead of these functions

ecvt.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sprintf(3) instead of these functions

gcvt.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sprintf(3) instead of this function

getcwd.3
    Michael Kerrisk
        Note that getcwd() should be used instead of the obsolete getwd()

getgrent.3
    Michael Kerrisk
        Returned buffer may be statically allocated and overwritten by
        later calls

gethostbyname.3
    Michael Kerrisk
        POSIX.1-2008 recommends getaddrinfo(3) and getnameinfo(3) instead

getnetent_r.3
    Michael Kerrisk
        Fix function name in text: s/getnetbynumber_r/getnetbyaddr_r/
            The SYNOPSIS showed the right function name (getnetbyaddr_r),
            but the text repeatedly used the wrong name (getnetbynumber_r).
            Probably, this was a cut-and-paste error.

getpwent.3
    Michael Kerrisk
        Returned buffer may be statically allocated and overwritten by
        later calls

index.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends strchr(3) and strrchr(3) instead

isalpha.3
    Michael Kerrisk
        Explain why POSIX.1-2008 marks isascii(3) obsolete

lockf.3
    Nikanth Karthikesan
        Update pointer to documentation in kernel source

makecontext.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends the use of POSIX threads instead

mq_notify.3
    Michael Kerrisk
        Document the POSIX.1-2008 optional EINVAL error
            POSIX.1-2008 allows an optional EINVAL error if
            notification==NULL and the caller is not currently
            registered to receive notifications.

posix_fallocate.3
    Michael Kerrisk
        Clarify that EINVAL also occurs of 'len' *equals* zero
            See http://bugzilla.kernel.org/show_bug.cgi?id=12919

posix_fallocate.3
    Michael Kerrisk
        Document POSIX.1-2001 and POSIX.1-2008 specifications for EINVAL error
            See http://bugzilla.kernel.org/show_bug.cgi?id=12919

posix_memalign.3
    Michael Kerrisk
        Document handling of size==0 case for posix_memalign()

pthread_exit.3
    Michael Kerrisk
        Fix error in DESCRIPTION: s/pthread_create/pthread_exit/

realpath.3
    Michael Kerrisk
        Rework resolved_path==NULL discussion w.r.t. POSIX.1-200[18]
            Although the page already mentioned the resolved_path==NULL
            feature, and that this feature was added in POSIX.1-2008, there
            was still some crufty text in BUGS that hadn't been updated to
            reflect the POSIX.1-2008 changes.

            Also, some other minor wording and grammar fixes.

scalb.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends scalbln*(3) instead

seekdir.3
    Michael Kerrisk
        SYNOPSIS: Fix type of 'offset' argument: s/off_t/long/
            And add a NOTES section pointing out that 'off_t'
            was indeed used in glibc 2.1.1 and earlier.
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519230

sem_post.3
    Michael Kerrisk
        Document EOVERFLOW error

shm_open.3
    Michael Kerrisk
        Recast discussion on name length to exclude terminating NULL byte
            Probably it's clearer to describe the length of the IPC object
            name as a count that excludes the null terminator.

siginterrupt.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sigaction() instead

sigset.3
    Michael Kerrisk
        Note APIs that POSIX.1-2008 recommends instead of these obsolete APIs

strftime.3
    Michael Kerrisk
        Small fix to description of %G
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=516677

strftime.3
    Michael Kerrisk
        Add details on ISO 8601 week-based dates
            ISO 8602 week-based dates are relevant for %G, %g, and %V,
            and the existing details on these dates are a little thin.

strftime.3
    Michael Kerrisk
        Remove mention of year from ISO 8601 standard
            The text mentioned the 1988 8601 standard, but there have
            already been two revisions of the standard since then, so
            simply remove mention of the year.

telldir.3
    Michael Kerrisk
        SYNOPSIS: Fix return type: s/off_t/long/
            And add a NOTES section pointing out that 'off_t'
            was indeed used in glibc 2.1.1 and earlier.
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519230

timeradd.3
    Michael Kerrisk
        Note that on some systems, <=, >=, == don't work for timercmp()

timeradd.3
    Michael Kerrisk
        SYNOPSIS: Fix return types of timerisset() and timercmp()

toascii.3
    Michael Kerrisk
        Note why POSIX.1-2008 marks this function obsolete

console_ioctl.4
    Alan Curry
        Fix 'argp' type for KDGETLED description
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517485

group.5
    Michael Kerrisk
        Various minor rewordings and improvements

resolv.conf.5
    Michael Kerrisk
        Document 'ip6-bytestring' option

resolv.conf.5
    Michael Kerrisk
        Document 'edns0' option

resolv.conf.5
    Michael Kerrisk
        Document 'ip6-dotint' / 'no-ip6-dotint' option

resolv.conf.5
    Michael Kerrisk
        Note that maximum value of 'ndots' option is capped to 15

resolv.conf.5
    Michael Kerrisk
        Note that maximum value of 'timeout' option is capped to 30

hier.7
    Michael Kerrisk
        Add description of /srv
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=520904

ip.7
    Michael Kerrisk
        Fix type used to declare sin6_port
            The page should use the type specified by POSIX,
            rather than the (equivalent) type used in the kernel

ipv6.7
    Teddy Hogeborn
        Fix types used to declare sin6_family and sin6_port
            The page should use the types specified by POSIX,
            rather than the (equivalent) types used in the kernel.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517074

mq_overview.7
    Michael Kerrisk
        Recast discussion on name length to exclude terminating NULL byte
            Probably it's clearer to describe the length of the IPC object
            name as a count that excludes the null terminator.

rtld-audit.7
    Michael Kerrisk
        Note that multiple libraries in LD_AUDIT doesn't work
            This is reportedly fixed in glibc 2.10.
            See http://sourceware.org/bugzilla/show_bug.cgi?id=9733

sem_overview.7
    Michael Kerrisk
        Fix discussion of length of semaphore names
            Because of the "sem." prefix added by glibc to a semaphore
            name, the limit on the length of the name (excluding the
            terminating null byte) is 251 characters.
top
==================== Changes in man-pages-3.21 ====================

Released: 2009-04-15, Los Gatos

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Frank Dana
Michael Kerrisk
Roman Byshko

Apologies if I missed anyone!

New and rewritten pages
-----------------------

pthread_setconcurrency.3
    Michael Kerrisk
        New page documenting pthread_setconcurrency(3) and
        pthread_getconcurrency(3)

pthread_yield.3
    Michael Kerrisk
        New page documenting pthread_yield(3)

New and changed links
---------------------

pthread_getconcurrency.3
    Michael Kerrisk
        New link to new pthread_setconcurrency(3)

Changes to individual pages
---------------------------

initrd.4
    Michael Kerrisk
        Various minor wording improvements

initrd.4
    Frank Dana
        Add missing word in description

feature_test_macros.7
    Michael Kerrisk
        Update for glibc 2.10 changes to <features.h>
            From glibc 2.10, <features.h> understands the values 200809
            for _POSIX_C_SOURCE and 700 for _XOPEN_SOURCE, and makes
            corresponding changes to defaults for other feature test macros.
    Michael Kerrisk
        Add an example program
            This example program makes it possible to explore what
            feature test macros are set depending on the glibc version
            and the macros that are explicitly set.

ldconfig.8
    Michael Kerrisk
        /etc/ld.so.conf also include libraries found in /lib and /usr/lib
top
==================== Changes in man-pages-3.22 ====================

Released: 2009-07-25, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Adrian Dewhurst
Alexander Lamaison
Bryan Østergaard
Christopher Head
Doug Goldstein
Florentin Duneau
Gokdeniz Karadag
Jeff Moyer
KOSAKI Motohiro
Lucian Adrian Grijincu
Mark Hills
Michael Kerrisk
Mike Frysinger
Petr Baudis
Reimar Döffinger
Ricardo Garcia
Rui Rlex
Shachar Shemesh
Tolga Dalman
ku roi
sobtwmxt

Apologies if I missed anyone!

Changes to individual pages
---------------------------

clone.2
    Michael Kerrisk
        Rewrite crufty text about number of args in older version of clone()
                Some bit rot had crept in regarding the discussion of the
                number of arguments in older versions of this syscall.
                Simplify the text to just say that Linux 2.4 and earlier
                didn't have ptid, tls, and ctid arguments.

                See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=533868
    Michael Kerrisk
        Fix version number for CLONE_NEWIPC
            It's 2.6.19, not 2.4.19.
    Michael Kerrisk
        Fix errors in argument names in text (ptid, ctd)

execve.2
    Mike Frysinger
        Remove erroneous statement that pending signal set is cleared
        on execve(2).

fcntl.2
    Michael Kerrisk
        The kernel source file mandatory.txt is now mandatory-locking.txt
    Michael Kerrisk
        The Documentation/* files are now in Documentation/filesystems

flock.2
    Michael Kerrisk
        Remove unneeded reference to Documentation/mandatory.txt
            Mandatory locks are only implemented by fcntl() locking
    Michael Kerrisk
        The Documentation/* files are now in Documentation/filesystems

fork.2
    Jeff Moyer
        Document fork() behaviour for the Linux native AIO io_context
            It was noted on lkml that the fork behaviour is documented
            for the POSIX AIO calls, but not for the Linux native calls.
            Here is a patch which adds a small blurb that folks will
            hopefully find useful.

            Upon fork(), the child process does not inherit the
            io_context_t data structures returned by io_setup,
            and thus cannot submit further asynchronous I/O or
            reap event completions for said contexts.

getdents.2
    Michael Kerrisk
        The d_type field is fully supported on Btrfs

mount.2
    Michael Kerrisk
        Document MS_STRICTATIME, update description of MS_RELATIME
            Starting with Linux 2.6.30, the MS_RELATIME behavior became
            the default, and MS_STRICTATIME is required to obtain the
            traditional semantics.

poll.2
    Michael Kerrisk
        Remove EBADF error from ERRORS
            As reported by Motohiro:

            "man poll" describe this error code.

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

            but current kernel implementation ignore invalid file descriptor,
            not return EBADF.
            ...

            In the other hand, SUSv3 talk about

            > POLLNVAL
            >  The specified fd value is invalid. This flag is only valid in the
            >  revents member; it shall ignored in the events member.

            and

            > If the value of fd is less than 0, events shall be ignored, and
            > ireevents shall be set to 0 in that entry on return from poll().

            but, no desribe EBADF.
            (see http://www.opengroup.org/onlinepubs/009695399/functions/poll.html)

            So, I think the implementation is correct.

            Why don't we remove EBADF description?

sigaction.2
    Michael Kerrisk
        Expand description of si_utime and si_stime fields of siginfo_t

stat.2
    Michael Kerrisk
        Improve wording of ENOTDIR error

syscalls.2
    Michael Kerrisk
        Add preadv() and pwritev(), new in kernel 2.6.30

wait.2
    Gokdeniz Karadag
        Document CLD_DUMPED and CLD_TRAPPED si_code values

daemon.3
    Michael Kerrisk
        Clarify discussion of 'noclose' and 'nochdir' arguments

ffs.3
    Petr Baudis
        SEE ALSO: add memchr(3)

fmemopen.3
    Petr Baudis
        Relocate BUGS section to correct position
    Petr Baudis
        NOTES: there is no file descriptor associated with the returned stream
            Alexander Lamaison pointed out that this is not obvious
            from the documentation, citing an example with passing the
            FILE * handle to a function that tries to fstat() its
            fileno() in order to determine the buffer size.
    Michael Kerrisk
        CONFORMING TO: remove note that these functions are GNU extensions
            That sentence is now redundant, since these functions
            are added in POSIX.1-2008.

lockf.3
    Michael Kerrisk
        Clarify relationship between fcntl() and lockf() locking

memchr.3
    Petr Baudis
        SEE ALSO: add ffs(3)

readdir.3
    Michael Kerrisk
        The d_type field is fully supported on Btrfs

setjmp.3
    Mike Frysinger
        Fix typo and clarify RETURN description
            The word "signal" was duplicated in NOTES, and the RETURN
            section refers to setjmp() and sigsetjmp(), and mentions
            longjmp(), but not siglongjmp().

strcmp.3
    Petr Baudis
        SEE ALSO: add strverscmp(3)

strcpy.3
    Mark Hills
        SEE ALSO: Add strdup(3)

complex.7
    Michael Kerrisk
        Add missing header file for example program
    Reimar Döffinger
        Fix type used in example code
        man complex (from release 3.18) contains the following code:
            complex z = cexp(I * pi);
        Reading the C99 standard, "complex" is not a valid type,
        and several compilers (Intel ICC, ARM RVCT) will refuse to compile.
        It should be
            double complex z = cexp(I * pi); instead.

environ.7
    Michael Kerrisk
        Note that last element in environ array is NULL
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=528628
    Michael Kerrisk
        Wording fixes

mq_overview.7
    Michael Kerrisk
        Note that mkdir and mount commands here need superuser privilege
    Michael Kerrisk
        Fix example showing contents of /dev/mqueue file

standards.7
    Michael Kerrisk
        Remove references to dated books
            Gallmeister and Lewine are rather old books. Probably,
            there are better books to consult nowadays, and anyway,
            this man page isn't intended to be a bibliography.
top
==================== Changes in man-pages-3.23 ====================

Released: 2009-09-30, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Aaron Gardner
Andrey Vihrov
Christoph Hellwig
Georg Sauthoff
Leslie P. Polzer
Marc Lehmann
Mark Hills
Michael Kerrisk
Mike Frysinger
Nicolas François
Serge Hallyn
Siward de Groot
rui rlex

Apologies if I missed anyone!

Changes to individual pages
---------------------------

execve.2
pipe.2
tee.2
fmemopen.3
mq_notify.3
qsort.3
    Michael Kerrisk
        Replace use of assert() by code that checks argc
            See http://bugzilla.kernel.org/show_bug.cgi?id=13569

            As noted by Andrey:
            The purpose of the assert macro, defined in <assert.h>,
            is to provide a tool to check for programming mistakes
            or program logic errors. However, the assert macro must
            never be used to perform checks for run time errors,
            since, with the NDEBUG macro defined, expressions within
            the assert macro invocations are not evaluated/checked
            for, resulting in behavior that was not originally intended.
            ...
            The pages affected in the core package are

            execve(2)
            pipe(2)
            tee(2)
            fmemopen(3)
            mq_notify(3)
            qsort(3)

getrusage.2
    Michael Kerrisk
        ru_inblock and ru_oublock are now implemented
            These fields of the rusage structure are filled in since
            Linux 2.6.22.

mmap.2
    Michael Kerrisk
        Add brief documentation of MAP_HUGETLB
            This flag is new in 2.6.32, and serves a similar
            purpose to the shmget() SHM_HUGETLB flag.

open.2
    Christoph Hellwig
        add some comments on O_SYNC and friends

poll.2
    Michael Kerrisk
        Clarify wording describing of 'nfds' argument.
            reported by: rui rlex

semctl.2
    Nicolas François
        Remove some redundant words

setpgid.2
    Michael Kerrisk
        Add an explanation of orphaned process groups

splice.2
tee.2
vmsplice.2
    Mark Hills
        Fix return type
            Since glibc 2.7, the return type for these functions
            is ssize_t (formerly it was long).

stat.2
    Nicolas François
        Fix small bug in example program
            Since it is a failure, EXIT_FAILURE looks more appropriate
            than EXIT_SUCCESS.

umount.2
    Michael Kerrisk
        glibc only exposes MNT_DETACH and MNT_EXPIRE since version 2.11
            See http://sourceware.org/bugzilla/show_bug.cgi?id=10092

exit.3
    Michael Kerrisk
        Add a pointer to explanation of orphaned process groups in setpgid(2)

fflush.3
    Michael Kerrisk
        fflush() discards buffered input

ffs.3
    Michael Kerrisk
        Clarify that ffsl() and ffsll() are GNU extensions

getaddrinfo.3
    Michael Kerrisk
        Note nonstandard assumed hints.ai_flags value when hints is NULL
            When hints is NULL, glibc assumes hints.ai_flags is
            AI_V4MAPPED|AI_ADDRCONFIG whereas POSIX says 0.
            According to Ulrich Drepper, glibc's behavior is better.

getmntent.3
    Mike Frysinger
        setmntent() argument is 'filename' not 'fp'
            The description of setmntent() formerly used the wrong
            argument name.

posix_fallocate.3
    Nicolas François
        Fix reference to POSIX.1-2008
            The sentence mentions twice POSIX.1-2001.
            I guess the second one should be POSIX.1-2008.
            This should be checked in the standard.

setenv.3
    Michael Kerrisk
        Improve ERRORS section
            Add ENOMEM error; improve EINVAL description. Also, make
            RETURN VALUE section a little more accurate in its mention
            of errno.

strftime.3
    Nicolas François
        Fix error in description: s/Monday/Thursday/

proc.5
    Nicolas François
        Fix page cross reference
            max_user_watches is better explained in epoll(7) than inotify(7).

proc.5
    Michael Kerrisk
        dmesg is in section 1, not section 8

capabilities.7
    Michael Kerrisk
        FS UID manipulations affect CAP_LINUX_IMMUTABLE and CAP_MKNOD
            Nowadays, file system UID manipulations also affect
            CAP_LINUX_IMMUTABLE (since 2.6.3) and CAP_MKNOD (since 2.6.29).

capabilities.7
    Michael Kerrisk
        Fix version number for CAP_MKNOD in FS UID manipulations
            A recent patch said "since 2.6.29". It should have
            been "since 2.6.30".

capabilities.7
    Nicolas François
        Reword a bad sentence in description of capability bounding set.

mq_overview.7
    Michael Kerrisk
        Change documented ranges for msg_max and msgsize_max
            Linux 2.6.28 changed the permissible ranges for
            these /proc files.

tcp.7
udp.7
    Nicolas François
        Replace references to syctl interfaces with /proc
top
==================== Changes in man-pages-3.24 ====================

Released: 2010-02-25, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
Andries E. Brouwer
Ansgar Burchardt
Bela Lubkin
Bill O. Gallmeister
Christoph Hellwig
Colin Watson
Dan Jacobson
David Howells
Denis Barbier
Doug Manley
Edward Welbourne
Fang Wenqi
Frédéric Brière
Garrett Cooper
Ihar Hrachyshka
Jann Poppinga
Jason Goldfine-Middleton
Jason Noakes
Jonathan Nieder
Kevin
Mark Hills
Markus Peuhkuri
Michael Kerrisk
Michael Witten
Mike Frysinger
Sam Liao
Samy Al Bahra
Stuart Kemp
sunjiangangok
Tobias Stoeckmann
Vlastimil Babka
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

add_key.2
    David Howells
        New page documenting add_key(2)
            Taken from keyutils-1.1 package.

keyctl.2
    David Howells
        New page documenting keyctl(2)
            Taken from keyutils-1.1 package.

request_key.2
    David Howells
        New page documenting request_key(2)
            Taken from keyutils-1.1 package.

Global changes
--------------

Various pages
    Michael Kerrisk
        Global fix: s/non-root/unprivileged/

Various pages
    Michael Kerrisk
        Global fix: s/non-privileged/unprivileged/

Various pages
    Michael Kerrisk
        Global fix:  /non-superuser/unprivileged user/

Various pages
    Michael Kerrisk
        s/non-/non/
            The tendency in English, as prescribed in style guides like
            Chicago MoS, is toward removing hyphens after prefixes
            like "non-" etc.

Various pages
    Michael Kerrisk
        Global fix: s/re-/re/
            The tendency in English, as prescribed in style guides like
            Chicago MoS, is toward removing hyphens after prefixes
            like "re-" etc.

Various pages
    Michael Kerrisk
        Global fix: s/multi-/multi/
            The tendency in English, as prescribed in style guides like
            Chicago MoS, is toward removing hyphens after prefixes
            like "multi-" etc.

Various pages
    Michael Kerrisk
        Global fix: s/pre-/pre/
            The tendency in English, as prescribed in style guides like
            Chicago MoS, is toward removing hyphens after prefixes
            like "pre-" etc.

Various pages
    Michael Kerrisk
        Global fix: s/sub-/sub/
            The tendency in English, as prescribed in style guides like
            Chicago MoS, is toward removing hyphens after prefixes
            like "sub-" etc.

stime.2
time.2
utimensat.2
ctime.3
difftime.3
ftime.3
getspnam.3
mq_receive.3
mq_send.3
rtime.3
sem_wait.3
strftime.3
strptime.3
timeradd.3
rtc.4
core.5
proc.5
icmp.7
time.7
    Michael Witten
        Global fix: Consistently define the Epoch
            All definitions of the Epoch have been refactored to the following:

              1970-01-01 00:00:00 +0000 (UTC)

            That form is more consistent, logical, precise, and internationally
            recognizable than the other variants.

            Also, some wording has been altered as well.

spu_create.2
getopt.3
passwd.5
    Michael Kerrisk
        Global fix: s/non-existing/nonexistent/

faccessat.2
fchmodat.2
fchownat.2
fstatat.2
futimesat.2
linkat.2
mkdirat.2
mknodat.2
openat.2
readlinkat.2
renameat.2
symlinkat.2
unlinkat.2
utimensat.2
mkfifoat.3
    Michael Kerrisk
        Update feature test macro requirements
            Starting in glibc 2.10, defining _XOPEN_SOURCE >= 700,
            or _POSIX_C_SOURCE >= 200809 exposes the declarations of
            these functions.

Changes to individual pages
---------------------------

clock_getres.2
    Michael Kerrisk
        Update text on nonsetabble CLOCK_*_CPUTIME_ID clocks
            SUSv3 permits, but does not require CLOCK_THREAD_CPUTIME_ID and
            CLOCK_PROCESS_CPUTIME_ID to be settable.
            See http://bugzilla.kernel.org/show_bug.cgi?id=11972.

execve.2
    Colin Watson
        Fix description of treatment of caught signals
            Caught signals reset to their default on an execve() (not
            to being ignored).

fcntl.2
    Michael Kerrisk
        s/F_OWNER_GID/F_OWNER_PGRP/
            Peter Zijlstra took the name change I suggested.
    Michael Kerrisk
        Document F_[SG]ETOWN_EX; update details on F_SETOWN
            Linux 2.6.32 adds F_SETOWN_EX and F_GETOWN_EX.
            Linux 2.6.12 changed (broke) the former behavior of
            F_SETOWN with respect to threads.

intro.2
intro.3
    Michael Kerrisk
        Make subsection heading consistent with other intro.? pages
            These pages used "Copyright Terms"; the other intro.? pages
            used "Copyright Conditions". Make these pages like the others.

sendfile.2
    Michael Kerrisk
        Clarify behavior when 'offset' is NULL

seteuid.2
    Michael Kerrisk
        Note unstandardized behavior for effective ID
            POSIX.1 doesn't require that the effective ID can be changed
            to the same value it currently has (a no-op). The man page
            should note this, since some other implementations
            don't permit it.

setgid.2
    Michael Kerrisk
        Fix EPERM error description
            s/effective group ID/real group ID/
            This bug lived in man pages for 15 years before Jason
            spotted it! I checked back in Linux 1.0, and the behavior
            was as the fixed man page describes.

setreuid.2
    Michael Kerrisk
        Add more detail on POSIX.1 specification for these syscalls

setuid.2
    Michael Kerrisk
        Remove crufty statement that seteuid() is not in POSIX
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=569812

stime.2
strftime.3
tzset.3
zic.8
    Michael Witten
        GMT -> UTC (where appropriate)

sync_file_range.2
    Christoph Hellwig
        Add some big warnings re data integrity
            This system call is by design completely unsuitable for any data
            integrity operations.  Make that very clear in the manpage.

CPU_SET.3
    Vlastimil Babka
        SYNOPSIS: Fix return types for CPU_COUNT_*()
            These functions return 'int' not void'.

confstr.3
    Michael Kerrisk
        Fix feature test macro requirements

daemon.3
    Michael Kerrisk
        Fix description of 'nochdir' argument.
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=554819

gethostbyname.3
    Michael Kerrisk
        Document feature test macro requirements for herror() and hstrerror()
            Since glibc 2.8, one of _BSD_SOURCE, _SVID_SOURCE,
            or _GNU_SOURCE is required.

getline.3
    Michael Kerrisk
        Update to reflect that these functions were standardized in POSIX.1-2008

getnameinfo.3
    Michael Kerrisk
        Document feature test macros requirements for NI_MAXHOST and NI_MAXSERV
            Since glibc 2.8, one of _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE
            must be defined to obtain these definitions.

getopt.3
    Jonathan Nieder
        Fix feature test macro requirements

memchr.3
    Michael Kerrisk
        Add feature text macro requirements for memrchr()

nextafter.3
    Michael Kerrisk
        Fix notable error in DESCRIPTION.
        "less than y" should be "less than x".

popen.3
    Michael Kerrisk
        Fix feature test macro requirements

pthread_attr_setdetachstate.3
pthread_attr_setschedparam.3
pthread_attr_setschedpolicy.3
    Denis Barbier
        Argument name is 'attr' not 'thread'
            The function argument was misnamed in the DESCRIPTION on these
            three pages.

rtnetlink.3
    Michael Kerrisk
        Various fixes in example code
            Edward reported a problem in the example code, where a variable
            seems to be misnamed. Upon inspection, there seem to be a few
            such instances, and this patch is my best guess at how things
            should look.

sched_getcpu.3
    Michael Kerrisk
        Place correct header file in SYNOPSIS

sleep.3
    Bill O. Gallmeister
        sleep() puts calling *thread* to sleep (not calling *process*)

sleep.3
    Bill O. Gallmeister
        Add nanosleep(2) to SEE ALSO

strftime.3
    Michael Kerrisk
        %z is defined in SUSv3
            So, substitute "GNU" tag in man page by "SU".

strftime.3
    Michael Witten
        Move 822-compliant date format example to EXAMPLES section
            The RFC 822-compliant date format given in the description
            of `%z' is now moved to the `EXAMPLES' section (note: `EXAMPLE'
            has been renamed `EXAMPLES').

            Furthermore, that format example is now actually
            RFC 822-compliant (using `%y' instead of `%Y') and has been
            qualified as being correct only when in the context of at least
            an English locale. Also, `%T' is used in place of `%H:%M:%S'.

            For completeness, an RFC 2822-compliant format example has been
            similarly added.

strftime.3
    Michael Witten
        Expand introductory text

strftime.3
    Michael Witten
        Clarification of %z specifier

string.3
    Mark Hills
        Add stpcpy() to this list of string functions

strptime.3
    Michael Kerrisk
        Initialize tm structure in example program

undocumented.3
    Michael Kerrisk
        Remove pages now documented
            By now, the following are documented:

                fopencookie(3)
                freeifaddrs(3)
                rawmemchr(3)
                readdir_r(3)
                getutmp(3)
                getutmpx(3)
                utmpxname(3)

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=554819

group.5
    Michael Kerrisk
        s/passwd/password/
            The page inconsistently used "passwd" and "password"
            to refer to the same field.

capabilities.7
    Michael Kerrisk
        Update securebits discussion to use SECBIT_* flags

feature_test_macros.7
    Michael Kerrisk
        _POSIX_C_SOURCE >= 200808 defines _ATFILE_SOURCE
            Since glibc 2.10, _POSIX_C_SOURCE >= 200808 defines _ATFILE_SOURCE

path_resolution.7
    Michael Kerrisk
        Add readlink(2) to SEE ALSO
    Michael Kerrisk
        Fix NAME line
            The poorly constructed part preceding "\-" causes apropos
            not to be able to find the subject.

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=558300

signal.7
    Michael Kerrisk
        Fix discussion of SIGUNUSED
            Clarify that this signal really is synonymous with SIGSYS.
            See http://bugzilla.kernel.org/show_bug.cgi?id=14449
top
==================== Changes in man-pages-3.25 ====================

Released: 2010-06-20, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alexander E. Patrakov
Andi Kleen
Andrew Klossner
André Goddard Rosa
Bo Borgerson
Christian Franke
Daisuke HATAYAMA
David Sommerseth
Denis Barbier
Eric Blake
Fang Wenqi
Francesco Cosoleto
Gernot Tenchio
Hugh Dickins
Ivana Hutarova Varekova
Jan Blunck
Jan Engelhardt
Jan Kara
Jeff Barry
Manfred Schwarb
Mark Hills
Martin (Joey) Schulze
Michael Kerrisk
Mihai Paraschivescu
Mike Frysinger
Miklos Szeredi
Petr Baudis
Petr Gajdos
Petr Uzel
Pierre Habouzit
Reuben Thomas
Rob Landley
Robert Wohlrab
Serge E. Hallyn
Tolga Dalman
Tom Swigg
Walter Harms
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

migrate_pages.2
    Andi Kleen
        New page documenting migrate_pages(2).
            Andi's text based on the move_pages.2 page;
            additional edits by mtk.
            migrate_pages(2) was new in Linux 2.6.16.

quotactl.2
    Jan Kara
        Major updates
            Update the page to consolidate information from the
            outdated man-pages quotactl.2 page and the quotactl.2
            page in the "quota-tools" pachage. The page in "quota-tools"
            has now been dropped by Jan Kara, so that there is just one
            canonical quotactl.2 page (in pan-pages).
    Michael Kerrisk
            Various other pieces added to the page by mtk.

Newly documented interfaces in existing pages
---------------------------------------------

fcntl.2
    Michael Kerrisk
        Document F_SETPIPE_SZ and F_GETPIPE_SZ
            These commands, new in kernel 2.6.35, set and get the capacity
            of pipes.

madvise.2
    Andi Kleen
        Document MADV_HWPOISON
    Michael Kerrisk
        Added documentation of MADV_MERGEABLE and MADV_UNMERGEABLE
            These flags (used for Kernel Samepage Merging, KSM)
            are new in 2.6.32.
    Andi Kleen
        Document MADV_SOFT_OFFLINE
            This operation was added in Linux 2.6.33.

mmap.2
    Michael Kerrisk
        Document MAP_UNINITIALIZED flag
            New in Linux 2.6.33.

prctl.2
    Andi Kleen
        Document the hwpoison prctls in 2.6.32

sched_setscheduler.2
    Michael Kerrisk
        Document SCHED_RESET_ON_FORK
            New in Linux 2.6.32

umount.2
    Michael Kerrisk
        Document UMOUNT_NOFOLLOW
            New in Linux 2.6.34.

mkstemp.3
    Michael Kerrisk
        Document mkstemps() and mkostemps()
            These functions are new in glibc 2.11. They allow the template
            string to include a suffix after the "XXXXXX" string.

proc.5
    Michael Kerrisk
        Document /proc/sys/vm/memory_failure_early_kill
            New in 2.6.32. Description based on the text in
            Documentation/sysctl/vm.txt.
    Michael Kerrisk
        Document /proc/sys/vm/memory_failure_recovery
            New in Linux 2.6.32.  Description based on the text in
            Documentation/sysctl/vm.txt.
    Michael Kerrisk
        Document /proc/sys/fs/pipe-max-size

socket.7
    Jan Engelhardt
        Document SO_DOMAIN and SO_PROTOCOL
            These read-only socket options were new in Linux 2.6.32.

New and changed links
---------------------

fstatvfs.2
    Michael Kerrisk
        Adjust link to point to Section 3

fstatvfs.3
statvfs.2
    Michael Kerrisk
        New link to page relocated to Section 3

mkstemps.3
mkostemps.3
    Michael Kerrisk
        New links to mkstemp.3
            mkstemp.3 now describes mkstemps(3) and mkostemps(3).

timer_create.2
timer_delete.2
timer_getoverrun.2
timer_settime.2
getline.3
    Michael Kerrisk
        Add 'L' to constants in feature test macro specifications
            Be consistent with POSIX, which uses constants such as 200809L.

Global changes
--------------

open.2
sync_file_range.2
umount.2
    Michael Kerrisk
        Global fix: s/filesystem/file system/

Changes to individual pages
---------------------------

fcntl.2
    Michael Kerrisk
        Note that glibc 2.11 papers over the kernel F_GETOWN bug
            Since version 2.11, glibc works around the kernel limitation for
            process groups IDs < 4096 by implementing F_GETOWN via F_GETOWN_EX.

futex.2
    Michael Kerrisk
        Various fixes in SEE ALSO

getpriority.2
nice.2
    Francesco Cosoleto
        Move renice from section 8 to section 1

getrusage.2
    Mark Hills
        Add ru_maxrss
            See kernel commit 1f10206.
    Mark Hills
        Description of maintained fields
            These descriptions are taken from NetBSD 5.0's getrusage(2).
    Michael Kerrisk
        Enhanced description of various fields

mlock.2
    Michael Kerrisk
        /proc/PID/status VmLck shows how much memory a process has locked
            After a note from Tom Swigg, it seems sensible mention VmLck here.

mount.2
    Petr Uzel
        Fix incorrect path

move_pages.2
    Andi Kleen
        Clarify includes/libraries

mremap.2
    Michael Kerrisk
        Clarify existence of fifth argument.

msgctl.2
semctl.2
shmctl.2
    Francesco Cosoleto
        Move ipcs from section 8 to section 1

open.2
    Michael Kerrisk
        Remove ambiguity in text on NFS and O_EXCL.

poll.2
    Michael Kerrisk
        Fix discussion of ppoll() timeout argument
            1. Rename ppoll)(_ argument to "timeout_ts" to distinguish it
               from the poll() argument in the text.
            2. More accurately describe the poll() call that is equivalent
               to ppoll().

posix_fadvise.2
    Michael Kerrisk
        Add sync_file_range(2) under SEE ALSO

prctl.2
    Michael Kerrisk
        Correct PR_SET_KEEPCAPS description
            The "keep capabilities" flag only affects the treatment of
            permitted capabilities, not effective capabilities.
            Also: other improvements to make the PR_SET_KEEPCAPS text clearer.

select_tut.2
    Michael Kerrisk
        Fix bug in example program

sigaction.2
    Michael Kerrisk
        Add TRAP_BRANCH and TRAP_HWBKPT to si_code values for SIGTRAP
    Michael Kerrisk
        Rearrange text describing fields set by sigqueue(2)
    Michael Kerrisk
        Add details for signals sent by POSIX message queue notifications
    Michael Kerrisk
        Improve description of various siginfo_t fields
    Michael Kerrisk
        Add some details for SIGTRAP and si_trapno
    Andi Kleen
        Document hwpoison signal extensions

statfs.2
    Michael Kerrisk
        Bring statfs struct type declarations closer to glibc reality
    Fang Wenqi
        Add definition EXT4_SUPER_MAGIC = 0xEF53
    Michael Kerrisk
        Document f_frsize field.

statvfs.2
    Michael Kerrisk
        Move this page to section 3 (since it's a library call)

swapon.2
    Ivana Hutarova Varekova
        Note effect of CONFIG_MEMORY_FAILURE on MAX_SWAPFILES
            From 2.6.32, MAX_SWAPFILES is decreased by 1 if the kernel is
            built with CONFIG_MEMORY_FAILURE.

syscalls.2
    Michael Kerrisk
        Bring system call list up to date with Linux 2.6.33
    Michael Kerrisk
        Fix kernel version number for utimes()

cproj.3
    Michael Kerrisk
        Note fix for C99 conformance in glibc 2.12.

crypt.3
    Petr Baudis
        Correct note on key portion significance
            As Marcel Moreaux notes:

                The Linux manpage for crypt()[1] contains the following
                statement as the last sentence of the NOTES section:

                    In the SHA implementation the entire key is significant
                    (instead of only the first 8 bytes in MD5).

                It should probably say "DES" where it says "MD5" (and maybe
                "MD5/SHA" where it says "SHA"), because in MD5 password hashing,
                the entire key is significant, not just the first 8 bytes.

            This patch fixes the wording.

fmemopen.3
    Michael Kerrisk
        Bug fix in example program

ftw.3
    Michael Kerrisk
        Note that if 'fn' changes CWD, the results are undefined
    Michael Kerrisk
        Clarify description of fpath argument
            As reported by Pierre Habouzit, 'fpath' is not relative
            to 'dirpath'. It is either relative to the calling process's
            current working directory (if 'dirpath' was relative), or it
            is absolute (if 'dirpath' was absolute).

getaddrinfo.3
    Christian Franke
        Fix a field name mixup: s/ai_family/ai_flags/

getline.3
    Robert Wohlrab
        Remove unneeded check before free()
            The manpage of getline shows an example with an extra NULL pointer
            check before it calls free. This is unneeded according to free(3):

                 If ptr is NULL, no operation is performed.

            This patch removes the "if" check.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572508

log.3
log10.3
log2.3
    Jan Engelhardt
        Add cross-references to other-base logarithmic functions

opendir.3
    Petr Baudis
        Specify feature test macro requirements for fdopendir(3)
            Currently, there is no note on the fact that fdopendir() is
            POSIX.2008-only.

openpty.3
    Eric Blake
        Use const as appropriate
    Michael Kerrisk
        Note glibc version that added "const" to function arguments
    Michael Kerrisk
        Explicitly note that these functions are not in POSIX

resolver.3
    Michael Kerrisk
        Fix declaration of dn_comp() in SYNOPSIS
            Remove the second 'exp_dn' from the calling signature.

termios.3
    Michael Kerrisk
        Change NOFLSH text to speak of characters, not signals

core.5
    Michael Kerrisk
        Update description of coredump_filter
            Kernel 2.6.24 added MMF_DUMP_ELF_HEADERS.
            Kernel 2.6.28 added MMF_DUMP_HUGETLB_PRIVATE and
            MMF_DUMP_HUGETLB_SHARED.

elf.5
    Daisuke HATAYAMA
        Document PN_XNUM extension
            In linux-2.6.34-rc1, an ELF core extension was added; user-land
            tools manipulating ELF core dump such as gdb and binutils has
            already been modified before; so elf.5 needs to be modified
            accordingly.

            You can follow information on the ELF extension via the LKML post:
            http://lkml.org/lkml/2010/1/3/103
            Date        Mon, 04 Jan 2010 10:06:07 +0900 (JST)
            Subject     ... elf coredump: Add extended numbering support

            This Linux-specific extension was added in kernel 2.6.34.

            Reviewed-by: Petr Baudis

    Michael Kerrisk
        Remove EI_BRAND
            As reported by Yuri Kozlov  and confirmed by Mike Frysinger,
            EI_BRAND is not in GABI
            (http://www.sco.com/developers/gabi/latest/ch4.eheader.html)
            It looks to be a BSDism
    Michael Kerrisk
        Remove words under '.note': "described below"
            The existing text is broken, because there is
            no '"Note Section" format' describe below. Simplest
            solution is to remove the words "described below".

filesystems.5
    Jeff Barry
        Add discussion of ntfs and ext4

proc.5
    Michael Kerrisk
        Simplify description of /proc/sys and /proc/sys/fs
            In the description of these directories, there's no need
            to list all the files and subdirectories that they contain;
            that information is provided by the entries that follow.

services.5
    Yuri Kozlov
        Remove crufty reference to nonexistent BUGS section

capabilities.7
    Michael Kerrisk
        Document CAP_SYS_RESOURCE and F_SETPIPE_SZ
            With CAP_SYS_RESOURCE, a process can increase pipe capacity above
            /proc/sys/ps/pipe-max-size.
    Michael Kerrisk
        Add get_robust_list() info under CAP_SYS_PTRACE
    Michael Kerrisk
        Add MADV_HWPOISON under CAP_SYS_ADMIN

signal.7
    Michael Kerrisk
        Make a clearer statement about nonportable aspect of signal(2)
            Make a clearer statement that signal(2) is less portable for
            establishing a signal handler.

socket.7
    Michael Kerrisk
        Use consistent language to describe read-only socket options

udp.7
    Michael Kerrisk
        Add FIONREAD warning.
            Warn that FIONREAD can't can't distinguish case of a zero-length
            datagram from the case where no datagrams are available.
top
==================== Changes in man-pages-3.26 ====================

Released: 2010-09-04, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Alexander Shishkin
Brian Sutin
Denis Barbier
Guillem Jover
Jianhua Li
Linus Nilsson
Lenaic Huard
mac@mcrowe.com
Martin Schulze
Maxin John
Michael Kerrisk
Nicholas Hunt
Peng Haitao
Peter Stuge
Przemyslaw Szczepaniak
Scott Walls
TAN Yee Fan
Wu Fengguang
Yitzchak Gale
Yuri Kozlov

Apologies if I missed anyone!

Newly documented interfaces in existing pages
---------------------------------------------

eventfd.2
    Michael Kerrisk
        Document EFD_SEMAPHORE
            Document the EFD_SEMAPHORE flag, added in kernel 2.6.30.
            Also restructured some parts of the text to fit with the
            addition of the EFD_SEMAPHORE text.

Global changes
--------------

getaddrinfo.3
getipnodebyname.3
st.4
    Michael Kerrisk
        s/logical OR/bitwise OR/

Changes to individual pages
---------------------------

clock_nanosleep.2
    Michael Kerrisk
        Fix discussion of return value when interrupted by a signal

epoll_ctl.2
    Yuri Kozlov
        Small fix to types in data structures

eventfd.2
    Alexander Shishkin
        Clarified close-on-exec behavior

madvise.2
    Michael Kerrisk
        Improve discussion of MADV_SOFT_OFFLINE

mkdir.2
    Michael Kerrisk
        Add EMLINK error to ERRORS

mq_getsetattr.2
mq_close.3
mq_getattr.3
mq_notify.3
mq_send.3
mq_unlink.3
    Lnac Huard
        Fix return type in SYNOPSIS (s/mqd_t/int/)

recv.2
send.2
    Michael Kerrisk
        Remove obsolete reference to glibc version in NOTES

recv.2
send.2
    Nicholas Hunt
        Adjust type shown for msg_controllen to glibc reality
            This patch fixes the type of msg_controllen in the struct msghdr
            definition given in send.2 and recv.2 to match the definition in
            glibc and the kernel.

select.2
    Michael Kerrisk
        Update NOTES on old glibc pselect()
            Make it clear that modern glibc uses the kernel pselect()
            on systems where it is available.
            See https://bugzilla.kernel.org/show_bug.cgi?id=14411

statfs.2
    Guillem Jover
        Fix copy & paste error for __SWORD_TYPE definition

sysfs.2
    Michael Kerrisk
        Clarify that this syscall is obsolete.
            And strengthen recommendation to use /proc/filesystems instead.

write.2
    Michael Kerrisk
        Add EDESTADDRREQ error

a64l.3
    Peng Haitao
        Fix error in NOTES, s/a64l/l64a/

error.3
    Linus Nilsson
        Change "perror" to "strerror" in DESCRIPTION of error()

mq_send.3
    Michael Kerrisk
        Fix EAGAIN description (s/empty/full)

initrd.4
    Yuri Kozlov
        Fix IP address in explanation of NFS example

tzfile.5
    Michael Kerrisk
        Add information on version 2 format timezone files
            Updated using information from the tzcode 2010l release at
            ftp://elsie.nci.nih.gov/pub.
            (It's an open question whether or not a version of tzfile.5
            should live independently in man-pages. It was added to the
            man-pages set many years ago. For now, I'll follow a
            conservative course that causes least pain to downstream,
            by continuing to maintain a separate copy in man-pages.)

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594219
top
==================== Changes in man-pages-3.27 ====================

Released: 2010-09-22, Nuernberg

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

caishuxian@gmail.com
Denis Barbier
Denis Silakov
der Mouse
Jan Kratochvil
Jim Belton
Jiri Olsa
KOSAKI Motohiro
Mark Hills
Matthew Flaschen
Michael Kerrisk
Ozgur Gurcan
Petr Baudis
Remi Denis-Courmont
Tanaka Akira
Tim Stoakes
W. Trevor King
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

sigevent.7
    Petr Baudis, Michael Kerrisk
        New page to centralize description of sigevent structure
            Several interfaces use this structure. Best to centralize the
            common details in one place. Content taken from the existing
            timerfd_create.2 and mq_open.3 pages, with additions by
            Petr Baudis and Michael Kerrisk.

Newly documented interfaces in existing pages
---------------------------------------------

ip.7
    Jiri Olsa
        Document IP_NODEFRAG
            This option is new in Linux 2.6.36

unix.7
    Michael Kerrisk
        Document SIOCINQ ioctl() operation

Global changes
--------------

_exit.2
brk.2
chdir.2
chmod.2
chown.2
chroot.2
clock_nanosleep.2
getdtablesize.2
gethostname.2
getpagesize.2
getsid.2
killpg.2
mknod.2
mknodat.2
posix_fadvise.2
pread.2
readlink.2
setpgid.2
setreuid.2
sigaltstack.2
stat.2
symlink.2
sync.2
truncate.2
vfork.2
wait.2
wait4.2
a64l.3
abs.3
acos.3
acosh.3
asin.3
asinh.3
atan.3
atan2.3
atanh.3
atoi.3
cbrt.3
ceil.3
clock_getcpuclockid.3
copysign.3
cos.3
cosh.3
dirfd.3
div.3
dprintf.3
ecvt.3
erf.3
erfc.3
exp.3
exp2.3
expm1.3
fabs.3
fdim.3
fexecve.3
ffs.3
floor.3
fma.3
fmax.3
fmemopen.3
fmin.3
fmod.3
fpclassify.3
frexp.3
fwide.3
gamma.3
gcvt.3
getcwd.3
getdate.3
getgrent.3
gethostid.3
getpass.3
getpwent.3
getsubopt.3
getw.3
hypot.3
ilogb.3
insque.3
isalpha.3
isgreater.3
iswblank.3
j0.3
j0.3
ldexp.3
lockf.3
log.3
log10.3
log1p.3
log2.3
logb.3
lrint.3
lround.3
mbsnrtowcs.3
mkdtemp.3
mkstemp.3
mktemp.3
modf.3
mq_receive.3
mq_send.3
nan.3
nextafter.3
posix_fallocate.3
posix_memalign.3
pow.3
printf.3
qecvt.3
random.3
realpath.3
remainder.3
remquo.3
rint.3
rint.3
round.3
scalb.3
scalbln.3
scanf.3
siginterrupt.3
signbit.3
sigset.3
sin.3
sinh.3
sqrt.3
stpcpy.3
stpncpy.3
strdup.3
strdup.3
strnlen.3
strsignal.3
strtod.3
strtol.3
strtoul.3
tan.3
tanh.3
tgamma.3
trunc.3
ttyslot.3
ualarm.3
usleep.3
wcpcpy.3
wcpncpy.3
wcscasecmp.3
wcsdup.3
wcsncasecmp.3
wcsnlen.3
wcsnrtombs.3
wprintf.3
    Michael Kerrisk
        Add/fix/update feature test macro requirements in SYNOPSIS
            Various changes to:
            * Update feature test requirements to note changes in
              recent glibc releases
            * Correct errors in feature test macro requirements
            * Add feature test macro requirements to pages where
              the requirements were not previously stated.

accept.2
clone.2
dup.2
fallocate.2
pipe.2
readahead.2
sched_setaffinity.2
unshare.2
CPU_SET.3
endian.3
euidaccess.3
fexecve.3
getpt.3
getpw.3
getumask.3
getutmp.3
gnu_get_libc_version.3
makedev.3
matherr.3
mbsnrtowcs.3
memfrob.3
pthread_attr_setaffinity_np.3
pthread_getattr_np.3
pthread_setaffinity_np.3
pthread_tryjoin_np.3
tcgetsid.3
wcscasecmp.3
wcsncasecmp.3
wcsnlen.3
wcsnrtombs.3
wcswidth.3
rtld-audit.7
    Michael Kerrisk
        SYNOPSIS: Add reference to feature_test_macros(7)
            These pages specify feature test macros in the function
            prototypes. Add a reference to feature_test_macros(7),
            so that readers are pointed to the information that
            feature test macros must be defined before including
            *any* header file.

clock_nanosleep.2
clock_getcpuclockid.3
getnetent_r.3
getprotoent_r.3
getrpcent_r.3
getservent_r.3
sigwait.3
    Michael Kerrisk
        RETURN VALUE: Note that "positive error numbers" are listed in ERRORS

fcntl.2
intro.2
open.2
poll.2
ftw.3
intro.3
matherr.3
system.3
tmpnam.3
unix.7
    Michael Kerrisk
        Note that feature test macros must be defined before *any* includes
            Programmers often make the mistake of including a feature test
            macro only after having already included some header files.
            This patch adds some text at opportune places to remind
            programmers to do things the right way.

index.3
stpcpy.3
strcasecmp.3
strcat.3
strchr.3
strcmp.3
strcoll.3
strcpy.3
strdup.3
strfry.3
strpbrk.3
strsep.3
strspn.3
strstr.3
strtok.3
strxfrm.3
    Michael Kerrisk
        SEE ALSO: Add reference to string(3)
            The idea here is to provide a route to discover other
            string functions.

armscii-8.7
cp1251.7
iso_8859-3.7
iso_8859-5.7
iso_8859-6.7
iso_8859-8.7
iso_8859-10.7
iso_8859-11.7
iso_8859-13.7
iso_8859-14.7
koi8-u.7
    Denis Barbier
        Fix decimal values in encoding tables
            Octal and hexadecimal values are right, but there are some
            off-by one errors in decimal values.  Correct values are
            printed by this command:

              perl -pi -e 'if (s/^([0-7]+)\t([0-9]+)\t([0-9a-fA-F]+)//)
                {printf "%03o\t%d\t%s", hex($3), hex($3), $3;};' man7/*.7

Changes to individual pages
---------------------------

capget.2
    Michael Kerrisk
        SYNOPSIS: Remove unneeded "undef _POSIX_SOURCE"

fcntl.2
    Michael Kerrisk
        Add feature test macro requirements for F_GETOWN and F_SETOWN

fcntl.2
    Michael Kerrisk
        Note feature test macro requirements for F_DUPFD_CLOEXEC

getrlimit.2
    Michael Kerrisk
        Document units for RLIMIT_RTTIME limit
            This limit is in microseconds

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=596492

lseek.2
    Michael Kerrisk
        Removed note about return type on ancient systems

mount.2
    Michael Kerrisk
        Definitions of various MS_* constants only appeared in glibc 2.12
            See http://sourceware.org/bugzilla/show_bug.cgi?id=11235

stat.2
    Michael Kerrisk
        Update information on nanosecond timestamp fields
            Update feature test macro requirements for exposing these fields.
            Note that these fields are specified in POSIX.1-2008.

timer_create.2
    Michael Kerrisk
        Factor out generic material that was moved to new sigevent(7) page

aio_fsync.3
    Michael Kerrisk
        Add reference to new sigevent(7) page

atanh.3
    Michael Kerrisk
        glibc 2.10 fixed pole error bug
            http://sourceware.org/bugzilla/show_bug.cgi?id=6759
            was resolved.

cerf.3
    Michael Kerrisk
        Make it clearer that this function is unimplemented

cos.3
    Michael Kerrisk
        errno is now correctly set to EDOM on a domain error
            http://sources.redhat.com/bugzilla/show_bug.cgi?id=6780
            was (silently) resolved.

expm1.3
    Michael Kerrisk
        errno is now correctly set to ERANGE on a range error
            http://sources.redhat.com/bugzilla/show_bug.cgi?id=6788
            was (silently) resolved.

fmod.3
    Michael Kerrisk
        errno is now correctly set to EDOM for the x==inf domain error
            http://sources.redhat.com/bugzilla/show_bug.cgi?id=6784
            was (silently) resolved.

insque.3
    Michael Kerrisk
        Noted prev == NULL bug in glibc 2.4 and earlier
            As noted by Remi Denis-Courmont, glibc nowadays allows
            'prev' to be NULL, as required by POSIX for initializing
            a linear list. But in glibc 2.4 and earlier, 'prev' could
            not be NULL. Add a BUGS section noting this.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=551201
    Michael Kerrisk
        Added info on circular lists, and initializing circular lists
    Michael Kerrisk
        Added example program

lgamma.3
    Michael Kerrisk
        glibc 2.10 fixed pole error bug
            http://sourceware.org/bugzilla/show_bug.cgi?id=6777
            was (silently) resolved.

log2.3
    Matthew Flaschen
        log2() function does not conform to C89
            log2(), log2f(), and log2l() do not conform to C89.
            They are defined in C99.  See http://flash-gordon.me.uk/ansi.c.txt
            and http://www.schweikhardt.net/identifiers.html

mq_notify.3
    Michael Kerrisk
        Factor out generic material that was moved to new sigevent(7) page

pow.3
    Michael Kerrisk
        errno is now correctly set to ERANGE on a pole error
            http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776
            was (silently) resolved.

pthread_kill_other_threads_np.3
    Michael Kerrisk
        CONFORMING TO: Note meaning of "_np" suffix

rand.3
    Michael Kerrisk
        Clarify description of range of returned value
    Michael Kerrisk
        Add an example program
    Michael Kerrisk
        Expand description of rand_r()

random.3
    W. Trevor King
        Update initstate() return value description to match glibc

readdir.3
    Michael Kerrisk
        Clarify that "positive error numbers" are listed in ERRORS
            Reported-by fkater@googlemail.com

rexec.3
    Michael Kerrisk
        SYNOPSIS: Add header file and feature test macro requirements

sigpause.3
    Michael Kerrisk
        Correct discussion of when BSD vs SysV version is used in glibc

sin.3
    Michael Kerrisk
        errno is now correctly set to EDOM on a domain error
            http://sources.redhat.com/bugzilla/show_bug.cgi?id=6781
            was (silently) resolved.

tan.3
    Michael Kerrisk
        errno is now correctly set to EDOM on a domain error
            http://sources.redhat.com/bugzilla/show_bug.cgi?id=6782
            was (silently) resolved.

wcscasecmp.3
wcsncasecmp.3
wcsnlen.3
    Michael Kerrisk
        Added VERSIONS section

boot.7
    Yuri Kozlov
        Update list of major Linux distributions

feature_test_macros.7
    Michael Kerrisk
        Make text on required placement of macros more prominent
            Move the text that notes the requirement that feature test macros
            must be defined before including any header files to the top of
            the page, and highlight the text further, so that the reader will
            not miss this point.

pthreads.7
signal.7
    Michael Kerrisk
        Add SEE ALSO reference to new sigevent(7) page

tcp.7
    Michael Kerrisk
        Clarify header file details for SIOCINQ and SIOCOUTQ
            Also note synonymous FIONREAD and TIOCOUTQ.
top
==================== Changes in man-pages-3.28 ====================

Released: 2010-10-04, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andries E. Brouwer
Denis Barbier
Jan Kara
Landijk
Lennart Poettering
Michael Haardt
Michael Kerrisk
Petr Baudis
Sam Varshavchik

Apologies if I missed anyone!

New and rewritten pages
-----------------------

getaddrinfo_a.3
    Petr Baudis
        New page documenting getaddrinfo_a()
            The page also documents gai_suspend(), gai_cancel(),
            and gai_error().

aio.7
    Michael Kerrisk
        New page providing an overview of POSIX asynchronous I/O

Newly documented interfaces in existing pages
---------------------------------------------

exec.3
    Michael Kerrisk
        Document execvpe()
            This function was added to glibc in version 2.11.
            Also various other small rewrites in the page.

New and changed links
---------------------

gai_cancel.3
gai_error.3
gai_suspend.3
    Petr Baudis
        New links to new getaddrinfo_a.3 page

error_one_per_line.3
    Michael Kerrisk
         Fix misnamed link file (was error_on_per_line.3)

execvpe.3
    Michael Kerrisk
        New link to exec.3

sigstack.3
    Michael Kerrisk
        New link to sigaltstack.2
            No new programs should use sigstack(3). Point the user to the
            better sigalstack(2), whose man page briefly mentions sigstack(3).

vlimit.3
    Michael Kerrisk
        New link to getrlimit.2
            No new programs should use vlimit(3). Point the user to the
            better setrlimit(2), whose man page briefly mentions vlimit(3).

vtimes.3
    Michael Kerrisk
        New link to getrusage.2
            No new programs should use vtimes(3). Point the user to the
            better getrusage(2), whose man page briefly mentions vtimes(3).

Global changes
--------------

Various pages
    Michael Kerrisk
        Switch to American usage: "-wards" ==> "-ward"
            American English uses "afterward" in preference to "afterwards",
            and so on

chdir.2
chmod.2
chown.2
gethostname.2
getsid.2
pread.2
setpgid.2
sigaltstack.2
stat.2
truncate.2
wait.2
dirfd.3
getsubopt.3
mkdtemp.3
mkstemp.3
siginterrupt.3
strdup.3
    Michael Kerrisk
        Simplify feature test macro requirements

Changes to individual pages
---------------------------

getrlimit.2
    Michael Kerrisk
        Add mention of the ancient vlimit() function

getrusage.2
    Michael Kerrisk
        Add mention of the ancient vtimes() function

io_cancel.2
io_destroy.2
io_getevents.2
io_setup.2
io_submit.2
    Michael Kerrisk
        SEE ALSO: add aio(7)

sched_setscheduler.2
    Michael Kerrisk
        ERRORS: note that NULL 'param' yields EINVAL

stat.2
    Michael Kerrisk
        Note feature test macro requirements for blkcnt_t and blksize_t

timer_create.2
    Michael Kerrisk
        Standardize on name 'sevp' for sigevent argument

truncate.2
    Michael Kerrisk
        Correct and simplify ftruncate() feature test macro requirements
            The glibc 2.12 feature test macro requirements for ftruncate() are
            buggy; see http://sourceware.org/bugzilla/show_bug.cgi?id=12037.
            Corrected the requirements in the SYNOPSIS, and added a BUGS
            section describing the problem in glibc 2.12.

aio_cancel.3
    Michael Kerrisk
        Add pointer to aio(7) for example program
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

aio_error.3
    Michael Kerrisk
        Wording improvements in RETURN VALUE
        Add pointer to aio(7) for example program
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

aio_fsync.3
    Michael Kerrisk
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

aio_read.3
    Michael Kerrisk
        Various minor rewordings and additions
        Add pointer to sigevent(7) for details of notification of I/O completion
        Add pointer to aio(7) for example program
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

aio_return.3
    Michael Kerrisk
        Improve description in RETURN VALUE
        Add pointer to aio(7) for example program
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

aio_suspend.3
    Michael Kerrisk
        Various additions and rewordings.
            Give some arguments more meaningful names.
            More explicitly describe the 'nitems' argument.
            Explicitly note that return is immediate if an I/O operation
            has already completed.
            Note that aio_error(3) should be used to scan the aiocb list
            after a successful return.
            Add references to other relevant pages.
            Various other pieces rewritten.
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

aio_write.3
    Michael Kerrisk
        Add pointer to sigevent(7) for details of notification of I/O completion
        Various minor rewordings and additions
        Refer the reader to aio(7) for a description of the aiocb structure
        CONFORMING TO: Add POSIX.1-2008; add VERSIONS section

clearenv.3
    Michael Kerrisk
        Fix error in feature test macro requirements

dysize.3
    Michael Kerrisk
        Remove crufty statement about old SCO bug

exec.3
    Michael Kerrisk
        Add feature test macro requirements for execvpe()
        Rewrite description of PATH and mention _CS_PATH
        Note execvp() and execlp() behavior for filename containing a slash

getaddrinfo.3
    Michael Kerrisk
        Add SEE ALSO reference to new getaddrinfo_a.3 page

gethostbyname.3
    Michael Kerrisk
        Fix formatting of feature test macros

getw.3
    Michael Kerrisk
        Fix feature test macros

malloc.3
    Landijk
        Remove editorializing comments on memory overcommitting
            See https://bugzilla.kernel.org/show_bug.cgi?id=19332
    Michael Kerrisk
        Various minor reorganizations and wording fix-ups

mq_notify.3
    Michael Kerrisk
        Standardize on name 'sevp' for sigevent argument

nl_langinfo.3
    Michael Haardt
        Make it clear that nl_langinfo() interacts with setlocale()
        Add an example program

posix_openpt.3
    Michael Kerrisk
        Fix feature test macro requirements

rand.3
    Michael Kerrisk
        Remove duplicate #include in example program

strtok.3
    Petr Baudis
        Add reference to strtok() example in getaddrinfo(3)

inotify.7
    Michael Kerrisk
        Added section noting limitations and caveats of inotify

sigevent.7
    Michael Kerrisk
        Add SEE ALSO reference to new getaddrinfo_a.3 page
        Add SEE ALSO referring to new aio(7) page

suffixes.7
    Michael Kerrisk
        Change explanation of ".rpm" to "RPM software package"
top
==================== Changes in man-pages-3.29 ====================

Released: 2010-10-19, Detroit

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Balazs Scheidler
David Prevot
Denis Barbier
Guillem Jover
Ivana Varekova
Lennart Poettering
Michael Kerrisk
Sam Varshavchik
Simon Paillard
Stephan Mueller
Thomas Jarosch
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

subpage_prot.2
    Michael Kerrisk
        New page documenting the PowerPC-specific subpage_prot(2)

aio_init.3
    Michael Kerrisk
        New page documenting aio_init(3)

Newly documented interfaces in existing pages
---------------------------------------------

posix_fadvise.2
    Michael Kerrisk
        Document the architecture-specific arm_fadvise64_64() system call
            This ARM-specific system call fixes the argument ordering
            for that architecture. Since Linux 2.6.14.

sync_file_range.2
    Michael Kerrisk
        Document the architecture-specific sync_file_range2() system call
            As described in commit edd5cd4a9424f22b0fa08bef5e299d41befd5622,
            the sync_file_range() argument order is broken for some
            architectures (PowerPC, ARM, tile). The remedy was a different
            system call using the right argument order on those architectures.

psignal.3
    Guillem Jover
        Document psiginfo()
            psiginfo() was added to glibc in version 2.10.
    Michael Kerrisk
        Add details, VERSIONS, and BUGS for psiginfo()

ip.7
    Balazs Scheidler
        Document IP_RECVORIGDSTADDR
        Document IP_TRANSPARENT
    Michael Kerrisk
        Document IP_FREEBIND
            Text based on input from Lennart Poettering and Balazs Scheidler.
            See https://bugzilla.kernel.org/show_bug.cgi?id=20082

New and changed links
---------------------

arm_fadvise64_64.2
    Michael Kerrisk
        New link to posix_fadvise.2

arm_sync_file_range.2, sync_file_range2.2
    Michael Kerrisk
        New links to sync_file_range.2

arrm_fadvise.2
    Michael Kerrisk
        New link to posix_fadvise.2

psiginfo.3
    Guillem Jover
        New link to psignal.3

Global changes
--------------

Many pages
    Michael Kerrisk
        global fix: s/Unix/UNIX/
            The man pages were rather inconsistent in the use of "Unix"
            versus "UNIX". Let's go with the trademark usage.

Various pages
    Michael Kerrisk
        Global fix: s/pseudo-terminal/pseudoterminal/

grantpt.3, ptsname.3, unlockpt.3, pts.4
    Michael Kerrisk
        Global fix: s/pty/pseudoterminal/

recv.2, cmsg.3, unix.7
    Michael Kerrisk
        global fix: s/UNIX socket/UNIX domain socket/

fmtmsg.3, gethostbyname.3, termios.3
    Michael Kerrisk
        Global fix: s/Unixware/UnixWare/

Changes to individual pages
---------------------------

inotify_rm_watch.2
    Michael Kerrisk
        SYNOPSIS: fix type of 'wd' argument

posix_fadvise.2
    Michael Kerrisk
        Rewrite VERSIONS, noting that the system call is fadvise64()

syscalls.2
    Michael Kerrisk
        Add the PowerPC-specific subpage_prot() system call
        Add sync_file_range2()

truncate.2
    Michael Kerrisk
        Fix feature test macros

aio_cancel.3
aio_error.3
aio_fsync.3
aio_read.3
aio_return.3
aio_suspend.3
aio_write.3
    Michael Kerrisk
        SEE ALSO: Add lio_listio(3)

gai_cancel.3
gai_error.3
gai_suspend.3
    Michael Kerrisk
        Make these into links
            In the previous release, these files were accidentally made copies
            of getaddrinfo_a.3, instead of being made as link files.

getifaddrs.3
    Thomas Jarosch
        Prevent possible NULL pointer access in example program

malloc.3
    Michael Kerrisk
        Emphasize that malloc() and realloc() do not initialize allocated memory

malloc_hook.3
    Ivana Varekova
        Warn that these functions are deprecated

strcpy.3
    Michael Kerrisk
        Formatting fixes in strncpy() example implementation code

ip.7
    Michael Kerrisk
        Reword NOTES on Linux-specific options

sigevent.7
    Michael Kerrisk
        SEE ALSO: Add aio_read(3), aio_write(3), and lio_listio(3)

unix.7
    Michael Kerrisk
        Document the autobind feature
    Michael Kerrisk
        Fix description of abstract socket names
            As reported by Lennart Poettering:
                The part about "abstract" sockets is misleading as it suggests
                that the sockaddr returned by getsockname() would necessarily
                have the size of sizeof(struct sockaddr), which however is not
                the case: getsockname() returns exactly the sockaddr size that
                was passed in on bind(). In particular, two sockets that are
                bound to the same sockaddr but different sizes are completely
                independent.
            See https://bugzilla.kernel.org/show_bug.cgi?id=19812
    Michael Kerrisk
        Fix description of "pathname" sockets
            As reported by Lennart Poettering:
               The part about "pathname" sockets suggests usage of
               sizeof(sa_family_t) + strlen(sun_path) + 1
               for calculating the sockaddr size. Due to alignment/padding
               this is probably not a good idea. Instead, one should use
               offsetof(struct sockaddr_un, sun_path) + strlen() + 1
               or something like that.
            See https://bugzilla.kernel.org/show_bug.cgi?id=19812
top
==================== Changes in man-pages-3.30 ====================

Released: 2010-11-01, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
Bernhard Walle
David Prevot
Eric W. Biederman
Florian Lehmann
Jan Engelhardt
Lucian Adrian Grijincu
Michael Kerrisk
Paul Mackerras
PÃ¡draig Brady
Reuben Thomas
scarlettsp
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

kexec_load.2
    Andi Kleen
        New page documenting kexec_load(2)
    Michael Kerrisk
        Add license
    Michael Kerrisk
        Incorporate fixes from Eric W. Biederman
            Eric noted that a few instances of "virtual" should
            be "physical" and noted:

                There is an expectation that at hand off from sys_kexec that
                virtual and physical addresses will be identity mapped. But
                this isn't the old Alpha booting convention where you have
                a virtual address and then you have to parse the page table
                to figure out where your kernel was actually loaded.
    Michael Kerrisk
        Additions and edits by mtk
            Various wording and layout improvements.
            Fixed the name of a constant: s/KEXEC_ARCH_I386/KEXEC_ARCH_386/.
            Added RETURN VALUE and ERRORS sections.
            Added VERSIONS section
            Note that CONFIG_KEXEC is needed
            Removed details of using syscall; the reader can find them in
            syscall(2).
            Added some details for KEXEC_PRESERVE_CONTEXT.
            Revised the text mentioning the kernel header, since it is
            not yet exported, and it's not certain that it will be.

lio_listio.3
    Michael Kerrisk
        New page documenting lio_listio(3)

Newly documented interfaces in existing pages
---------------------------------------------

reboot.2
    Andi Kleen
        Document LINUX_REBOOT_KEXEC
            Some fix-ups by Michael Kerrisk
    Michael Kerrisk
        Place 'cmd' values in alphabetical order.

unshare.2
    Michael Kerrisk
        Document CLONE_NEWIPC
    Michael Kerrisk
        Document CLONE_NEWNET
    Lucian Adrian Grijincu
        Improve description of CLONE_NEWNET
            CLONE_NEWNET creates a new network namespace from scratch.
            You don't have anything from the old network namespace in
            the new one. Even the loopback device is new.
    Michael Kerrisk
        Document CLONE_SYSVSEM
    Michael Kerrisk
        Document CLONE_NEWUTS
    Michael Kerrisk
        Relocate discussion of CAP_SYS_ADMIN to CLONE_NEWNS section
            And rewrite the EPERM description to be more general in
            preparation for the new flags to be documented.

Global changes
--------------

Various pages
    Michael Kerrisk
        Add reference to feature_test_macros(7)
            Some pages simply list feature test macro requirements in
            the form:

                #define #GNU_SOURCE
                #include <someheader.h>

            For these pages, add a "See feature_test_macros(7)" comment
            on the "#define" line.

Various pages
    Michael Kerrisk
        SEE ALSO: Remove redundant reference to feature_test_macros(7)

Various pages
    David Prevot
        Use greater consistency in NAME line
        (Remove definite article at start of descriptive clause.)

Various pages
    Michael Kerrisk
        SEE ALSO: Place entries in correct order

Various pages
    Michael Kerrisk
        ERRORS: Place entries in correct order

Various pages
    Michael Kerrisk
        Add section number to references to functions documented in other pages

Various pages
    Michael Kerrisk
        Remove redundant section number in page references
            Remove section number in function references that are for
            functions documented on this page.

armscii-8.7
iso_8859-3.7
iso_8859-4.7
iso_8859-5.7
iso_8859-6.7
iso_8859-10.7
iso_8859-11.7
iso_8859-13.7
iso_8859-14.7
koi8-u.7
    David Prevot
        Capitalize hexadecimal numbers

Changes to individual pages
---------------------------

access.2
    Michael Kerrisk
        Note use of faccessat(2) for checking symbolic link permissions
    Michael Kerrisk
        Give an example of a safer alternative to using access()

clone.2
    Michael Kerrisk
        Clarify when CLONE_NEWNET implementation was completed

faccessat.2
    Michael Kerrisk
        Note that faccessat() is racy

fcntl.2
    Michael Kerrisk
        RETURN VALUE: Improve description of F_GETFD and F_GETFL

inotify_add_watch.2
    Michael Kerrisk
        Document ENOENT error

mlock.2
    Michael Kerrisk
        Improve wording describing /proc/PID/status /VmLck field
    Michael Kerrisk
        shmctl() SHM_LOCKed memory is not included in VmLck

reboot.2
    Michael Kerrisk
        Place 'cmd' values in alphabetical order

subpage_prot.2
    Michael Kerrisk
        Change 1-line page description
    Michael Kerrisk
        Improvements after review by Paul Mackerras

timer_settime.3
    Michael Kerrisk
        Remove redundant SEE ALSO reference

euidaccess.3
    Michael Kerrisk
        Note the use of faccessat(2) to operate on symbolic links
    Michael Kerrisk
        Note that the use of euidaccess() is racy

fenv.3
    Michael Kerrisk
        Clarify wording relating to glibc version

getgrent.3
getgrent_r.3
getgrnam.3
    Michael Kerrisk
        Refer reader for group(5) for more info on group structure

getopt.3
    Bernhard Walle
        Use constants in getopt_long() example
            The description of getopt_long() mentions the constants
            required_argument, no_argument and optional_argument.
            Use them in the example to make the code easier to understand.

getpw.3
    Michael Kerrisk
        Change comment describing pw_gecos

getpw.3
getpwent.3
getpwent_r.3
    Michael Kerrisk
        Refer reader to passwd(5) for more info on the passwd structure

getpwent.3
getpwnam.3
    Michael Kerrisk
        Note that pw_gecos is not in POSIX
            And change the comment describing this field

getpwent_r.3
    Michael Kerrisk
        Change comment describing pw_gecos

getpwnam.3
    Michael Kerrisk
        Some rewording and restructuring

sched_getcpu.3
    Michael Kerrisk
        Fix feature test macro requirements

strnlen.3
    Michael Kerrisk
        Fix feature test macro requirements

group.5
    Michael Kerrisk
        Various minor rewordings

hosts.5
protocols.5
spufs.7
termio.7
    David Prevot
        Remove definite article from NAME section
            Please find inline another tiny patch in order to shrink
            the definite article from some other pages (found with
            "rgrep -i ' \\\- the' man*").

passwd.5
    Michael Kerrisk
        Various minor rewordings

proc.5
    Michael Kerrisk
        Add reference to mlock(2) for further info on /proc/PID/status VmLck

armscii-8.7
    David Prevot
        Write the character set name as ArmSCII

cp1251.7
    David Prevot
        Capitalize hexadecimal numbers

ip.7
    David Prevot
        Fix name of socket option: s/IP_TTL/IP_TRANSPARENT/
    David Prevot
        Place socket options in alphabetical order

koi8-r.7
    David Prevot
        Fix special character names
            Comparing to koi8-u.7, I noticed some inconsistencies in special
            character names. After checking with the following Unicode related
            pages, please find inline (and gzipped attached, hopefully not
            messing with encoding), a patch in order to make it right, on an
            Unicode point of view.

            http://www.unicode.org/charts/PDF/U2500.pdf
            http://www.unicode.org/charts/PDF/U25A0.pdf
            http://www.unicode.org/charts/PDF/U0080.pdf
            http://www.unicode.org/charts/PDF/U1D400.pdf
    David Prevot
        Fix SEE ALSO reference and letter names
            The koi8-r(7) (Russian Net Character Set) manual page refers
            to iso-8859-7(7) manual page, which is the Latin/Greek one.
            I guess it should refer instead to the iso-8859-5(7)
            (Latin/Cyrillic) one. This is addressed at the end of the patch.

            It has also been spotted that letter names are different in
            this manual page and in the Unicode related page [0], the
            first part of the page address this.

                    0: http://www.unicode.org/charts/PDF/U0400.pdf

man-pages.7
    Michael Kerrisk
        Update example
            The old example used the chmod(2) man page, but the
            feature test macro requirements on that page had changed.
            Update to use an example from a different page (acct(2),
            whose feature test macro requirements are probably unlikely
            to change in the future).
top
==================== Changes in man-pages-3.31 ====================

Released: 2010-11-12, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

Andi Kleen
David Prevot
Denis Barbier
Krzysztof Å»elechowski
Michael Kerrisk
Yuri Kozlov

Apologies if I missed anyone!

Newly documented interfaces in existing pages
---------------------------------------------

getrlimit.2
    Michael Kerrisk
        Added documentation of prlimit()
            prlimit() is new in kernel 2.6.36.

inotify.7
    Michael Kerrisk
        Document IN_EXCL_UNLINK
            This flag was added in Linux 2.6.36.
            See kernel commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6.

New and changed links
---------------------

prlimit.2
    Michael Kerrisk
        New link to getrlimit.2

Changes to individual pages
---------------------------

getrlimit.2
    Michael Kerrisk
        Remove unneeded text in DESCRIPTION

intro.2
    Michael Kerrisk
        Added various pages to SEE ALSO

kexec_load.2
    Michael Kerrisk
        Add kernel version where KEXEC_PRESERVE_CONTEXT first appeared
        Added kernel version number where KEXEC_ON_CRASH first appeared
        Fix copyright
            Make copyright in the name of Intel corporation
        VERSIONS: Fix version number
            kexec_load() was first implemented in 2.6.13, though the entry
            in the system call table was reserved starting in 2.6.7.

migrate_pages.2
    Michael Kerrisk
        SEE ALSO: Add reference to Documentation/vm/page_migration

sched_setaffinity.2
    Michael Kerrisk
        Add missing word "real" to "user ID"

syscalls.2
    Michael Kerrisk
        Fix kernel version number for kexec_load
            kexec_load() was first implemented in 2.6.13, though the entry
            in the system call table was reserved starting in 2.6.7.
    Michael Kerrisk
        Add prlimit() to list

intro.3
    Michael Kerrisk
        Added various pages to SEE ALSO

printf.3
    Michael Kerrisk
        Formatting fixes in example code

hostname.7
    Michael Kerrisk
        Small improvement to description of domains
            See: https://bugzilla.novell.com/show_bug.cgi?id=651900
top
==================== Changes in man-pages-3.32 ====================

Released: 2010-12-03, Munich

Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

A. Costa
Denis Barbier
Emil Mikulic
Eugene Kapun
Hugh Dickins
Ivana Hutarova Varekova
Joern Heissler
Lars Wirzenius
Martin Eberhard Schauer
Michael Kerrisk
Petr Uzel
Roger Pate
Török Edwin
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

pthread_sigqueue.3
    Michael Kerrisk
        New page documenting ptrhead_sigqueue()
            pthread_sigqueue() is new in glibc 2.11 (requires a kernel with
            rt_tgsigqueinfo(), added in Linux 2.6.31).

Newly documented interfaces in existing pages
---------------------------------------------

readv.2
    Michael Kerrisk
        Add documentation of preadv() and pwritev()
            The preadv() and pwritev() system calls were added in
            Linux 2.6.30.

New and changed links
---------------------

preadv.2
    Michael Kerrisk
        New link to readv.2

pwritev.2
    Michael Kerrisk
        New link to readv.2

Changes to individual pages
---------------------------

chdir.2
    Michael Kerrisk
        Remove redundant and incorrect info on FTMs from NOTES

chown.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

clock_nanosleep.2
    Michael Kerrisk
        Clarify that clock_nanosleep() suspends the calling *thread*

epoll_create.2
    Michael Kerrisk
        Note that 'size' argument must be greater than 0
            See https://bugzilla.kernel.org/show_bug.cgi?id=23872
    Michael Kerrisk
        Added VERSIONS section

epoll_ctl.2
    Michael Kerrisk
        Added VERSIONS section

epoll_wait.2
    Michael Kerrisk
        Updated VERSIONS section

fcntl.2
    Michael Kerrisk
        Add notes on fcntl64()

fstatat.2
    Michael Kerrisk
        Add NOTES on fstatat64(), the name of the underlying system call

getdents.2
    Michael Kerrisk
        Added notes on getdents64()

getgid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

getgroups.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

getpagesize.2
    Michael Kerrisk
        Improve description of getpagesize()
            Improve description of getpagesize() and relocate discussion
            of sysconf(_SC_PAGESIZE).

            In part inspired by
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=537272

getresuid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

getrlimit.2
    Michael Kerrisk
        Add example program for prlimit()

getuid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

open.2
    Ivana Hutarova Varekova
        O_EXCL can be used without O_CREAT for block devices
            Since Linux 2.6 there is a possibility to use O_EXCL without
            O_CREAT. See patch: http://lkml.org/lkml/2003/8/10/221.

pread.2
    Michael Kerrisk
        Add notes on pread64() and pwrite64()
            See https://bugzilla.kernel.org/show_bug.cgi?id=23072
    Michael Kerrisk
        SEE ALSO: add readv(3)

readv.2
    Michael Kerrisk
        Wording fix: readv() and writev() are system calls, not functions

sendfile.2
    Michael Kerrisk
        Add notes on sendfile64()

setfsgid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

setfsuid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

setgid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

setresuid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

setreuid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

setuid.2
    Michael Kerrisk
        Add NOTES explaining 32-bit system calls added in Linux 2.4

sigqueue.2
pthreads.7
signal.7
    Michael Kerrisk
        SEE ALSO: Add pthread_sigqueue(3)

stat.2
    Michael Kerrisk
        Fix EOVERFLOW error description
            2<<31 should read 1<<31 (which equals 2^31).

statfs.2
    Michael Kerrisk
        Add notes on statfs64() and fstatfs64()

swapon.2
    Hugh Dickins
        Document SWAP_FLAG_DISCARD and discarding of swap pages

truncate.2
    Michael Kerrisk
        Add notes on truncate64() and ftruncate64()

memcpy.3
    Michael Kerrisk
        Change "should not overlap" to "must not overlap"
            glibc 2.12 changed things so that applications that use memcpy() on
            overlapping regions will encounter problems. (The standards have
            long said that the behavious is undefined if the memory areas
            overlap.)

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=603144
            In reference of http://lwn.net/Articles/414467/
            and http://article.gmane.org/gmane.comp.lib.glibc.alpha/15278

usleep.3
    Petr Uzel
        usleep() suspends calling thread, not process

core.5
    Michael Kerrisk
        Change single quote to double quote in shell session example
            The example section has a sample shell session containing:

            echo '|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s'

            But $PWD won't be expanded in single quotes. It should be double
            quotes around the entire argument or some other form.

pthreads.7
    Michael Kerrisk
        Added description of async-cancel-safe functions

unix.7
    Michael Kerrisk
        Reworded the text of various errors
    Michael Kerrisk
        Added ENOENT error
top
==================== Changes in man-pages-3.33 ====================

Released: 2011-09-16, Munich

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes and ideas that have been
incorporated in changes in this release:

Akira Fujita
Alexander Schuch
Andries Brouwer
Brian M. Carlson
Dan Jacobson
Folkert van Heusden
Graham Gower
Hendrik Jan Thomassen
Jan Engelhardt
Joey Adams
Johannes Laire
Jon Grant
Josh Triplett
Konstantin Ritt
Luis Javier Merino
Michael Kerrisk
Mike Frysinger
Mikel Ward
Nick Black
Paul Evans
Petr Pisar
Przemyslaw Pawelczyk
Regid Ichira
Reuben Thomas
Richard B. Kreckel
Ryan Mullen
Sebastian Geiger
Sebastian Unger
Seonghun Lim
Serge E. Hallyn
Simon Cross
Simon Paillard
Stan Sieler
Timmy Lee
Tolga Dalman
Tomislav Jonjic
Yuri Kozlov
Wei Luosheng

Apologies if I missed anyone!

Newly documented interfaces in existing pages
---------------------------------------------

sync.2
    Michael Kerrisk
        Added new syncfs() system call
            syncfs() was added in Linux 2.6.39.

New and changed links
---------------------

syncfs.2
    Michael Kerrisk
        New link for sync(2).

Global changes
--------------

Various pages
    Simon Paillard
        Global fix:  properly escape minus sign

Changes to individual pages
---------------------------

clone.2
    Michael Kerrisk
        Note that CLONE_STOPPED was removed in 2.6.38

execve.2
    Michael Kerrisk  [Sebastian Geiger]
        Note that the first argv[] value should contain name of executable

fcntl.2
    Michael Kerrisk  [Reuben Thomas]
        Note that F_GETFL also retrieves file access mode

getrlimit.2
    Michael Kerrisk  [Ryan Mullen]
        Remove mention of kernel versions in discussion of RLIMIT_CPU
    Michael Kerrisk  [Seonghun Lim]
        Fix example program and add _FILE_OFFSET_BITS requirement

mlock.2
    Michael Kerrisk  [Brian M. Carlson]
        Clarify EINVAL error
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?625747
    Michael Kerrisk  [Seonghun Lim]
        Simplify and correct text for EPERM error

mprotect.2
    Seonghun Lim
        Fix off-by-one error in a memory range
    Seonghun Lim
        Fix small bug in example program
            The description of the example program says that it makes the
            third page "read-only". Thus use PROT_READ instead of PROT_NONE.

open.2
    Folkert van Heusden
        Remove text describing O_CLOEXEC as Linux-specific
            O_CLOEXEC is specified in POSIX.1-2008, as noted
            elsewhere in the page.

readlink.2
    Michael Kerrisk  [Dan Jacobson]
        SEE ALSO: Add readlink(1)

sendfile.2
    Akira Fujita
        Since 2.6.33, 'out_fd' can refer to any file type
            Linux kernel commit cc56f7de7f00d188c7c4da1e9861581853b9e92f
            meant sendfile(2) can work with any output file.
    Michael Kerrisk
        Shift text on falling back to read()/write() to NOTES
    Michael Kerrisk  [Tolga Dalman]
        Remove mention of kernel version for 'in_fd' argument
    Tolga Dalman
        Add an explicit reference to splice(2)
            Unlike sendfile(), splice() can transfer data
            between a pair of sockets.

sigaction.2
    Michael Kerrisk  [Tolga Dalman]
        Add a little info about ucontext_t

stat.2
    Michael Kerrisk  [Jon Grant]
        Small rewording of ENAMETOOLONG error

sync.2
    Michael Kerrisk
        Some rewrites to description of sync()

syscalls.2
    Michael Kerrisk
        Added fanotify_init() and fanotify_mark() to syscall list
    Michael Kerrisk
        Added new 2.6.39 system calls
    Michael Kerrisk
        Updated for Linux 3.0 system calls
    Michael Kerrisk
        Update kernel version at head of syscall list
    Michael Kerrisk
        Update to mention 3.x kernel series

syslog.2
    Michael Kerrisk  [Serge E. Hallyn]
        Update for kernel 2.6.37 changes
            Document /proc/sys/kernel/dmesg_restrict.
            Document CAP_SYSLOG.

time.2
    Michael Kerrisk  [Alexander Schuch]
        NOTES: Fix description of "Seconds since the Epoch"

timerfd_create.2
    Michael Kerrisk  [Josh Triplett]
        Note behavior when timerdfd_settime() old_value is NULL
        See http://bugs.debian.org/cgi-bin/bugreport.cgi?641513
    Tomislav Jonjic
        Fix small error in description of timerfd_settime()

truncate.2
    Seonghun Lim
        Remove redundant EINTR description

unlink.2
    Hendrik Jan Thomassen
        Improve EBUSY description

cacos.3
cacosh.3
catan.3
catanh.3
    Michael Kerrisk  [Richard B. Kreckel, Andries Brouwer]
        Fix formula describing function
            The man pages for cacos(), cacosh(), catan(), catanh()
            contain incorrect formulae describing the functions.

cacos.3
    Michael Kerrisk
        Add example program

cacosh.3
    Michael Kerrisk
        Add example program

cacosh.3
casinh.3
catan.3
catanh.3
    Michael Kerrisk
        SEE ALSO: Add reference to inverse function

catan.3
    Michael Kerrisk
        Add example program

catanh.3
    Michael Kerrisk
        Add example program

ccos.3
ccosh.3
csin.3
csinh.3
ctan.3
ctanh.3
    Michael Kerrisk
        SEE ALSO Add reference to "arc" inverse function

cexp.3
    Michael Kerrisk
        SEE ALSO: add cexp(3)

clog.3
    Michael Kerrisk
        SEE ALSO: Add reference to clog(2)

crypt.3
    Michael Kerrisk  [Jan Engelhardt]
        Fix header file and feature test macro requirements for crypt_r()

err.3
    Seonghun Lim
        Clean up description of error message source
            In the second paragraph of DESCRIPTION section, one of the
            sources of error messages is incorrect: the four functions obtain
            error message only from errno, and "a code" is just relevant
            with errc() and warnc(), which are not present on Linux.
            see http://www.unix.com/man-page/freebsd/3/ERR/ .

            Then, the third paragraph becomes a duplicate.

fflush.3
    Regid Ichira
        Fix wording error
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?614021

hsearch.3
    Seonghun Lim
        Update ERRORS section
            EINVAL can occur for hdestroy_r().
            EINVAL can't occur for hcreate().
            Other minor fixes.

lockf.3
    Michael Kerrisk  [Mikel Ward]
        ERRORS: EBADF can also occur for nonwritable file descriptor
            As noted in the DESCRIPTION, the file descriptor must be writable
            in order to place a lock.

malloc.3
    Seonghun Lim
        Reorder prototypes in SYNOPSIS
            calloc() comes before realloc() in the other sections,
            so should do in SYNOPSIS, too.

mbstowcs.3
    Michael Kerrisk
        SEE ALSO: add reference to wcstombs(3)

memcmp.3
    Michael Kerrisk  [Sebastian Unger]
        Clarify that comparison interprets bytes as "unsigned char"

realpath.3
    Michael Kerrisk  [Seonghun Lim]
        Fix EINVAL error
            Since glibc 2.3, resolved_path can be non-NULL (with the
            semantics already documented in the page).

scandir(3)
    Mike Frysinger
        Add ENOENT/ENOTDIR errors

siginterrupt.3
    Michael Kerrisk  [Luis Javier Merino]
        Remove misleading sentence about signal(2) and system call interruption

strlen.3
    Michael Kerrisk  [Jon Grant]
        SEE ALSO: Add strnlen(3)

strnlen.3
    Michael Kerrisk  [Jon Grant]
        CONFORMING TO: Note that strnlen() is in POSIX.1-2008

strtoul.3
    Michael Kerrisk  [Tolga Dalman]
        Fix NOTES section constants

termios.3
    Michael Kerrisk
        Use "terminal special characters" consistently throughout page
    Michael Kerrisk  [Paul Evans]
        Add documentation of _POSIX_VDISABLE
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=627841
    Michael Kerrisk
        Add a description of STATUS character
    Michael Kerrisk
        Added description of SWTCH character
    Michael Kerrisk
        Add names of terminal special characters
    Michael Kerrisk
        List terminal special characters in alphabetical order

wcstombs.3
    Michael Kerrisk
        SEE ALSO: add mbstowcs(3)

console_codes.4
    Petr Pisar
        Add ESC [ 3 J
            Linux 3.0 (commit f8df13e0a901fe55631fed66562369b4dba40f8b)
            implements \E[3J to allow scrambling content of console
            including scroll-back buffer
            (http://thread.gmane.org/gmane.linux.kernel/1125792).

proc.5
    Michael Kerrisk  [Stan Sieler]
        Add description of 'PPid' field of /proc/PID/status
    Michael Kerrisk  [Stan Sieler]
        Add description of 'SigQ' field of /proc/PID/status

capabilities.7
    Michael Kerrisk  [Serge E. Hallyn]
        Document CAP_SYSLOG and related changes in Linux 2.6.37
    Michael Kerrisk
        File capabilities are no longer optional
            Starting with Linux 2.6.33, the CONFIG_SECURITY_FILE_CAPABILITIES
            has been removed, and file capabilities are always part of the
            kernel.

complex.7
    Michael Kerrisk
        Updated SEE ALSO list to include all complex math functions

ipv6.7
    Michael Kerrisk  [Simon Cross]
        Fix description of address notation: "8 4-digit hexadecimal numbers"

signal.7
    Seonghun Lim
        Remove crufty repeated info about LinuxThreads

unix.7
    Michael Kerrisk
        Add pointer to cmsg(3) for an example of the use of SCM_RIGHTS
top
==================== Changes in man-pages-3.34 ====================

Released: 2011-09-23, Munich

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes and ideas that have been
incorporated in changes in this release:

Alan Curry
Benjamin Poirier
Brian M. Carlson
David Howells
David PrÃ©vot
Denis Barbier
Doug Goldstein
Eric Blake
Guillem Jover
Jon Grant
Michael Kerrisk
Neil Horman
Paul Pluzhnikov
Reuben Thomas
Stefan Puiu
Stephan Mueller
Stephen Cameron
Sunil Mushran

Apologies if I missed anyone!

New and rewritten pages
-----------------------

rt_sigqueueinfo.2
    Michael Kerrisk  [Stephan Mueller]
        New page for rt_sigqueueinfo(2) and rt_tgsigqueueinfo(2)
            This replaces the previous '.so' man page link file for
            rt_sigqueueinfo.2, which linked to this sigqueue() man page.

cciss.4
    Stephen M. Cameron
        New man page for cciss driver
            I obtained the information in this man page as a consequence
            of having worked on the cciss driver for the past several years,
            and having written considerable portions of it.
    Michael Kerrisk
        Copyedit by mtk

hpsa.4
    Stephen M. Cameron
        New man page for the hpsa driver
            I obtained the information in this man page as a consequence
            of being the main author of the hpsa driver.
    Michael Kerrisk
        Copyedits my mtk

Newly documented interfaces in existing pages
---------------------------------------------

fstatat.2
    Michael Kerrisk  [David Howells]
        Document AT_NO_AUTOMOUNT
        This flag was added in Linux 2.6.38.

lseek.2
    Michael Kerrisk  [Eric Blake, Sunil Mushran]
        Document SEEK_HOLE and SEEK_DATA
            These flags, designed for discovering holes in a file,
            were added in Linux 3.1. Included comments from Eric
            Blake and Sunil Mushran.

madvise.2
    Doug Goldstein
        Add MADV_HUGEPAGE and MADV_NOHUGEPAGE
            Document the MADV_HUGEPAGE and MADV_NOHUGEPAGE flags added to
            madvise() in Linux 2.6.38.

New and changed links
---------------------

rt_tgsigqueueinfo.2
    Michael Kerrisk
        New link to new rt_sigqueueinfo.2 page

sigqueue.2
    Michael Kerrisk
        Create link to page that was relocated to section 3

Global changes
--------------

Various pages
    Michael Kerrisk
        Change reference to "sigqueue(2)" to "sigqueue(3)"

Changes to individual pages
---------------------------

fallocate.2
    Michael Kerrisk
        ERRORS: Add EPERM and ESPIPE errors

lseek.2
    Michael Kerrisk  [Alan Curry, Reuben Thomas]
        Remove suspect note about 'whence' being incorrect English

prctl.2
    Paul Pluzhnikov
        PR_SET_DUMPABLE makes process non-ptrace-attachable

readlink.2
    Guillem Jover
        Document using st_size to allocate the buffer
    Michael Kerrisk
        Added copyright text + changelog note for Guillem Jover's patch

sched_setscheduler.2
    Michael Kerrisk
        Document 2.6.39 changes to rules governing changes from SCHED_IDLE policy
            Since Linux 2.6.39, unprivileged processes under the
            SCHED_IDLE policy can switch to another nonrealtime
            policy if their nice value falls within the range
            permitted by their RLIMIT_NICE limit.

tkill.2
    Michael Kerrisk
        SEE ALSO: Add rt_sigqueueinfo (2)

btowc.3, wctob.3
    Michael Kerrisk  [Brian M. Carlson]
        Add pointers to better, thread-safe alternative functions
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=606899

fwide.3
    Michael Kerrisk
        Add _ISOC95_SOURCE to feature test macro requirements
            Since glibc 2.12, _ISOC95_SOURCE can also be used to expose
            prototype of this function.

index.3
    Michael Kerrisk  [Jon Grant]
        Fix text mentioning terminating null

pthread_sigqueue.3
    Michael Kerrisk
        Replace explicit mention of rt_tgsigqueueinfo() with SEE ALSO reference

sigqueue.3
    Michael Kerrisk
        Move this page to section 3
            Now that the underlying system call rt_sigqueueinfo(2) is
            properly documented, move sigqueue() to Section 3, since
            it is really a library function.
    Michael Kerrisk
        Update text in line with existence of new rt_sigqueueinfo.2 page

wcsnlen.3
    Jon Grant
        Improve description of 'maxlen' argument
            It's worth clarifying 'maxlen' is in wide-char units, not bytes.

wprintf.3
    Michael Kerrisk
        Add _ISOC95_SOURCE to feature test macro requirements
            Since glibc 2.12, _ISOC95_SOURCE can also be used to expose
            prototype of these functions.

feature_test_macros.7
    Michael Kerrisk
        Document _ISOC95_SOURCE
            _ISOC95_SOURCE was added in glibc 2.12 as a means
            to expose C90 Amendment 1 definitions.

ip.7
    Benjamin Poirier  [Neil Horman]
        Improve description of IP_MTU_DISCOVER

signal.7
    Michael Kerrisk
        SEE ALSO: Add rt_sigqueueinfo(2)
top
==================== Changes in man-pages-3.35 ====================

Released: 2011-10-04, Munich

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes and ideas that have been
incorporated in changes in this release:

Andi Kleen
David PrÃ©vot
Denis Barbier
Eric W. Biederman
Guillem Jover
Jon Grant
Kevin Lyda
Michael Kerrisk
Mike Frysinger
Reuben Thomas

Apologies if I missed anyone!

New and rewritten pages
-----------------------

recvmmsg.2
    Andi Kleen, Michael Kerrisk
        New man page for recvmmsg(2)

setns.2
    Eric W. Biederman
        New manual page for setns(2)
    Michael Kerrisk
        Various improvements

Global changes
--------------

Various pages
    Michael Kerrisk
        Global fix: remove spaces around em-dash
            Normal English typographical convention is not to have
            spaces around em dashes.

Various pages
    Michael Kerrisk
        Global fix: s/null pointer/NULL pointer/

Various pages
    Michael Kerrisk
        Global fix: use ORing
            Use "ORing", not "OR'ing", nor an italic ".IR OR ing".

Various pages
    Michael Kerrisk
        Global fix: consistent use of "null wide character"
            Bring more consistency to the discussion of
            "[terminating] null wide character"
            by writing (at least in the initial use in a page)
            "[terminating] null wide character (L'\0')".

Various pages
    Michael Kerrisk
        Global fix: consistent use of "null byte"
            Bring more consistency to the discussion of
            "[terminating] null byte"
            by writing (at least in the initial use in a page)
            "[terminating] null byte ('\0')".

mount.2, prctl.2
    Michael Kerrisk
        s/task/thread/ for consistency with other pages

Changes to individual pages
---------------------------

lseek.2
    Guillem Jover
        CONFORMING TO: Note other systems that have SEEK_HOLE+SEEK_DATA

recv.2
    Michael Kerrisk
        Add mention of recvmmsg(2)

recvmmsg.2
    Michael Kerrisk
        SEE ALSO: add sendmmsg(2)

send.2
    Michael Kerrisk
        CONFORMING TO: POSIX.1-2008 adds MSG_NOSIGNAL

sigwaitinfo.2
    Michael Kerrisk
        Note that attempts to wait for SIGKILL and SIGSTOP are silently ignored

stat.2
    Michael Kerrisk
        Note POSIX.1-2001 and POSIX.1-2008 requirements for lstat()
    Michael Kerrisk
        Regarding automounter action, add a reference to fstatat(2)
    Michael Kerrisk
        Clean up text describing which POSIX describes S_IF* constants

aio_cancel.3
    Michael Kerrisk  [Jon Grant]
        Clarify meaning of "return status" and "error status"

gets.3
    Michael Kerrisk
        POSIX.1-2008 marks gets() obsolescent
            The page formerly erroneously stated that POSIX.1-2008
            removed the specification of this function.

mbsnrtowcs.3
    Michael Kerrisk
        CONFORMING TO: Add POSIX.1-2008
            This function is specified in the POSIX.1-2008 revision.

regex.3
    Michael Kerrisk  [Reuben Thomas]
        Change "terminating null" to "terminating null byte"

stpcpy.3
stpncpy.3
    Mike Frysinger
        Note that these functions are in POSIX.1-2008
            Update the "CONFORMING TO" sections of these functions to
            note that they are now part of the POSIX.1-2008 standard.

stpncpy.3
    Michael Kerrisk
        Change "terminating null" to "terminating null byte"

strcpy.3
    Mike Frysinger
        SEE ALSO: Add stpncpy(3)

strdup.3
    Michael Kerrisk
        CONFORMING TO: strndup() is in POSIX.1-2008

wcpcpy.3
wcpncpy.3
wcsnlen.3
wcsnrtombs.3
    Michael Kerrisk
        CONFORMING TO: Add POSIX.1-2008
            These functions are specified in the POSIX.1-2008 revision.

proc.5
    Eric W. Biederman
        Document /proc/[pid]/ns/
    Michael Kerrisk
        Some edit's to Eric Biederman's /proc/[pid]/ns/ additions

capabilities.7
    Michael Kerrisk
        List setns(2) as an operation allowed by CAP_SYS_ADMIN
top
==================== Changes in man-pages-3.36 ====================

Released: 2012-02-27, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes and ideas that have been
incorporated in changes in this release:

Alain Benedetti
carado
Christoph Hellwig
Clemens Ladisch
David PrÃ©vot
Elie De Brauwer
Guillem Jover
Jessica McKellar
Josef Bacik
Junjiro Okajima
Lucian Adrian Grijincu
Michael Kerrisk
Mike Frysinger
Pat Pannuto
Salvo Tomaselli
Simone Piccardi
Slaven Rezic
starlight@binnacle.cx
Stephan Mueller
Vijay Rao
Walter Haidinger
Walter Harms
Yang Yang

Apologies if I missed anyone!

New and rewritten pages
-----------------------

sendmmsg.2
    Michael Kerrisk  [Stephan Mueller]
        New page for sendmmsg(2)
            Some pieces inspired by an initial attempt by Stephan Mueller.

Newly documented interfaces in existing pages
---------------------------------------------

fallocate.2
    Lucian Adrian Grijincu
        Document FALLOC_FL_PUNCH_HOLE
            FALLOC_FL_PUNCH_HOLE was added in Linux 2.6.38,
            for punching holes in the allocated space in a file.

Changes to individual pages
---------------------------

dup.2
    Michael Kerrisk
        SYNOPSIS: Add "#include <fcntl.h>" for O_* constants

fallocate.2
    Michael Kerrisk
        Substantial restructuring of DESCRIPTION
            The addition of a second class of operation ("hole punching")
            to the man page made it clear that some significant restructuring
            is required. So I substantially reworked the page, including the
            preexisting material on the default "file allocation" operation.
    Michael Kerrisk  [Josef Bacik]
        Add further details for FALLOC_FL_PUNCH_HOLE
    Michael Kerrisk
        ERRORS: Add EPERM error case for FALLOC_FL_PUNCH_HOLE

fork.2
    Michael Kerrisk
        NOTES: Describe clone() call equivalent to fork()

fsync.2
    Christoph Hellwig
        Various improvements
            - explain the situation with disk caches better
            - remove the duplicate fdatasync() explanation in the NOTES
              section
            - remove an incorrect note about fsync() generally requiring two
              writes
            - remove an obsolete ext2 example note
            - fsync() works on any file descriptor (doesn't need to be
              writable); correct the EBADF error code explanation
    Michael Kerrisk  [Guillem Jover]
        Note that some systems require a writable file descriptor
            An edited version of Guillem Jover's comments:
            [While the file descriptor does not need to be writable on Linux]
            that's not a safe portable assumption to make on POSIX in general
            as that behavior is not specified and as such is
            implementation-specific. Some Unix systems do actually fail on
            read-only file descriptors, for example [HP-UX and AIX].

mount.2
    Michael Kerrisk  [Junjiro Okajima]
        Removed erroneous statement about MS_RDONLY and bind mounts

open.2
    Jessica McKellar
        Fix grammar in O_DIRECT description
            Some small grammar fixes to the O_DIRECT description.

pipe.2
    Michael Kerrisk  [Salvo Tomaselli]
        SYNOPSIS: Add "#include <fcntl.h>" for O_* constants
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=659750

sched_rr_get_interval.2
    Clemens Ladisch
        Update notes on modifying quantum
            Since Linux 2.6.24, it is no longer possible to
            modify the SCHED_RR quantum using setpriority(2).
            (Slight edits to Clemens' patch by mtk.)
    Michael Kerrisk
        Reordered various pieces of text
    Michael Kerrisk
        Reworded text of ESRCH error

send.2
    Michael Kerrisk
        Add mention of sendmmsg(2)

sync.2
    Michael Kerrisk  [Simone Piccardi]
        PROTOTYPE: Fix return type of syncfs()

vfork.2
    Michael Kerrisk  [starlight@binnacle.cx]
        Clarify what is duplicated in the child
            Add some words to make it clear to the reader that vfork(),
            like fork(), creates duplicates of process attributes
            in the child.
    Michael Kerrisk
        Note clone() flags equivalent to vfork()
    Michael Kerrisk  [starlight@binnacle.cx, Mike Frysinger]
        Add some notes on reasons why vfork() still exists
    Michael Kerrisk  [starlight@binnacle.cx]
        Clarify that calling *thread* is suspended during vfork()
    Michael Kerrisk
        CONFORMING TO: Note that POSIX.1-2001 marked vfork() obsolete

gets.3
    Michael Kerrisk
        Document C11 and glibc 2.16 changes affecting gets()

pthread_sigmask.3
    Michael Kerrisk  [Pat Pannuto]
        Fix comment that was inconsistent with code in example program

sem_wait.3
    Walter Harms
        EXAMPLE: Remove extraneous line of output from shell session

wcsnrtombs.3
wcsrtombs.3
wcstombs.3
    Michael Kerrisk
        Fix-ups for e9c23bc636426366d659809bc99cd84661e86464

core.5
    Michael Kerrisk  [Junjiro Okajima]
        Document %E specifier for core_pattern

passwd.5
    Michael Kerrisk  [Walter Haidinger]
        s/asterisk/asterisk (*)/ to improve clarity
    Michael Kerrisk
        Correct note on passwd field value when shadowing is enabled
            When password shadowing is enabled, the password field
            contains an 'x' (not "*').

proc.5
    Elie De Brauwer
        Fix description of fourth field of /proc/loadavg
            SIgned-off-by: Elie De Brauwer

resolv.conf.5
    Michael Kerrisk  [Slaven Rezic]
        Describe syntax used for comments
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=656994

feature_test_macros.7
    Michael Kerrisk
        Document _ISOC11_SOURCE

inotify.7
    Michael Kerrisk  [Yang Yang]
        Note that 'cookie' field is set to zero when unused

man.7
    Michael Kerrisk
        Various fixes for description of NAME section
            As noted by reporter:
            * The code sample given for the NAME section is incomplete because
              the actual content sample is not given.
            * Additionally, the description assumes that the item described is
              a command, which need not be the case.
            * The command makewhatis is not present on my system; the
              documented tool to create the whatis database is called mandb.
            * The description on .SH NAME in man(7) should either copy the
              relevant paragraph of lexgrog(1) or refer to it.
top
==================== Changes in man-pages-3.37 ====================

Released: 2012-03-06, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes and ideas that have been
incorporated in changes in this release:

Denys Vlasenko
Mark R. Bannister
Michael Kerrisk
Oleg Nesterov
Tejun Heo

Apologies if I missed anyone!

New and rewritten pages
-----------------------

getent.1
    Mark R. Bannister
        New page to document 'getent' binary provided by glibc

Changes to individual pages
---------------------------

bdflush.2
    Michael Kerrisk
        Note that bdflush() is deprecated, and does nothing

nfsservctl.2
    Michael Kerrisk
        Note that this system call was removed in Linux 3.1

ptrace.2
    Denys Vlasenko  [Oleg Nesterov, Tejun Heo]
        add extended description of various ptrace quirks
            Changes include:

            s/parent/tracer/g, s/child/tracee/g - ptrace interface now
            is sufficiently cleaned up to not treat tracing process
            as parent.

            Deleted several outright false statements:
            - pid 1 can be traced
            - tracer is not shown as parent in ps output
            - PTRACE_ATTACH is not "the same behavior as if tracee had done
              a PTRACE_TRACEME": PTRACE_ATTACH delivers a SIGSTOP.
            - SIGSTOP _can_ be injected.
            - Removed mentions of SunOS and Solaris as irrelevant.
            - Added a few more known bugs.

            Added a large block of text in DESCRIPTION which doesn't focus
            on mechanical description of each flag and operation, but rather
            tries to describe a bigger picture. The targeted audience is
            a person which is reasonably knowledgeable in Unix but did not
            spend years working with ptrace, and thus may be unaware of its
            quirks. This text went through several iterations of review by
            Oleg Nesterov and Tejun Heo.
            This block of text intentionally uses as little markup as possible,
            otherwise future modifications to it will be very hard to make.
    Michael Kerrisk
        Global clean-up of page
            * Wording and formatting fixes to existing text and
              Denys Vlasenko's new text.
            * Various technical amendments and improvements to
              Denys Vlasenko's new text.
            * Added FIXME for various problems with the current text.
    Michael Kerrisk
        Integrated changes after further review from Denys Vlasenko

syscalls.2
    Michael Kerrisk
        Note that nfsservctl(2) was removed in Linux 3.1
        Note that bdflush(2) is deprecated

capabilities.7
    Michael Kerrisk
        Add CAP_WAKE_ALARM
    Michael Kerrisk
        Add various operations under CAP_SYS_ADMIN
        Add perf_event_open(2) to CAP_SYS_ADMIN
        Add VM86_REQUEST_IRQ vm86(2) command to CAP_SYS_ADMIN
        Update CAP_NET_ADMIN with notes from include/linux/capability.h
        Add nfsservctl(2) to CAP_SYS_ADMIN
    Michael Kerrisk
        Add ioctl(FIBMAP) under CAP_SYS_RAWIO
    Michael Kerrisk
        Add virtual terminal ioctl()s under CAP_SYS_TTY_CONFIG
    Michael Kerrisk
        Update CAP_NET_RAW with notes from include/linux/capability.h
    Michael Kerrisk
        Add F_SETPIPE_SZ case to CAP_SYS_RESOURCE
        Add POSIX messages queues queues_max case to CAP_SYS_RESOURCE
        Update CAP_SYS_RESOURCE with notes from include/linux/capability.h
    Michael Kerrisk
        SEE ALSO: Add libcap(3)

ld.so.8
    Michael Kerrisk
        Add --audit command-line option
top
==================== Changes in man-pages-3.38 ====================

Released: 2012-03-25, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Akihiro MOTOKI
Artyom Pervukhin
BeÅˆas Petr
Ben Bacarisse
Bjarni Ingi Gislason
David PrÃ©vot
Denis Barbier
Denys Vlasenko
Eric Blake
Iain Fraser
Justin T Pryzby
Kirill Brilliantov
Mark R Bannister
Matthew Gregan
Michael Kerrisk
Nix
Peter Schiffer
Sergei Zhirikov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

get_nprocs_conf.3
    BeÅˆas Petr
        New page documenting get_nprocs_conf(3) and get_nprocs(3)
    Michael Kerrisk
        Some additions and improvements

malloc_get_state.3
    Michael Kerrisk
        New page documenting malloc_get_state(3) and malloc_set_state(3)

mallopt.3
    Michael Kerrisk
        New man page for mallopt(3)

mtrace.3
    Michael Kerrisk
        Complete rewrite of page, adding much more detail

scandirat.3
    Mark R Bannister
        New page for scandirat(3) (new in glibc 2.15)

Newly documented interfaces in existing pages
---------------------------------------------

posix_memalign.3
    Michael Kerrisk
        Document aligned_alloc(3)
            aligned_alloc() is new in C11.
    Michael Kerrisk
        Document pvalloc(3)

qsort.3
    Mark R Bannister
        Add documentation of qsort_r(3)
    Ben Bacarisse
        Improvements to Mark R Bannister's qsort_r() patch
    Michael Kerrisk
        Add VERSIONS section for qsort_r()

New and changed links
---------------------

aligned_alloc.3
    Michael Kerrisk
        New link to posix_memalign.3

get_nprocs.3
    BeÅˆas Petr
        Link to new get_nprocs_conf.3 page

malloc_set_state.3
    Michael Kerrisk
        Link to new malloc_get_state.3 page

pvalloc.3
    Michael Kerrisk
        New link to posix_memalign.3

Global changes
--------------

Various pages
    Michael Kerrisk
        Global formatting fix: balance .nf/.fi pairs

Various pages
    Michael Kerrisk
        Global fix: place sections in correct order

Various pages
    Michael Kerrisk  [Justin T Pryzby]
        Global fix: Remove duplicated words
            Remove instances of duplicate words found using Justin's
            grep-fu:

                for f in man?/*.[1-9]; do
                    grep -HE ' ([[:alpha:]]{2,} +)\1' "$f" |
                        grep -Evw '(proc|hugetlbfs|XXX*|root|long) *\1';
                done | grep -E --colo ' ([[:alpha:]]{2,} +)\1'

Various pages
    Michael Kerrisk
        Correct order of SEE ALSO entries

Changes to individual pages
---------------------------

futimesat.2
    Michael Kerrisk
        PROTOTYPE: Correct header file and feature test macro requirements

keyctl.2
    Bjarni Ingi Gislason
        Strip trailing tabs from source line
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=664688

ptrace.2
    Denys Vlasenko
        Document PTRACE_GETEVENTMSG for PTRACE_EVENT_EXEC
    Denys Vlasenko
        Various fixes to recent updates of this page

symlinkat.2
    Michael Kerrisk  [Eric Blake]
        PROTOTYPE: Correct header file

syscalls.2
    Michael Kerrisk
        Remove unimplemented system calls from main syscall list
            The unimplemented system calls are in any case noted lower down
            in the page. Also: rearrange the text describing the unimplemented
            system calls.
    Michael Kerrisk
        Note a few system calls that were removed in Linux 2.6
    Michael Kerrisk
        Add process_vm_readv(2) and process_vm_writev(2)

unlinkat.2
    Michael Kerrisk  [Eric Blake]
        PROTOTYPE: Correct header file
    Michael Kerrisk
        PROTOTYPE: Add <fcntl.h> for AT_* constants

utimensat.2
    Michael Kerrisk
        PROTOTYPE: Add <fcntl.h> for AT_* constants

copysign.3
    Michael Kerrisk  [Tolga Dalman]
        DESCRIPTION: Add a couple of examples

malloc.3
    Michael Kerrisk
        NOTES: Add a short discussion of arenas
    Michael Kerrisk
        Replace discussion of MALLOC_CHECK_ with pointer to mallopt(3)
    Michael Kerrisk
        SEE ALSO: Add mtrace(3)
        SEE ALSO: add malloc_get_state(3)

posix_memalign.3
    Michael Kerrisk
        Rename memalign() argument
            Rename "boundary" to "alignment" for consistency
            with posix_memalign().
    Michael Kerrisk
        Improve discussion of feature test macros and header files for valloc(3)

rtnetlink.3
    Kirill Brilliantov  [Sergei Zhirikov]
        Fix example code, rta_len assignment should use RTA_LENGTH()
            See also http://bugs.debian.org/655088

scandir.3
    Mark R Bannister
        SEE ALSO: Add scandirat(3)

sigqueue.3
    Nix
        Remove rt_sigqueueinfo from TH line
            rt_sigqueueinfo() now has its own manual page, so should not
            be listed in the .TH line of this page.

tzset.3
    Peter Schiffer
        Correct description for Julian 'n' date format
            The Julian 'n' date format counts starting from 0, not 1.
    Michael Kerrisk
        Add some clarifying remarks to discussion of Julian day formats

packet.7
    Michael Kerrisk  [Iain Fraser]
        Fix comment on 'sll_hatype' field

tcp.7
    Michael Kerrisk  [Artyom Pervukhin]
        Correct RFC for TIME_WAIT assassination hazards
top
==================== Changes in man-pages-3.39 ====================

Released: 2012-04-17, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Abhijith Das
Alexander Kruppa
Andreas Jaeger
Armin Rigo
Cyrill Gorcunov
Denys Vlasenko
Eric Blake
Felix
Jak
Jeff Mahoney
Jesus Otero
Jonathan Nieder
Kevin O'Gorman
Mark R Bannister
Michael Kerrisk
Michael Welsh Duggan
Mike Frysinger
Petr Gajdos
Regid Ichira
Reuben Thomas
Ricardo Catalinas JimÃ©nez
Simone Piccardi
Tetsuo Handa

Apologies if I missed anyone!

New and rewritten pages
-----------------------

malloc_trim.3
    Michael Kerrisk
        New man page for malloc_trim(3)

malloc_usable_size.3
    Michael Kerrisk
        New man page for malloc_usable_size(3)

Newly documented interfaces in existing pages
---------------------------------------------

prctl.2
    Cyrill Gorcunov
        Document PR_SET_MM (new in Linux 3.3)
    Michael Kerrisk
        Various edits and improvements to Cyrill's patch

Changes to individual pages
---------------------------

epoll_create.2
    Michael Kerrisk
        Rework discussion of 'size' argument
    Michael Kerrisk
        Add .SS for description of epoll_create1()

epoll_wait.2
    Michael Kerrisk  [Armin Rigo]
        Another thread can add to epoll instance while epoll_wait is blocked
            See https://bugzilla.kernel.org/show_bug.cgi?id=43072
    Michael Kerrisk
        Clarify that epoll_pwait() blocks calling *thread*
        A few wording improvements

fchmodat.2
    Michael Kerrisk  [Mike Frysinger]
        Note difference between glibc wrapper and underlying system call
            The wrapper function has a 'flags' argument (which currently
            serves no purpose), while the underlying system call does not.

fcntl.2
    Abhijith Das
        Explain behaviour of F_GETLEASE during lease break
    Michael Kerrisk  [Eric Blake]
        Change type of arg from "long" to "int"
            Various fcntl(2) commands require an integral 'arg'.
            The man page said it must be "long" in all such cases.
            However, for the cases covered by POSIX, there is an
            explicit requirement that these arguments be "int".
            Update the man page to reflect. Probably, all of the
            other "long" cases (not specified in POSIX) should
            be "int", and this patch makes them so. Based on a
            note fromEric Blake, relating to F_DUPFD_CLOEXEC.

gettimeofday.2
    Michael Kerrisk
        Reorganize content
            The main change is to move the historical information about
            the 'tz_dsttime' to NOTES.
    Michael Kerrisk  [Felix]
        Note that compiler issues warnings if 'tv' is NULL

mmap.2
    Michael Kerrisk  [Kevin O'Gorman]
        Clarify that this system call should not be invoked directly
            See https://bugzilla.kernel.org/show_bug.cgi?id=42892
    Michael Kerrisk
        Clarify NOTES discussion of mmap() versus mmap2()

poll.2
    Michael Kerrisk  [Michael Welsh Duggan]
        Document negative value in 'fd' field
    Michael Kerrisk
        Document semantics of passing zero in 'events' field

ptrace.2
    Denys Vlasenko
        Various fixes
            For some reason, the PTRACE_TRACEME paragraph talks about some
            general aspects of ptraced process behavior. It repeats the
            "tracee stops on every signal" information even though that was
            already explained just a few paragraphs before. Then it describes
            legacy SIGTRAP on execve().

            This patch deletes the first part, and moves the second part up,
            into the general ptrace description. It also adds
            "If PTRACE_O_TRACEEXEC option is not in effect" to the description
            of the legacy SIGTRAP on execve().

            The patch also amends the part which says "For requests other
            than PTRACE_KILL, the tracee must be stopped." - PTRACE_ATTACH
            also doesn't require that.

sigaction.2
    Michael Kerrisk  [Andreas Jaeger, ]
        Clarify that the use of SI_SIGIO is for Linux 2.2 only
            See also http://sourceware.org/bugzilla/show_bug.cgi?id=6745

sigprocmask.2
    Mike Frysinger
        ERRORS: add EFAULT

times.2
    Michael Kerrisk  [Simone Piccardi]
        ERRORS: Add EFAULT

div.3
    Michael Kerrisk  [Reuben Thomas]
        CONFORMING TO: Add C99

fread.3
    Regid Ichira
        Clarify further that return value is number of items, not bytes
            See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=665780

getaddrinfo.3
    Michael Kerrisk  [Jak]
        Correct type of ai_addrlen field

malloc.3
    Michael Kerrisk
        SEE ALSO: add malloc_usable_size(3)
        SEE ALSO: Add malloc_trim(3)

mallopt.3
    Michael Kerrisk
        Fix text describing M_PERTURB and free()
        SEE ALSO: Add malloc_trim(3)

memchr.3
    Michael Kerrisk  [Reuben Thomas]
        Remove mention of terminating null in description of rawmemchr()

perror.3
    Michael Kerrisk  [Jesus Otero]
        Note that use of 'sys_errlist' is deprecated

rcmd.3
    Michael Kerrisk
        glibc eventually added a declaration of iruserok() in version 2.12

sysconf.3
    Michael Kerrisk  [Ricardo Catalinas JimÃ©nez]
        Add mention of _SC_SYMLOOP_MAX

nologin.5
    Michael Kerrisk  [Tetsuo Handa]
        nologin must not only exist, but *be readable* to be effective

nsswitch.conf.5
    Mark R Bannister
        Significant rewrites and improvements
            This patch applies to nsswitch.conf.5 in man-pages-3.36.

            My changes almost completely rewrite large sections of the
            man page. They are needed to add clarity, correct grammar,
            reduce confusion, and bring up-to-date with the latest glibc.
            I have checked the man page against the nss source code in
            glibc 2.14.90.

            Historical notes are demoted to the footer.

            The rewrite makes the man page much clearer to
            understand, more authoratitive, and easier to read.
    Michael Kerrisk
        Light edits to Mark Bannister's changes

capabilities.7
    Michael Kerrisk
        Add prctl(PR_SET_MM) to CAP_SYS_RESOURCE

epoll.7
    Michael Kerrisk
        Some minor clarifications at start of DESCRIPTION

netlink.7
    Jeff Mahoney  [Petr Gajdos]
        Note cases where nonprivileged users can use netlink multicast groups
            See also https://bugzilla.novell.com/show_bug.cgi?id=754611

unix.7
    Michael Kerrisk  [Tetsuo Handa]
        Add a detail on autobind feature

ld.so.8
    Jonathan Nieder  [Reuben Thomas]
        Document effect of hwcaps on search path
            Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).

            Addresses http://bugs.debian.org/622385
top
==================== Changes in man-pages-3.40 ====================

Released: 2012-04-27, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Alexey Toptygin
Bernhard Walle
Brian F. G. Bidulock
Brian M. Carlson
Christopher Yeoh
Daniel J Blueman
Eric Blake
Eugen Dedu
James Hunt
John Sullivan
Jon Grant
lepton
Marcel Holtmann
Michael Kerrisk
Mike Frysinger
Petr Baudis
Simon Paillard
Stefan Puiu
Ulrich Drepper
Vadim Mikhailov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

process_vm_readv.2
    Mike Frysinger, Christopher Yeoh, Michael Kerrisk
        New page for process_vm_readv(2) and process_vm_writev(2)

mcheck.3
    Michael Kerrisk
        New man page for mcheck(3) and related functions
            Also describes mcheck_check_all(3), mcheck_pedantic(3),
            and mprobe(3)

Newly documented interfaces in existing pages
---------------------------------------------

rcmd.3
    Michael Kerrisk
        Document "_af" variants of these functions
            Document rcmd_af(), rresvport_af(), iruserok_af(), ruserok_af().
            Also some restructuring and other clarifications.

rexec.3
    Michael Kerrisk
        Document rexec_af()

New and changed links
---------------------

iruserok_af.3
rcmd_af.3
rresvport_af.3
ruserok_af.3
    Michael Kerrisk
        New links to rcmd.3

rexec_af.3
    Michael Kerrisk
        New link to rexec.3

Changes to individual pages
---------------------------

clock_getres.2
    Michael Kerrisk
        Clarify difference between CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW
            Note interactions of these two clocks with discontinuous
            adjustments to the system time and NTP/adjtime(2).

fallocate.2
    Michael Kerrisk  [John Sullivan]
        Fix description of ENOSYS and EOPNOTSUP errors
            As reported in https://bugzilla.redhat.com/show_bug.cgi?id=680214

fchmodat.2
    Michael Kerrisk  [Mike Frysinger]
        Improve discussion of difference between wrapper and underlying syscall

gettimeofday.2
    Michael Kerrisk
        gettimeofday() is affected by discontinuous jumps in the system time
            Advise reader to use clock_gettime(2), if they need a
            monotonically increasing time source.
    Michael Kerrisk
        SEE ALSO: Add clock_gettime(2)

prctl.2
    Michael Kerrisk
        Add PR_TASK_PERF_EVENTS_DISABLE and PR_TASK_PERF_EVENTS_ENABLE
            Add some basic documentation of these operations, with a pointer to
            tools/perf/design.txt for more information.
    Michael Kerrisk  [Marcel Holtmann]
        Amend details of PR_SET_PDEATHSIG

ptrace.2
    Michael Kerrisk  [Mike Frysinger]
        Note SPARC deviation with respect to get/set regs
            SPARC reverses the use of 'addr' and 'data' for
            PTRACE_GETREGS, PTRACE_GETFPREGS, PTRACE_SETREGS,
            and PTRACE_SETFPREGS.

send.2
    Stefan Puiu
        Document EACCES error case for UDP

sigaction.2
    Michael Kerrisk
        Remove mention of raise(3) for SI_USER
            For a long time now, glibc's raise(3) didn't yield SI_USER
            for the signal receiver, so remove mention of raise(3)
            here. The user can deduce the details, if needed, by looking
            at the recently updated raise(3) page.

aio_cancel.3
    Michael Kerrisk  [Jon Grant]
        Rewrite RETURN VALUE section to be clearer

aio_init.3
    Michael Kerrisk  [Jon Grant]
        Remove extraneous "POSIX" from NAME section

btree.3
dbopen.3
hash.3
mpool.3
recno.3
    Michael Kerrisk  [Brian M. Carlson]
        Note that glibc no longer provides these interfaces
            glibc stopped providing these interfaces with v2.2.
            Nowadays, the user that finds these pages probably wants
            the libdb API, so note this in the page.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=337581

fopen.3
    Michael Kerrisk
        BUGS: Note limitation on number of flag characters parsed in 'mode'
    Michael Kerrisk
        Note that 'c' and 'e' flags are ignored for fdopen()
            Determined from reading libio/iofdopen.c.
    Michael Kerrisk
        Document ",ccs=string" feature of 'mode' for fopen()/freopen()

getgrnam.3
    Michael Kerrisk  [Ulrich Drepper]
        Fix discussion of _SC_GETGR_R_SIZE_MAX
            The value is not meant to be a maximum (as was specified in
            SUSv3) but an initial guess at the required size
            (as specified in SUSv4).

getpwnam.3
    Michael Kerrisk  [Ulrich Drepper]
        Fix discussion of _SC_GETPW_R_SIZE_MAX
            The value is not meant to be a maximum (as was specified in
            SUSv3) but an initial guess at the required size
            (as specified in SUSv4).

malloc.3
mallopt.3
mtrace.3
    Michael Kerrisk
        SEE ALSO: add mcheck(3)

memchr.3
    Michael Kerrisk
        Clarify description, omitting mention of "strings" and "characters"
            The existing text slipped into talking about characters and
            strings, which could mislead readers into thing that, for
            example, searches for the byte '\0' are treated specially.
            Therefore, rewrite in terms of "bytes" and "memory areas".

            At the same time, make a few source file clean-ups.

mkstemp.3
    Michael Kerrisk
        Add "mkstemps" and "mkostemps" to NAME line

posix_openpt.3
    Michael Kerrisk  [Vadim Mikhailov]
        Add some details on use of the slave pathname
            An explicit pointer to ptsname(3) is useful, as is a note
            of the fact that the slave device pathname exists only as
            long as the master device is held open.

raise.3
    Michael Kerrisk
        Add some notes on underlying system call that is used

rcmd.3
    Michael Kerrisk
        Add some details of the rresvport() 'port' argument

resolver.3
    Petr Baudis
        Note that many options are documented in resolv.conf(5)

scandir.3
    Michael Kerrisk  [Daniel J Blueman]
        Improve EXAMPLE source code: s/0/NULL/ in scandir() call

strchr.3
    James Hunt
        Explain behavior when searching for '\0'

strerror.3
    Eric Blake  [Stefan Puiu]
        Improve strerror_r() description
            POSIX requires that perror() not modify the static storage
            returned by strerror().  POSIX 2008 and C99 both require that
            strerror() never return NULL (a strerror() that always
            returns "" for all inputs is valid for C99, but not for POSIX).

            http://sourceware.org/bugzilla/show_bug.cgi?id=12204
            documents glibc's change to come into compliance with POSIX
            regarding strerror_r() return value.  The GNU strerror_r() use
            of 'buf' was confusing - I ended up writing a test program that
            proves that 'buf' is unused for valid 'errnum', but contains
            truncated "unknown message" for out-of-range 'errnum'.

            See also http://austingroupbugs.net/view.php?id=382
    Bernhard Walle
        Correct description of error return for XSI strerror_r()
    Michael Kerrisk [Eric Blake]
        Note how to use 'errno' to detect errors when calling strerror()
    Michael Kerrisk  [Jon Grant]
        Add an example of the kind of string returned by strerror()

resolv.conf.5
    Petr Baudis
        Document "single-request" option

inotify.7
    Michael Kerrisk
        Note buffer size that guarantees being able to read at least one event
    James Hunt
        Correct description of size of inotify_event structure

iso_8859-1.7
    Eugen Dedu
        Add "-" for SOFT HYPHEN
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=156154

netdevice.7
    Brian F. G. Bidulock
        Document some SIOC configuration ioctls
            This patch adds common but missing SIOC configuration ioctls to
            the netdevice.7 manual pages that are not documented anywhere
            else. SIOCSIFPFLAGS and SIOCGIFPFLAGS are linux-specific. Flag
            values come from Linux 2.6.25 kernel headers for sockios. The
            others are standard BSD ioctls that have always been implemented
            by Linux and were verified from inspecting netdevice.c kernel
            code.

socket.7
    Michael Kerrisk  [Alexey Toptygin]
        Correct description of SO_BROADCAST

tcp.7
    lepton
        Correct description for TCP_MAXSEG on modern kernel
top
==================== Changes in man-pages-3.41 ====================

Released: 2012-05-11, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Akihiro MOTOKI
Andries E. Brouwer
Angelo Borsotti <angelo.borsotti@gmail.com >
Bjarni Ingi Gislason
Brian M. Carlson
Casper.Dik@oracle.com
David PrÃ©vot
D. Barbier
Eric Blake
Hugh Dickins
Ivana Varekova
Jakub Jelinek
Jan Kara
Jason Baron
Jean-Michel VourgÃ¨re
Jeff Moyer
Josh Triplett
Kasper Dupont
KOSAKI Motohiro
Lauri Kasanen
Mel Gorman
Michael Kerrisk
Mike Frysinger
Nick Piggin
Paul Pluzhnikov
Petr Baudis
Ralph Corderoy <ralph@inputplus.co.uk >
Rich Felker
Simone Piccardi
Simon Paillard
Stefan Puiu
Stephen Hemminger
Vincent Lefevre
Yuri Kozlov

Apologies if I missed anyone!

New and rewritten pages
-----------------------

get_robust_list.2
    Ivana Varekova  [Michael Kerrisk]
        New page documenting get_robust_list(2) and set_robust_list(2)

mallinfo.3
    Michael Kerrisk [KOSAKI Motohiro, Paul Pluzhnikov]
        New page for mallinfo(3)

malloc_info.3
    Michael Kerrisk  [Jakub Jelinek]
        New page for malloc_info(3)

malloc_stats.3
    Michael Kerrisk  [KOSAKI Motohiro]
        New man page for malloc_stats(3)

Newly documented interfaces in existing pages
---------------------------------------------

madvise.2
    Jason Baron
        Document MADV_DONTDUMP and MADV_DODUMP

New and changed links
---------------------

set_robust_list.2
    Michael Kerrisk
        New link to new get_robust_list.2 page

LIST_ENTRY.3
LIST_HEAD.3
LIST_INIT.3
LIST_INSERT_AFTER.3
LIST_INSERT_HEAD.3
LIST_REMOVE.3
TAILQ_ENTRY.3
TAILQ_HEAD.3
TAILQ_INIT.3
TAILQ_INSERT_AFTER.3
TAILQ_INSERT_HEAD.3
TAILQ_INSERT_TAIL.3
TAILQ_REMOVE.3
CIRCLEQ_ENTRY.3
CIRCLEQ_HEAD.3
CIRCLEQ_INIT.3
CIRCLEQ_INSERT_AFTER.3
CIRCLEQ_INSERT_BEFORE.3
CIRCLEQ_INSERT_HEAD.3
CIRCLEQ_INSERT_TAIL.3
CIRCLEQ_REMOVE.3
    Michael Kerrisk
        New link to queue.3
            The queue(3) page documents these macros, so it makes sense to
            have links for the names.

DES_FAILED.3
    Michael Kerrisk
        New link to des_crypt.3
            The des_crypt(3) page documents this macro, so it makes sense
            to have a link for the name.

qsort_r.3
    Michael Kerrisk
        New link to qsort.3
            Overlooked to add this link in 3.38, when documentation of
            qsort_r() was added to the qsort.3 page.

Global changes
--------------

faccessat.2
fchmodat.2
fchownat.2
fstatat.2
futimesat.2
inotify_init.2
linkat.2
mkdirat.2
mknodat.2
openat.2
readlinkat.2
renameat.2
setns.2
splice.2
symlinkat.2
sync.2
tee.2
unlinkat.2
vmsplice.2
    Michael Kerrisk  [Lauri Kasanen]
        Global fix: note glibc version that added library support

confstr.3
strcasecmp.3
strcat.3
strcmp.3
strcpy.3
strdup.3
strftime.3
strlen.3
strnlen.3
strpbrk.3
strspn.3
strtok.3
strxfrm.3
    Michael Kerrisk  [Andries E. Brouwer]
        Clarify that these functions operate on bytes, not (wide) characters
            Change 'character(s)' to 'byte(s)' to make clear that these
            functions operate on bytes, not wide / UTF8 characters.
            (POSIX uses 'byte(s)' similarly, to make this point.)

icmp.7
ipv6.7
packet.7
raw.7
rtnetlink.7
unix.7
x25.7
    Michael Kerrisk
        Remove names of constants from NAME line
            Some of the sockets/network protocol pages included names of
            the corresponding address family constants in the NAME line,
            but this wasn't done consistently across all pages, and probably
            it adds little value in those pages that did do this. So, remove
            these constants from those pages that have them in the NAME
            section.

Changes to individual pages
---------------------------

clock_getres.2
    Michael Kerrisk  [Josh Triplett]
        Expand description of CLOCK_REALTIME
            Make it clear that this clock may be discontinuous, and is
            affected my incremental NTP and clock-adjtime(2) adjustments.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=540872

epoll_wait.2
    Michael Kerrisk
        Clarify that 'timeout' is a *minimum* interval
            Make it clear that 'timeout' is a minimum interval; the actual
            interval will be rounded up to the system clock granularity,
            and may overrun because of kernel scheduling delays.

execve.2
    Michael Kerrisk
        Rewording to deemphasize libc5 details

fork.2
    Mike Frysinger
        ERRORS: add ENOSYS
            Can occur on, for example, non-MMU hardware.

getcpu.2
    Mike Frysinger
        Add RETURN VALUE and ERRORS sections
    Michael Kerrisk
        Refer reader to NOTES for more info about 'tcache'
    Michael Kerrisk
        DESCRIPTION: reword a sentence to be clearer

io_cancel.2
io_destroy.2
io_getevents.2
io_setup.2
io_submit.2
    Michael Kerrisk
        Rewrite to focus on system call API
            Rewrite to focus on the system call interface, adding
            some notes on the libaio wrapper differences.
            See the following mail:
            2012-05-07 "aio manuals", linux-man@vger.kernel.org
            http://thread.gmane.org/gmane.linux.man/1935/focus=2910

            Other minor rewrites.

mount.2
    Michael Kerrisk
        Comment out an old Linux libc detail

open.2
    Nick Piggin  [KOSAKI Motohiro, Jan Kara, Hugh Dickins]
        Describe race of direct I/O and fork()
            Rework 04cd7f64, which didn't capture the details correctly.
            See the April/May 2012 linux-man@ mail thread "[PATCH]
            Describe race of direct read and fork for unaligned buffers"
            http://thread.gmane.org/gmane.linux.kernel.mm/77571

poll.2
    Michael Kerrisk
        Clarify that 'timeout' is a *minimum* interval
            Make it clear that 'timeout' is a minimum interval; the actual
            interval will be rounded up to the system clock granularity,
            and may overrun because of kernel scheduling delays.
    Michael Kerrisk
        Clarify discussion of wrapper function emulation
            Clarify that glibc (as well as old libc) provides emulation
            using select(2) on older kernels that don't have a poll()
            system call.
    Michael Kerrisk
        Make the meaning of a zero timeout explicit
            Clarify that timeout==0 causes an immediate return, even if
            no file descriptors are ready.

pread.2
    Michael Kerrisk  [Kasper Dupont]
        BUGS: Note O_APPEND + pwrite() does the wrong thing
            See https://bugzilla.kernel.org/show_bug.cgi?id=43178

recvmmsg.2
    Michael Kerrisk
        Clarify that 'timeout' is a *minimum* interval
            Make it clear that 'timeout' interval will be rounded up to the
            system clock granularity, and may overrun because of kernel
            scheduling delays.

select.2
    Michael Kerrisk
        Clarify that 'timeout' is a *minimum* interval
            Make it clear that 'timeout' is a minimum interval; the actual
            interval will be rounded up to the system clock granularity,
            and may overrun because of kernel scheduling delays.
    Michael Kerrisk
        Expand description of the self-pipe trick
    Michael Kerrisk
        Add further details on pselect6() system call that underlies pselect()

semop.2
    Michael Kerrisk
        Clarify that 'timeout' of semtimedop() is a *minimum* interval
            Make it clear that 'timeout' interval will be rounded up to the
            system clock granularity, and may overrun because of kernel
            scheduling delays.

signal.2
    Michael Kerrisk
        Note that 'sig_t' requires _BSD_SOURCE
            Also remove some old Linux libc details

sigwaitinfo.2
    Michael Kerrisk
        Clarify that 'timeout' of sigtimedwait() is a *minimum* interval
            Make it clear that 'timeout' is a minimum interval; the actual
            interval will be rounded up to the system clock granularity,
            and may overrun because of kernel scheduling delays.

stat.2
    Bjarni Ingi Gislason
        Formatting fixes
            From "groff -ww" (or "man --warnings=w ..."):

                warning: around line 442: table wider than line width

            GNU man uses line length of 78.

            Use text blocks.  Two spaces between sentences or better: start
            each sentence in a new line.

syscalls.2
    Bjarni Ingi Gislason
        Formatting fixes
            From "groff -ww ..." (or "man --warnings=w ..."):

                warning: around line 157: table wider than line width

            Have to use text blocks.  Move some text to its correct column.
            Split text to two columns to avoid hyphenation.

sysinfo.2
    Michael Kerrisk
        Remove reference to obsolete libc5

syslog.2
    Michael Kerrisk
        Remove some details about obsolete Linux libc

aio_cancel.3
aio_error.3
aio_fsync.3
aio_read.3
aio_return.3
aio_suspend.3
aio_write.3
    Michael Kerrisk
        ERRORS: Add/update ENOSYS error

aio_cancel.3
    Michael Kerrisk
        Clarify what happens when a request isn't successfully canceled
    Michael Kerrisk
        Add pointers to aio(7) and sigevent(7)

dbopen.3
    Michael Kerrisk
        SYNOPSIS: Add header file <fcntl.h>
            Upstreamed from Debian, and consistent with FreeBSD
            dbopen(3) man page.

fmemopen.3
    Michael Kerrisk
        Note details of POSIX.1-2008 specification of 'b' in 'mode'
    Michael Kerrisk  [Rich Felker]
        BUGS: fmemopen() doesn't correctly set file position in some cases
            If 'mode' is append, but 'size' does not cover a null byte
            in 'buf', then fmemopen() incorrectly sets the initial file
            position to -1, rather than the next byte after the end of
            the buffer.

            See http://sourceware.org/bugzilla/show_bug.cgi?id=13151
    Michael Kerrisk
        BUGS: fmemopen() incorrectly handles size==0 case
            If size is zero, fmemopen() fails, This is surprising behavior,
            and not specified in POSIX.1-2008.

            See http://sourceware.org/bugzilla/show_bug.cgi?id=11216

            Reported-by; Alex Shinn
    Michael Kerrisk
        BUGS: Note silent ABI change for fmemopen() in glibc 2.9
    Michael Kerrisk  [Rich Felker]
        BUGS: Append mode does not force writes to append
            Append mode correctly sets the initial offset but does
            not force subsequent writes to append at end of stream.

            See http://sourceware.org/bugzilla/show_bug.cgi?id=13152
    Michael Kerrisk  [Eric Blake]
        BUGS: Note inconsistent treatment of 'b' in 'mode'
            fopen() permits, for example, both "w+b" and "wb+",
            but only the latter is meaningful to fmemopen().

            See http://sourceware.org/bugzilla/show_bug.cgi?id=12836

fopencookie.3
    Michael Kerrisk  [Petr Baudis]
        Correct description of return for user-supplied 'write' function
            See http://sourceware.org/bugzilla/show_bug.cgi?id=2074

getaddrinfo.3
    Jean-Michel VourgÃ¨re
        Note that AI_ADDRCONFIG is not affected by loopback addresses
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=660479

iconv.3
    Michael Kerrisk
        Upstream useful NOTE from Debian
            Warn the reader that the pointer arguments can't be
            interpreted as C style strings. Also, note possible
            alignment requirements for the referenced bytes sequences,
    Michael Kerrisk
        Write a better paragraph introducing iconv() and its arguments

isgreater.3
    Michael Kerrisk  [Vincent Lefevre]
        Clarify that the arguments to these macros must be real-floating
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=609033

lio_listio.3
    Michael Kerrisk
        Clarify that async notification occurs when *all* I/Os complete

makedev.3
    Michael Kerrisk
        SYNOPSIS: Correct return types of major() and minor()
            See https://bugzilla.redhat.com/show_bug.cgi?id=754188

            Reported-by; Zdenek Kabelac

malloc.3
    Michael Kerrisk
        SEE ALSO: Add malloc_info(3)

malloc_get_state.3
    Michael Kerrisk
        Fix wordos in function names in NAME line

mallopt.3
    Michael Kerrisk
        Fix example program
            The example code was a version that was not consistent with
            the shell output shown on the page.

            Reported-bY: Simon Paillard
    Michael Kerrisk
        Restore accidentally omitted line in shell session
    Michael Kerrisk
        SEE ALSO: Add malloc_stats(3)

mmap64.3
    Michael Kerrisk
        Change target of link to mmap.2 (was mmap2.2)
            Upstreamed from Red Hat / Fedora

realpath.3
    Michael Kerrisk  [Casper.Dik@oracle.com]
        Remove note about Solaris possibly returning a relative path

syslog.3
    Michael Kerrisk  [Ralph Corderoy]
        Document behavior when 'ident' argument to openlog() is NULL
            See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/382096
    Michael Kerrisk
        Update CONFORMING TO for POSIX.1-2008
            POSIX.1-2008 doesn't change any details, but make
            that more explicit.

undocumented.3
    Michael Kerrisk
        Remove some functions that have been documented

sd.4
    Michael Kerrisk
        Remove reference to nonexistent scsi(4) page
            Upstreamed from RedHat / Fedora

sk98lin.4
    Michael Kerrisk  [Stephen Hemminger]
        Note that this driver was removed in 2.6.28
            See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/528020

passwd.5
    Michael Kerrisk
        Upstream pieces from Red Hat/Fedora
            Note mention of empty password field.
            Add description of "*NP*" in password field.
    Michael Kerrisk
        Various minor fixes and improvements

proc.5
    Michael Kerrisk
        Note that CAP_SYS_ADMIN processes can override file-max
            Upstreamed from red Hat / Fedora
    Michael Kerrisk
        Document  /proc/[pid]/cgroup
            Upstreamed from Red Hat / Fedora

resolv.conf.5
    Michael Kerrisk
        Take a Debian improvement into upstream

tzfile.5
    Michael Kerrisk
        Mention timezone directories in DESCRIPTION
            Note that timezone files are usually in /usr/lib/zoneinfo
            or /usr/share/zoneinfo.
    Michael Kerrisk
        Drop SYNOPSIS
            The SYNOPSIS doesn't correspond to a user-visible file.
    Michael Kerrisk
        SEE ALSO: Add pointer to glibc source file timezone/tzfile.h
    Michael Kerrisk
        SEE ALSO: add tzset(3) and tzselect(8)

ascii.7
    Bjarni Ingi Gislason
        Indent for "troff" makes table too wide
            Fix following from "groff -t -ww ...":

                warning: around line 53: table wider than line width

            Extra indent for "troff" makes the table look misplaced
            (default "ps" output).

cp1251.7
    Bjarni Ingi Gislason
        table too wide
            From "nroff -ww -t ...":

                warning: around line 44: table wider than line width

            Columns are made narrower (column gutter decreased).

ipv6.7
    Stefan Puiu
        Add ENODEV error for bind() to link-local IPv6 address

signal.7
    Michael Kerrisk  [Simone Piccardi]
        Clarify that SIGLOST is unused
    Michael Kerrisk
        Comment out crufty BUGS text on SIGLOST
            It must be a very long time since the statement there
            about SIGLOST was true. (The text seems to date back to
            1996.)
    Michael Kerrisk
        Update architectures for tables of signal numbers

utf-8.7
    Brian M. Carlson
        Two clarifications
            This patch clarifies that 0xc0 and 0xc1 are not valid in any UTF-8
            encoding[0], and it also references RFC 3629 instead of RFC 2279.

            [0] In order to have 0xc0, you'd have to have a two-byte encoding
            with all the data bits zero in the first byte (and thus only six
            bits of data), which would be an ASCII character encoded in the
            non-shortest form.  Similarly with 0xc1.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=538641

ldconfig.8
nscd.8
    Michael Kerrisk
        Remove path prefix from NAME line
            Command names shown in NAME are normally just the basename,
            not the full pathname of the command.
top
==================== Changes in man-pages-3.42 ====================

Released: 2012-08-14, Konolfingen

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Aaron Peschel
Adrian Dabrowski
Akihiro MOTOKI
Alan Curry
Bjarni Ingi Gislason
Christoph Lameter
Colin McCabe
Daniel Zingaro
David PrÃ©vot
Denys Vlasenko
Henry Hu
Herbert Xu
Jan Engelhardt
Jim Hill
JoonSoo Kim
Kalle Olavi Niemitalo
Martin H
Michael Kerrisk
Michael S. Tsirkin
Rasmus Villemoes
Sami Kerola
Sam Varshavchik
Shawn Landden
Simon Paillard
Tolga Dalman
Ulrich Drepper
ÐœÐ°Ñ€Ðº ÐšÐ¾Ñ€ÐµÐ½Ð±ÐµÑ€Ð³

Apologies if I missed anyone!

Global changes
--------------

Various pages
    Sami Kerola
        Global fix: use UR macro where applicable
            The syntax .UR http://example.com paired with .UE will create
            links which one can interact, if the pager allows that.  One
            way to see the effect is ask the man(1) command to use browser
            display, e.g.:

                man -H man7/uri.7

            ("\:" is optional groff syntax to permit hyphenless line breaks.)

Changes to individual pages
---------------------------

ldd.1
    Michael Kerrisk
        Add security note on untrusted executables
            See also http://www.catonmat.net/blog/ldd-arbitrary-code-execution/
            and
            http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html

clone.2
    Michael Kerrisk
        Rewrite discussion of sys_clone

futex.2
    ÐœÐ°Ñ€Ðº ÐšÐ¾Ñ€ÐµÐ½Ð±ÐµÑ€Ð³
        Consolidate error descriptions to ERRORS
    Michael Kerrisk
        Various wording fix-ups
    Michael Kerrisk
        Fix description of EINVAL error
            The current text seems incorrect. Replace with a more general
            description.

getdents.2
select_tut.2
atof.3
atoi.3
pthread_create.3
pthread_sigmask.3
rtime.3
setbuf.3
tsearch.3
netlink.7
    Michael Kerrisk  [Jan Engelhardt]
        Remove unneeded casts

get_robust_list.2
get_thread_area.2
getcpu.2
getdents.2
gettid.2
io_cancel.2
io_destroy.2
io_getevents.2
io_setup.2
io_submit.2
ioprio_set.2
kexec_load.2
llseek.2
modify_ldt.2
mq_getsetattr.2
pivot_root.2
readdir.2
rt_sigqueueinfo.2
set_thread_area.2
sgetmask.2
spu_create.2
spu_run.2
subpage_prot.2
sysctl.2
tkill.2
    Michael Kerrisk
        Add note to SYNOPSIS that there is no glibc wrapper for system call
            Reduce the chance that the reader may be misled into thinking
            that there is a wrapper function for this system call by noting
            explicitly in the SYNOPSIS that there is no glibc wrapper and
            pointing the reader to NOTES for further details.

ioprio_set.2
    Colin McCabe
        Clarify the multithreaded behavior of ioprio_set(2)
    Michael Kerrisk  [ÐœÐ°Ñ€Ðº ÐšÐ¾Ñ€ÐµÐ½Ð±ÐµÑ€Ð³, Kalle Olavi Niemitalo]
        Document who==0 for IOPRIO_WHO_PROCESS and IOPRIO_WHO_PGRP
            For IOPRIO_WHO_PROCESS, who==0 means operate on the caller.
            For IOPRIO_WHO_PGRP, who==0 means operate on the caller's
            process group.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443

migrate_pages.2
    Michael Kerrisk  [Christoph Lameter, JoonSoo Kim]
        Fix description of return value

mount.2
    Michael Kerrisk
        For MS_REMOUNT, source is ignored

mprotect.2
    Michael Kerrisk  [Rasmus Villemoes]
        'addr' argument is not const
            As reported by Rasmus:

                Both my system's man-pages (3.22) and the latest online
                (3.41) show:

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

                as the prototype for mprotect(2). However, POSIX [1] and the
                actual sys/mman.h (on all the systems I checked) do not have
                the const qualifier on the first argument.

msgctl.2
semctl.2
shmctl.2
svipc.7
    Michael Kerrisk
        Don't mention that ipc_perm is defined in <sys/ipc.h>
            There's no need to mention that the 'ipc_perm' structure
            is defined in <sys/ipc.h>. That's an implementation detail,
            and furthermore <sys/ipc.h> is itself included by the other
            System V IPC header files. The current text might lead the
            reader to conclude that they must include <sys/ipc.h>, which
            is not the case (it is required neither on Linux, nor by the
            standards).

msgctl.2
msgget.2
msgop.2
semctl.2
semget.2
semop.2
shmctl.2
shmget.2
    Michael Kerrisk
        NOTES: <sys/types.h> and <sys/ipc.h> aren't strictly needed
            Add text to NOTES to say that the <sys/types.h> and <sys/ipc.h>
            header files aren't required by Linux or the standards, but may
            be needed for portability to old systems.

ptrace.2
    Denys Vlasenko
        Explain WNOHANG behavior and EINTR bug
            I didn't like the "SIGKILL operates similarly, with exceptions"
            phrase (if it's different, then it's not "similar", right?),
            and now I got around to changing it. Now it says simply:
            "SIGKILL does not generate signal-delivery-stop and therefore
            the tracer can't suppress it."

            Replaced "why WNOHANG is not reliable" example with a more
            realistic one (the one which actually inspired to add this
            information to man page in the first place): we got
            ESRCH - process is gone! - but waitpid(WNOHANG) can still
            confusingly return 0 "no processes to wait for".

            Replaced "This means that unneeded trailing arguments may
            be omitted" part with a much better recommendation
            to never do that and to supply zero arguments instead.
            (The part about "undocumentedness" of gcc behavior was bogus,
            btw - deleted).

            Expanded BUGS section with the explanation and an example
            of visible strace behavior on the buggy syscalls which
            exit with EINTR on ptrace attach. I hope this will lead
            to people submitting better bug reports to lkml about
            such syscalls.

seteuid.2
    Michael Kerrisk
        Note glibc version where setegid() implementation changed
            In glibc 2.2/2.3, setegid() switched from setregid() to setresgid().

set_tid_address.2
    Michael Kerrisk
        Rename 'ctid' argument for consistency with clone(2) page
    Michael Kerrisk
        Some rewordings and minor clarifications

sigwaitinfo.2
    Michael Kerrisk  [Daniel Zingaro]
        Some wording clarifications
            Mainly rewording things like "is delivered" to "becomes pending",
            which is more accurate terminology.

syscall.2
    Michael Kerrisk
        Add some more details to the description of syscall(2)
            And add another example of using syscall() to the program example.

syscalls.2
    Michael Kerrisk
        Add kcmp(2)
    Michael Kerrisk
        Move discussion of set_zone_reclaim(2) out of main table
            This system call was never visible to user space, so it makes
            sense to move it out of the main table of system calls into
            the notes below the table.

getifaddrs.3
    Michael Kerrisk  [Adrian Dabrowski]
        Note that ifa_addr and ifa_netmask can be NULL

readdir.3
    Michael Kerrisk  [Jan Engelhardt]
        Handle -1 error from pathconf() in example code snippet
            Improve the example demonstrating allocation of a buffer
            for readdir_r() to handle -1 error return from pathconf().
            Otherwise, naive readers may think that pathconf() return
            value can be used without checking.

realpath.3
    Shawn Landden
        Use past tense with ancient history (libc4, libc5)

regex.3
    Michael Kerrisk
        Correct SEE ALSO reference to glibc manual "regex" section

rtime.3
    Michael Kerrisk  [Jan Engelhardt]
        Fix broken pointer cast in example code

sem_close.3
sem_destroy.3
sem_getvalue.3
sem_init.3
sem_open.3
sem_post.3
sem_unlink.3
sem_wait.3
sem_overview.7
    Michael Kerrisk
        Note that "cc -pthread" is required; "-lrt" no longer works
            See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/874418

sigwait.3
    Michael Kerrisk
        Reword "is delivered" to "becomes pending"

strcat.3
    Michael Kerrisk
        Add some text to emphasize the dangers of buffer overruns
    Michael Kerrisk
        NOTES: Add discussion of strlcat()

strcpy.3
    Michael Kerrisk
        Note that info is lost when strncpy() doesn't null terminate
    Michael Kerrisk
        Add some text to emphasize possibility of buffer runs with strcpy()
    Michael Kerrisk
        NOTES: Add a discussion of strlcpy()
            Inspired by https://lwn.net/Articles/506530/
    Michael Kerrisk
        Fix description of the null-byte padding performed by strncpy()

tsearch.3
    Michael Kerrisk
        NOTES: remove redundant discussion of unorthodox use of term "postorder"
            This point is already covered at greater length in the main
            text of the page (See the piece "More commonly, ...").
    Michael Kerrisk
        Clarify use for first argument to the twalk() 'action' function
            There's a number of details in POSIX that are omitted in
            the current version of this page.
    Michael Kerrisk
        Some wording fixes

core.5
    Michael Kerrisk
        Note effect of madvise(2) MADV_DONTDUMP flag

capabilities.7
    Michael Kerrisk
        Document CAP_BLOCK_SUSPEND

glob.7
    Bjarni Ingi Gislason
        Change 8 bit characters to 7 bit representation
            Fixes rendering errors for accented 'a' characters.
    Michael Kerrisk  [Aaron Peschel]
        Update bash(1) command used to obtain classical globbing behavior
            The man page formerly noted the bash(1) v1 command to do this.

iso_8859-1.7
    Bjarni Ingi Gislason
        Explanation of SOFT HYPHEN and the code for it
            <groff: iso_8859-2.7>:89: warning: can't find special character `shc'

            This is the only "iso_8859-*.7" file that has this (now)
            undefined character.  The code in column four in "iso_8859-1.7" is
            "0x2D" ("HYPHEN, MINUS SIGN" or "HYPHEN-MINUS") instead of "0xAD".
            See Debian bug 156154 (or package "manpages").

            There should be an explanation for this graphic character and the
            code should be 0xAD in iso_8859-1.7 (as in all others), even
            though "[gn]roff" does not display a "HYPHEN" in that position of
            the table.

            The line with "SOFT HYPHEN" gets a footnote and a short
            explanation.

mdoc.7
    Bjarni Ingi Gislason
        Fixing a warning and a table
            Fis warning from "groff -ww ..." (or "man --warnings=w ..."):

                <groff: mdoc.7>:294: warning:
                tab character in unquoted macro argument

            In one table the distance between columns is too small in the
            "ps" output.  (Bug in the groff "doc.tmac" macro?)

mdoc.samples.7
    Bjarni Ingi Gislason
        Fix warnings from [ng]roff, corrections
            From "man -ww ..." (groff -ww ...):

                <standard input>:541: warning:
                tab character in unquoted macro argument
                [+3 similar warnings]
                <standard input>:813: warning: macro `Pu' not defined
                Usage: .Rv -std in sections 2 and 3 only (#1669)
                mdoc warning: A .Bl directive has no matching .El (#1821)

            String "Pu" defined as a row of punctuation characters.
            ".Bl" and ".El" fixed.
            Some arguments, that start with a period or are the name of a
            macro, protected with "\&".
            Variable name for macro ".Rv" corrected.

netdevice.7
    Bjarni Ingi Gislason
        Line in table too long
            Fix warning from "man ..." ("nroff -ww ..."):

                nroff: netdevice.7: warning: around line 98:
                table wider than line width

            Fix: No right adjustment in text blocks in tables.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673873

netlink.7
    Bjarni Ingi Gislason
        Line in table is too long
            Fix warning from "man ..." ("nroff -ww ..."):

                nroff: netlink.7: warning: around line 195:
                table wider than line width

            Horizontal line incorporated into table.
            No right adjustment of text blocks in tables.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673875
    Simon Paillard  [Herbert Xu]
        Change description of "*_pid" fields to "Port ID"
            As reported by Herbert Xu, these should not be considered as PIDs.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=383296

rtnetlink.7
    Bjarni Ingi Gislason
        Line in table too long
            Fix warning from "man ..." ("nroff -ww ..."):

                nroff: rtnetlink.7: warning: around line 415:
                table wider than line width

            Column gutter reduced to fit line length.
            Right adjustment in text blocks removed in tables.
            Some header made centered in tables.
            One table put on same page.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=674051

socket.7
    Martin H
        Document SO_MARK socket option
            Commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 in Jan 2008 added
            the new SO_MARK socket option.

            This patch is based on text from the commit message.

            See https://bugzilla.kernel.org/show_bug.cgi?id=16461.

svipc.7
    Michael Kerrisk
        SYNOPSIS: Remove include of <sys/types.h> and <sys/ipc.h>
            Including <sys/types.h> and <sys/ipc.h> isn't needed on Linux
            and isn't really relevant for the explanation on this page.
top
==================== Changes in man-pages-3.43 ====================

Released: 2012-10-05, Munich

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Adrian Bunk
Anatoli Klassen
Andreas Schwab
Bjarni Ingi Gislason
David PrÃ©vot
Eric Dumazet
Florian Weimer
FrÃ©dÃ©ric BriÃ¨re
Fredrik Arnerup
Guillem Jover
Jan Engelhardt
Michael Kerrisk
Simon Josefsson
Stephane Fillod
Trevor Woerner
Yuri Kozlov

Apologies if I missed anyone!

Newly documented interfaces in existing pages
---------------------------------------------

getenv.3
    Michael Kerrisk  [Florian Weimer, Andreas Schwab]
        Document secure_getenv(3)

New and changed links
---------------------

phys.2
    Michael Kerrisk
        New link to unimplemented.2

secure_getenv.3
    Michael Kerrisk
        New link to getenv.3

Global changes
--------------

Various pages
    Michael Kerrisk
        Global fix: s/-/\\-/ when real hyphen is required (e.g., in code)

Various pages
    David PrÃ©vot [Michael Kerrisk]
        Global fix: Various consistency fixes for SEE ALSO

Various pages
    Michael Kerrisk
        Global fix: use "Linux kernel source" consistently
            Rather than "kernel source".

Various pages
    Michael Kerrisk
        Global fix: disable justification and hyphenation in SEE ALSO
            For a better visual result, disable justification and hyphenation
            in SEE ALSO where page names are long.

syscalls.2
uname.2
boot.7
    Michael Kerrisk
        Global fix: s/OS/operating system/

Changes to individual pages
---------------------------

epoll_wait.2
    Michael Kerrisk  [Fredrik Arnerup]
        Describe timeout limitation in kernels < 2.6.37
            As reported by Fredrik (and as far as I can tell the problem
            went back to 2.6.0):

            The timeout argument has an upper limit. Any values above that
            limit are treated the same as -1, i.e. to wait indefinitely.
            The limit is given by:

                #define EP_MAX_MSTIMEO min(1000ULL * MAX_SCHEDULE_TIMEOUT / HZ, \
                (LONG_MAX - 999ULL) / HZ)

            That is, the limit depends on the size of a long and the timer
            frequency.  Assuming the a long is never smaller than 32 bits
            and HZ never larger than 1000, the worst case is 35 minutes.
            I think this should be mentioned under "BUGS".

            Although this is likely to be fixed in the future
            (http://lkml.org/lkml/2010/8/8/144), the problem exists in
            at least 2.6.14 - 2.6.35. I don't know if select(2) and poll(2)
            are affected.

            https://bugzilla.kernel.org/show_bug.cgi?id=20762
    Michael Kerrisk
        Add pointer to select(2) for discussion of close in another thread

getitimer.2
    Michael Kerrisk  [Trevor Woerner]
        Note Linux's odd handling of the new_value==NULL case
    Michael Kerrisk  [Trevor Woerner]
        Fix types used to declare fields in timeval struct

keyctl.2
    David PrÃ©vot
        Reorder SEE ALSO, without .br

poll.2
    Michael Kerrisk
        Add pointer to select(2) for discussion of close in another thread

select.2
    Michael Kerrisk  [Stephane Fillod]
        Note behavior if monitored file descriptor is closed in another thread
            Executive summary: a sane application can't rely on any
            particular behavior if another thread closes a file descriptor
            being monitored by select().

            See https://bugzilla.kernel.org/show_bug.cgi?id=40852
    Michael Kerrisk
        Clarify equivalent pselect() code in terms of threads
            s/sigprogmask/pthread_sigmask/

semop.2
    Michael Kerrisk
        Recast discussion of blocking behavior in terms of threads
            semop() blocks the calling thread, not the process.
    Michael Kerrisk
        SEE ALSO: Add clone(2)
            Give reader a clue about CLONE_SYSVSEM.

shutdown.2
    Michael Kerrisk  [Eric Dumazet]
        Document EINVAL error (and associated bug)
            Eric Dumazet noted that EINVAL was not documented. Some further
            digging shows that it's also not diagnosed consistently.
            See https://bugzilla.kernel.org/show_bug.cgi?id=47111.

sigaction.2
    Michael Kerrisk
        Tweak SA_RESETHAND description

timer_settime.2
    Michael Kerrisk
        Small rewording around discussion of pointer arguments

wait4.2
    Adrian Bunk
        Note that these functions are nonstandard and recommend alternatives
            Some edits to Adrian's patch by mtk.
    Michael Kerrisk
        CONFORMING TO: Note SUS details for wait3()

gnu_get_libc_version.3
    Michael Kerrisk
        Remove unneeded "#define _GNU_SOURCE" from SYNOPSIS

pthread_kill.3
pthread_sigqueue.3
    Michael Kerrisk
        Remove wording "another"
            Writing "another thread" in these pages implies that these
            functions can't be used to send a signal to the calling thread
            itself, which is of course untrue.

sigvec.3
    Michael Kerrisk
        Add "int" arg to sv_handler definition in sigvec structure
    Michael Kerrisk
        Fix small error in discussion of blocking of signals
            The signal that causes the handler to be invoked is blocked,
            but saying "by default" implies that this can be changed via
            the API. It cannot. (One needs sigaction(2) for that.)

syslog.3
    Simon Josefsson
        Remove (apparently bogus) text claiming LOG_AUTH is deprecated
            LOG_AUTH is in POSIX, and widely available. There
            seems to be no basis to the claim it is deprecated.

            Quoting Simon:
                I cannot find any other source that claim LOG_AUTH is
                deprecated in any way.  LOG_AUTH is distinct from
                LOG_AUTHPRIV.  The GNU C Library manual only documents
                LOG_AUTH.  The header files contains both without any
                comment.  Common systems like Debian appear to refer to
                both auth and authpriv facilities in syslog configurations.
                Popular daemons appear to use both facilities.
                Both facilities are discussed in several RFCs.

            See https://bugzilla.kernel.org/show_bug.cgi?id=46091

ttyname.3
    Michael Kerrisk
        SEE ALSO: Add ctermid(3)

proc.5
    Michael Kerrisk
        Clarify header file related to 'flags' field of /proc/PID/stat
    Michael Kerrisk  [FrÃ©dÃ©ric BriÃ¨re]
        Update description of 'starttime' field of /proc/PID/stat
            The unit of measurement changed from jiffies to clock ticks in
            Linux 2.6.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=675891
    Michael Kerrisk
        Document /proc/sys/kernel/kptr_restrict
    Michael Kerrisk [Kees Cook]
        Document /proc/sys/fs/protected_symlinks
            Based on text in Documentation/sysctl/fs.txt by Kees Cook
    Michael Kerrisk [Kees Cook]
        Document /proc/sys/fs/protected_hardlinks
            Based on text in Documentation/sysctl/fs.txt by Kees Cook

capabilities.7
    Michael Kerrisk
        Document interaction of CAP_SYSLOG and /proc/sys/kernel/kptr_restrict

ip.7
    Michael Kerrisk
        SEE ALSO: Add ipv6(7)
        SEE ALSO: Add icmp(7)

man-pages.7
    Michael Kerrisk
        Add some advice about disabling hyphenation in SEE ALSO

ld.so.8
    Michael Kerrisk
        Describe interpretation of slashes in dependency strings
    Michael Kerrisk
        Repeat note that LD_LIBRARY_PATH is ignored in privileged programs
            This point is already noted when discussing search order for
            libraries, but it's worth repeating under the specific discussion
            of LD_LIBRARY_PATH further down the page.
    Michael Kerrisk
        Add some details for LD_PRELOAD
        Note that LD_PRELOAD list separator can be space or colon
top
==================== Changes in man-pages-3.44 ====================

Released: 2012-11-07, Barcelona

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Bert Hubert
David PrÃ©vot
James Youngman
Kees Cook
Lars Wirzenius
Lucas De Marchi
Michael Kerrisk
Rusty Russell
Simon Paillard
Thomas Habets

Apologies if I missed anyone!

New and rewritten pages
-----------------------

delete_module.2
    Michael Kerrisk
        Rewrite to Linux 2.6+ reality
    Michael Kerrisk
        Change license and copyright
            There is now nothing left of the original FSF-copyrighted
            page. So, change the copyright and license.
    Michael Kerrisk  [Lucas De Marchi, Rusty Russell]
        Substantial reorganization after comments from Rusty Russell
            Rusty notes that O_NONBLOCK is almost always used in
            practice. Therefore, it would be better to reorganize
            the page to consider that "the default".

init_module.2
    Michael Kerrisk
        Rewrite to Linux 2.6+ reality
    Michael Kerrisk
        Change copyright and license
            Little of the original page now remains. Change
            copyright and license
    Michael Kerrisk  [Rusty Russell]
        Changes after review comments from Rusty Russell
    Kees Cook
        Add various pieces describing Linux 2.6+ behavior
            Pieces take from, or inspired by, a patch sent by Kees.

getauxval.3
    Michael Kerrisk
        Document getauxval() function added in glibc 2.16

Global changes
--------------

Various pages
    Michael Kerrisk
        Global fix: Use consistent capitalization in NAME section
            The line(s) in the NAME section should only use capitals
            where English usage dictates that. Otherwise, use
            lowercase throughout.

Various pages
    Michael Kerrisk
        Global fix: "userspace" ==> "user space" or "user-space"
            Existing pages variously use "userspace or "user space".
            But, "userspace" is not quite an English word.
            So change "userspace" to "user space" or, when used
            attributively, "user-space".

Changes to individual pages
---------------------------

clock_getres.2
clock_nanosleep.2
    Michael Kerrisk
        Linking with -lrt is no longer needed from glibc 2.17 onward

create_module.2
    Michael Kerrisk
        Note that this system call is present only in kernels before 2.6
    Michael Kerrisk
        Note that ENOSYS probably indicates kernel 2.6+

execve.2
    Michael Kerrisk
        Document treatment of PR_SET_PDEATHSIG on execve()
    Michael Kerrisk
        Document treatment of SECBIT_KEEP_CAPS securebits flag on execve()

fork.2
    Michael Kerrisk
        Note treatment of default timer slack value on fork()

getdomainname.2
    Simon Paillard  [Lars Wirzenius]
        Point out that these calls relate to NIS, not DNS
            See http://bugs.debian.org/295635

get_kernel_syms.2
    Michael Kerrisk
        Note that this system call is present only in kernels before 2.6

ipc.2
    Michael Kerrisk
        Update note on architectures that don't have ipc()
            Replace mention of ia64 with x86-64 and ARM.

link.2
    Michael Kerrisk
        Add EPERM error triggered by /proc/sys/fs/protected_hardlink

prctl.2
    Michael Kerrisk
        Mention Documentation/prctl/no_new_privs.txt for PR_SET_NO_NEW_PRIVS
    Kees Cook
        update seccomp sections for mode 2 (BPF)
            This adds a short summary of the arguments used
            for "mode 2" (BPF) seccomp.
    Michael Kerrisk
        Small improvements to PR_SET_SECCOMP discussion
            Note type of 'arg3' for SECCOMP_MODE_FILTER.
            Add pointer to Documentation/prctl/seccomp_filter.txt.
    Michael Kerrisk
        Note 'seccomp' semantics with respect to fork(), execve(), and prctl()
    Michael Kerrisk
        Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK
    Michael Kerrisk
        Reword PR_SET_NAME and PR_GET_NAME in terms of threads
            Plus tfix
    Kees Cook
        document PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS
            This adds a short description of the no_new_privs bit,
            as described in Documentation/prctl/no_new_privs.txt.

ptrace.2
    Michael Kerrisk
        Clarify that some operations are not present on all architectures
            PTRACE_GETREGS, PTRACE_SETGREFS, PTRACE_GETFPREGS,
            and PTRACE_GETSPREGS are not present on all architectures.
            PTRACE_SYSEMU and PTRACE_SYSEMU_SINGLESTEP are present only
            on x86.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=122383

query_module.2
    Michael Kerrisk
        Add a few words clarifying reference to /sys/module
    Michael Kerrisk
        Note that this system call is present only in kernels before 2.6
    Michael Kerrisk
        Note that ENOSYS probably indicates kernel 2.6+
    Michael Kerrisk
        SEE ALSO: Add modinfo(8) and lsinfo(8)
    Michael Kerrisk
        Move some information in NOTES to VERSIONS

socketcall.2
    Michael Kerrisk
        Update note on architectures that don't have socketcall()
            Replace mention of ia64 with x86-64 and ARM.

times.2
    Thomas Habets
        Recommend clock_gettime(2) as alternative to times(2)

clock_getcpuclockid.3
    Michael Kerrisk
        Linking with -lrt is no longer needed from glibc 2.17 onward

fts.3
    Simon Paillard  [James Youngman]
        Improve description of physical vs. logical tree walking
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=633505

getenv.3
    Michael Kerrisk
        SEE ALSO: add getauxval(3)

proc.5
    Michael Kerrisk
        Document /proc/meminfo
            Info mostly taken from Documentation/filesystems/proc.txt
            and Documentation/vm/hugetlbpage.txt.
    Michael Kerrisk
        Default for /proc/sys/fs/protected_{hardlinks,symlinks} is now 0
            The default setting of 1 in/proc/sys/fs/protected_hardlinks
            and /proc/sys/fs/protected_symlinks caused one too many
            breakages for Linus's taste, so commit 561ec64ae67e changed
            the default for both files to 0.
        Note system call error yielded by /proc/sys/fs/protected_symlinks
            Note that violating 'protected_symlinks' restrictions
            causes system calls to fail with the error EACCES.
    Michael Kerrisk
        Since Linux 2.6.27, /proc/sys/kernel/modprobe depends on CONFIG_MODULES

ipv6.7
    Bert Hubert
        Document IPV6_RECVPKTINFO

man-pages.7
    Michael Kerrisk
        Note rules for capitalization in NAME section

time.7
    Michael Kerrisk
        Add a subsection on timer slack

ld.so.8
    Michael Kerrisk
        SEE ALSO: add getauxval(3)
top
==================== Changes in man-pages-3.45 ====================

Released: 2012-12-21, Christchurch

Contributors
------------

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Andi Kleen
Cyril Hrubis
David PrÃ©vot
Elie De Brauwer
Eric Dumazet
Felipe Pena
Florian Weimer
Gao Feng
Jan Glauber
Jim Paris
Jon Grant
Julien Cristau
Michael Kerrisk
Mike Frysinger
Rens van der Heijden
Simon Paillard
Thierry Vignaud
Trevor Woerner
YOSHIFUJI Hideaki

Apologies if I missed anyone!

New and rewritten pages
-----------------------

s390_runtime_instr.2
    Jan Glauber
        New page for s390-specific s390_runtime_instr(2)

if_nameindex.3
    YOSHIFUJI Hideaki
        Document if_nameindex(3) and if_freenameindex(3)
    Michael Kerrisk
        Edits, improvements and corrections to Hideaki's page
    Michael Kerrisk
        Add an example program

if_nametoindex.3
    YOSHIFUJI Hideaki
        New page documenting if_nametoindex(3) and if_indextoname(3)

Newly documented interfaces in existing pages
---------------------------------------------

New and changed links
---------------------

if_freenameindex.3
    Michael Kerrisk
        New link to if_nameindex.3

if_indextoname.3
    Michael Kerrisk
        New link to if_nametoindex.3

Global changes
--------------

sysconf.3
cciss.4
    Michael Kerrisk
        Global fix: s/runtime/run time/

Changes to individual pages
---------------------------

clone.2
    Michael Kerrisk
        Since 2.6.30, CLONE_NEWIPC also supports POSIX message queues

delete_module.2
    Michael Kerrisk
        Small rewording of description of effect of O_TRUNC

getrlimit.2
    Michael Kerrisk  [Trevor Woerner]
        Document Linux's nonstandard treatment or RLIMIT_CPU soft limit
            Upon encountering the RLIMIT_CPU soft limit when a SIGXCPU handler
            has been installed, Linux invokes the signal handler *and* raises
            the soft limit by one second. This behavior repeats until the
            limit is encountered.  No other implementation that I tested
            (Solaris 10, FreeBSD 9.0, OpenBSD 5.0) does this, and it seems
            unlikely to be POSIX-conformant. The (Linux-specific)
            RLIMIT_RTTIME soft limit exhibits similar behavior.
    Michael Kerrisk
        Point reader at discussion of /proc/[pid]/limits in proc(5)

io_getevents.2
    Michael Kerrisk
        io_getevents() may cause segfault when called with invalid ctx_id
            For reference see: http://marc.info/?l=linux-aio&m=130089887002435&w=2

recv.2
    Michael Kerrisk  [Eric Dumazet]
        UNIX domain sockets support MSG_TRUNC since 3.4

sendmmsg.2
    Elie De Brauwer
        Add example program for sendmmsg()

stat.2
    Simon Paillard
        Clarify description of EOVERFLOW error
            The EOVERFLOW error is not only for st_size, but also
            inode and block size fields. See glibc source file
            sysdeps/unix/sysv/linux/xstatconv.c and kernel source
            file fs/stat.c. Also, fix bit/byte confusion
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=604928

syscalls.2
    Michael Kerrisk
        Update various references to "i386" to "x86"
    Michael Kerrisk
        Add s390_runtime_instr(2)

sysctl.2
    Michael Kerrisk
        Mention CONFIG_SYSCTL_SYSCALL
    Michael Kerrisk
        Calls to sysctl() log warnings to the kernel log since 2.6.24

syslog.2
    Michael Kerrisk
        Substantially reorganize discussion of commands
            Make the layout of the discussion of the commands
            more readable.
    Michael Kerrisk
        Add kernel symbolic 'type' names
    Michael Kerrisk
        Clarify SYSLOG_ACTION_SIZE_UNREAD semantics
            SYSLOG_ACTION_SIZE_UNREAD returns the number of bytes
            available for reading via SYSLOG_ACTION_READ.
    Michael Kerrisk
        Clarify where SYSLOG_ACTION_READ_ALL places data it reads
    Michael Kerrisk
        Clarify semantics of SYSLOG_ACTION_CLEAR
            The SYSLOG_ACTION_CLEAR command (5) does not really clear
            the ring buffer; rather it affects the semantics of what
            is returned by commands 3 (SYSLOG_ACTION_READ_ALL) and
            4 (SYSLOG_ACTION_READ_CLEAR).
    Michael Kerrisk
        Clarify discussion of privileges for commands 3 and 10
    Michael Kerrisk
        Add mention of CONFIG_LOG_BUF_SHIFT

wait.2
    Michael Kerrisk
        BUGS: Document odd waitid() behavior when 'infop' is NULL

getifaddrs.3
    Michael Kerrisk  [Julien Cristau]
        Update description of ifa_data to Linux 2.6+ reality
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=526778

memcmp.3
    Michael Kerrisk  [Jon Grant]
        Enhance RETURN VALUE text and remove redundant text from DESCRIPTION
            Note that sign of result equals sign of difference between
            first two bytes that differ (treated as "unsigned char")."

mkstemp.3
    Michael Kerrisk  [Florian Weimer]
        Deemphasize discussion of mode 066 in glibc 2.0.6
            Glibc 2.0.6 is now so ld that the discussion of details
            of that version can be deemphasized placing just under
            NOTES.

            See https://bugzilla.kernel.org/show_bug.cgi?id=51811

strcmp.3
    Michael Kerrisk  [Jon Grant]
        Enhance RETURN VALUE text and remove redundant text from DESCRIPTION
            Note that sign of result equals sign of difference between
            first two bytes that differ (treated as "unsigned char")."

ttyname.3
    Michael Kerrisk
        Fix confused text in ERRORS
            The existing text suggested that the ERRORS applied
            only for ttyname_r(). However, 2 of the 3 errors
            can occur for ttyname().

undocumented.3
    Michael Kerrisk
        Remove some now documented functions

proc.5
    Michael Kerrisk  [Jim Paris]
        Correct description of SwapFree in /proc/meminfo
    Michael Kerrisk
        Note change of /proc/[pid]/limits file permissions in 2.6.36

resolv.conf.5
    Simon Paillard
        Document IPv6 format for nameserver
            See: http://bugs.debian.org/610036

capabilities.7
    Michael Kerrisk  [Rens van der Heijden]
        Correct URL for POSIX.1e draft

ipv6.7
    Gao Feng
        Add description of getsockopt() for IPV6_MTU
            In IPv4,IP_MTU is only supported by getsockopt.
            In IPv6, we can use IPV6_MTU to set socket's MTU,
            but the return value of getsockopt() is the path MTU.

rtnetlink.7
    Michael Kerrisk  [Julien Cristau]
        Update description of IFLA_STATS to Linux 2.6+ reality
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=526778

socket.7
    Michael Kerrisk  [YOSHIFUJI Hideaki]
        Document 'sockaddr' and 'sockaddr_storage' types
    Andi Kleen
        Explain effect of SO_SNDTIMEO for connect()
            When SO_SNDTIMEO is set before connect(), then connect()
            may return EWOULDBLOCK when the timeout fires.
top


charmap(5) - Linux manual page

NAME | DESCRIPTION | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CHARMAP(5)                       Linux User Manual                      CHARMAP(5)

NAME top

       charmap - character symbols to define character encodings

DESCRIPTION top

       A character set description (charmap) defines a character set of available
       characters and their encodings.  All supported character sets should have
       the portable character set as a proper subset.

Syntax

       The charmap file starts with a header, that may consist of the following
       keywords:

       <codeset>
              is followed by the name of the codeset.

       <mb_cur_max>
              is followed by the max number of bytes for a multibyte-character.
              Multibyte characters are currently not supported.  The default value
              is 1.

       <mb_cur_min>
              is followed by the min number of bytes for a character.  This value
              must be less or equal than mb_cur_max.  If not specified, it
              defaults to mb_cur_max.

       <escape_char>
              is followed by a character that should be used as the escape-
              character for the rest of the file to mark characters that should be
              interpreted in a special way.  It defaults to the backslash ( \ ).

       <comment_char>
              is followed by a character that will be used as the comment-
              character for the rest of the file.  It defaults to the number sign
              ( # ).

       The charmap-definition itself starts with the keyword CHARMAP in column 1.

       The following lines may have one of the two following forms to define the
       character-encodings:

       <symbolic-name> <encoding> <comments>
              This form defines exactly one character and its encoding.

       <symbolic-name>...<symbolic-name> <encoding> <comments>
              This form defines a couple of characters.  This is only useful for
              multibyte-characters, which are currently not implemented.

       The last line in a charmap-definition file must contain END CHARMAP.

Symbolic Names

       A symbolic name for a character contains only characters of the portable
       character set.  The name itself is enclosed between angle brackets.
       Characters following an <escape_char> are interpreted as itself; for
       example, the sequence <\\\>> represents the symbolic name \> enclosed in
       angle brackets.

Character Encoding

       The encoding may be in each of the following three forms:

       <escape_char>d<number>
              with a decimal number

       <escape_char>x<number>
              with a hexadecimal number

       <escape_char><number>
              with an octal number.

FILES top

       /usr/share/i18n/charmaps/*

CONFORMING TO top

       POSIX.2.

SEE ALSO top

       locale(1), localedef(1), localeconv(3), setlocale(3), locale(5)

COLOPHON top

       This page is part of release 3.45 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/.

                                    1994-11-28                          CHARMAP(5)


charsets(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

CHARSETS(7)                  Linux Programmer's Manual                 CHARSETS(7)

NAME top

       charsets - programmer's view of character sets and internationalization

DESCRIPTION top

       Linux is an international operating system.  Various of its utilities and
       device drivers (including the console driver) support multilingual
       character sets including Latin-alphabet letters with diacritical marks,
       accents, ligatures, and entire non-Latin alphabets including Greek,
       Cyrillic, Arabic, and Hebrew.

       This manual page presents a programmer's-eye view of different character-
       set standards and how they fit together on Linux.  Standards discussed
       include ASCII, ISO 8859, KOI8-R, Unicode, ISO 2022 and ISO 4873.  The
       primary emphasis is on character sets actually used as locale character
       sets, not the myriad others that can be found in data from other systems.

       A complete list of charsets used in an officially supported locale in glibc
       2.2.3 is: ISO-8859-{1,2,3,5,6,7,8,9,13,15}, CP1251, UTF-8, EUC-{KR,JP,TW},
       KOI8-{R,U}, GB2312, GB18030, GBK, BIG5, BIG5-HKSCS and TIS-620 (in no
       particular order.)  (Romanian may be switching to ISO-8859-16.)

ASCII

       ASCII (American Standard Code For Information Interchange) is the original
       7-bit character set, originally designed for American English.  It is
       currently described by the ECMA-6 standard.

       Various ASCII variants replacing the dollar sign with other currency
       symbols and replacing punctuation with non-English alphabetic characters to
       cover German, French, Spanish and others in 7 bits exist.  All are
       deprecated; glibc doesn't support locales whose character sets aren't true
       supersets of ASCII.  (These sets are also known as ISO-646, a close
       relative of ASCII that permitted replacing these characters.)

       As Linux was written for hardware designed in the US, it natively supports
       ASCII.

ISO 8859

       ISO 8859 is a series of 15 8-bit character sets all of which have US ASCII
       in their low (7-bit) half, invisible control characters in positions 128 to
       159, and 96 fixed-width graphics in positions 160-255.

       Of these, the most important is ISO 8859-1 (Latin-1).  It is natively
       supported in the Linux console driver, fairly well supported in X11R6, and
       is the base character set of HTML.

       Console support for the other 8859 character sets is available under Linux
       through user-mode utilities (such as setfont(8)) that modify keyboard
       bindings and the EGA graphics table and employ the "user mapping" font
       table in the console driver.

       Here are brief descriptions of each set:

       8859-1 (Latin-1)
              Latin-1 covers most Western European languages such as Albanian,
              Catalan, Danish, Dutch, English, Faroese, Finnish, French, German,
              Galician, Irish, Icelandic, Italian, Norwegian, Portuguese, Spanish,
              and Swedish.  The lack of the ligatures Dutch ij, French oe and old-
              style ,,German`` quotation marks is considered tolerable.

       8859-2 (Latin-2)
              Latin-2 supports most Latin-written Slavic and Central European
              languages: Croatian, Czech, German, Hungarian, Polish, Rumanian,
              Slovak, and Slovene.

       8859-3 (Latin-3)
              Latin-3 is popular with authors of Esperanto, Galician, and Maltese.
              (Turkish is now written with 8859-9 instead.)

       8859-4 (Latin-4)
              Latin-4 introduced letters for Estonian, Latvian, and Lithuanian.
              It is essentially obsolete; see 8859-10 (Latin-6) and 8859-13
              (Latin-7).

       8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian,
              Russian, Serbian and Ukrainian.  Ukrainians read the letter "ghe"
              with downstroke as "heh" and would need a ghe with upstroke to write
              a correct ghe.  See the discussion of KOI8-R below.

       8859-6 Supports Arabic.  The 8859-6 glyph table is a fixed font of separate
              letter forms, but a proper display engine should combine these using
              the proper initial, medial, and final forms.

       8859-7 Supports Modern Greek.

       8859-8 Supports modern Hebrew without niqud (punctuation signs).  Niqud and
              full-fledged Biblical Hebrew are outside the scope of this character
              set; under Linux, UTF-8 is the preferred encoding for these.

       8859-9 (Latin-5)
              This is a variant of Latin-1 that replaces Icelandic letters with
              Turkish ones.

       8859-10 (Latin-6)
              Latin 6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters
              that were missing in Latin 4 to cover the entire Nordic area.  RFC
              1345 listed a preliminary and different "latin6".  Skolt Sami still
              needs a few more accents than these.

       8859-11
              This only exists as a rejected draft standard.  The draft standard
              was identical to TIS-620, which is used under Linux for Thai.

       8859-12
              This set does not exist.  While Vietnamese has been suggested for
              this space, it does not fit within the 96 (noncombining) characters
              ISO 8859 offers.  UTF-8 is the preferred character set for
              Vietnamese use under Linux.

       8859-13 (Latin-7)
              Supports the Baltic Rim languages; in particular, it includes
              Latvian characters not found in Latin-4.

       8859-14 (Latin-8)
              This is the Celtic character set, covering Gaelic and Welsh.  This
              charset also contains the dotted characters needed for Old Irish.

       8859-15 (Latin-9)
              This adds the Euro sign and French and Finnish letters that were
              missing in Latin-1.

       8859-16 (Latin-10)
              This set covers many of the languages covered by 8859-2, and
              supports Romanian more completely then that set does.

KOI8-R

       KOI8-R is a non-ISO character set popular in Russia.  The lower half is US
       ASCII; the upper is a Cyrillic character set somewhat better designed than
       ISO 8859-5.  KOI8-U is a common character set, based off KOI8-R, that has
       better support for Ukrainian.  Neither of these sets are ISO-2022
       compatible, unlike the ISO-8859 series.

       Console support for KOI8-R is available under Linux through user-mode
       utilities that modify keyboard bindings and the EGA graphics table, and
       employ the "user mapping" font table in the console driver.

JIS X 0208

       JIS X 0208 is a Japanese national standard character set.  Though there are
       some more Japanese national standard character sets (like JIS X 0201, JIS X
       0212, and JIS X 0213), this is the most important one.  Characters are
       mapped into a 94x94 two-byte matrix, whose each byte is in the range
       0x21-0x7e.  Note that JIS X 0208 is a character set, not an encoding.  This
       means that JIS X 0208 itself is not used for expressing text data.  JIS X
       0208 is used as a component to construct encodings such as EUC-JP,
       Shift_JIS, and ISO-2022-JP.  EUC-JP is the most important encoding for
       Linux and includes US ASCII and JIS X 0208.  In EUC-JP, JIS X 0208
       characters are expressed in two bytes, each of which is the JIS X 0208 code
       plus 0x80.

KS X 1001

       KS X 1001 is a Korean national standard character set.  Just as JIS X 0208,
       characters are mapped into a 94x94 two-byte matrix.  KS X 1001 is used like
       JIS X 0208, as a component to construct encodings such as EUC-KR, Johab,
       and ISO-2022-KR.  EUC-KR is the most important encoding for Linux and
       includes US ASCII and KS X 1001.  KS C 5601 is an older name for KS X 1001.

GB 2312

       GB 2312 is a mainland Chinese national standard character set used to
       express simplified Chinese.  Just like JIS X 0208, characters are mapped
       into a 94x94 two-byte matrix used to construct EUC-CN.  EUC-CN is the most
       important encoding for Linux and includes US ASCII and GB 2312.  Note that
       EUC-CN is often called as GB, GB 2312, or CN-GB.

Big5

       Big5 is a popular character set in Taiwan to express traditional Chinese.
       (Big5 is both a character set and an encoding.)  It is a superset of US
       ASCII.  Non-ASCII characters are expressed in two bytes.  Bytes 0xa1-0xfe
       are used as leading bytes for two-byte characters.  Big5 and its extension
       is widely used in Taiwan and Hong Kong.  It is not ISO 2022-compliant.

TIS 620

       TIS 620 is a Thai national standard character set and a superset of US
       ASCII.  Like ISO 8859 series, Thai characters are mapped into 0xa1-0xfe.
       TIS 620 is the only commonly used character set under Linux besides UTF-8
       to have combining characters.

UNICODE

       Unicode (ISO 10646) is a standard which aims to unambiguously represent
       every character in every human language.  Unicode's structure permits 20.1
       bits to encode every character.  Since most computers don't include
       20.1-bit integers, Unicode is usually encoded as 32-bit integers internally
       and either a series of 16-bit integers (UTF-16) (needing two 16-bit
       integers only when encoding certain rare characters) or a series of 8-bit
       bytes (UTF-8).  Information on Unicode is available at
       <http://www.unicode.org>.

       Linux represents Unicode using the 8-bit Unicode Transformation Format
       (UTF-8).  UTF-8 is a variable length encoding of Unicode.  It uses 1 byte
       to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21
       bits, 5 bytes for 26 bits, 6 bytes for 31 bits.

       Let 0,1,x stand for a zero, one, or arbitrary bit.  A byte 0xxxxxxx stands
       for the Unicode 00000000 0xxxxxxx which codes the same symbol as the ASCII
       0xxxxxxx.  Thus, ASCII goes unchanged into UTF-8, and people using only
       ASCII do not notice any change: not in code, and not in file size.

       A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy is
       assembled into 00000xxx xxyyyyyy.  A byte 1110xxxx is the start of a 3-byte
       code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz.
       (When UTF-8 is used to code the 31-bit ISO 10646 then this progression con-
       tinues up to 6-byte codes.)

       For most people who use ISO-8859 character sets, this means that the char-
       acters outside of ASCII are now coded with two bytes.  This tends to expand
       ordinary text files by only one or two percent.  For Russian or Greek
       users, this expands ordinary text files by 100%, since text in those lan-
       guages is mostly outside of ASCII.  For Japanese users this means that the
       16-bit codes now in common use will take three bytes.  While there are
       algorithmic conversions from some character sets (especially ISO-8859-1) to
       Unicode, general conversion requires carrying around conversion tables,
       which can be quite large for 16-bit codes.

       Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other byte
       is the head of a code.  Note that the only way ASCII bytes occur in a UTF-8
       stream, is as themselves.  In particular, there are no embedded NULs ('\0')
       or '/'s that form part of some larger code.

       Since ASCII, and, in particular, NUL and '/', are unchanged, the kernel
       does not notice that UTF-8 is being used.  It does not care at all what the
       bytes it is handling stand for.

       Rendering of Unicode data streams is typically handled through "subfont"
       tables which map a subset of Unicode to glyphs.  Internally the kernel uses
       Unicode to describe the subfont loaded in video RAM.  This means that in
       UTF-8 mode one can use a character set with 512 different symbols.  This is
       not enough for Japanese, Chinese and Korean, but it is enough for most
       other purposes.

       At the current time, the console driver does not handle combining charac-
       ters.  So Thai, Sioux and any other script needing combining characters
       can't be handled on the console.

ISO 2022 and ISO 4873

       The ISO 2022 and 4873 standards describe a font-control model based on
       VT100 practice.  This model is (partially) supported by the Linux kernel
       and by xterm(1).  It is popular in Japan and Korea.

       There are 4 graphic character sets, called G0, G1, G2 and G3, and one of
       them is the current character set for codes with high bit zero (initially
       G0), and one of them is the current character set for codes with high bit
       one (initially G1).  Each graphic character set has 94 or 96 characters,
       and is essentially a 7-bit character set.  It uses codes either 040-0177
       (041-0176) or 0240-0377 (0241-0376).  G0 always has size 94 and uses codes
       041-0176.

       Switching between character sets is done using the shift functions ^N (SO
       or LS1), ^O (SI or LS0), ESC n (LS2), ESC o (LS3), ESC N (SS2), ESC O
       (SS3), ESC ~ (LS1R), ESC } (LS2R), ESC | (LS3R).  The function LSn makes
       character set Gn the current one for codes with high bit zero.  The func-
       tion LSnR makes character set Gn the current one for codes with high bit
       one.  The function SSn makes character set Gn (n=2 or 3) the current one
       for the next character only (regardless of the value of its high order
       bit).

       A 94-character set is designated as Gn character set by an escape sequence
       ESC ( xx (for G0), ESC ) xx (for G1), ESC * xx (for G2), ESC + xx (for G3),
       where xx is a symbol or a pair of symbols found in the ISO 2375 Interna-
       tional Register of Coded Character Sets.  For example, ESC ( @ selects the
       ISO 646 character set as G0, ESC ( A selects the UK standard character set
       (with pound instead of number sign), ESC ( B selects ASCII (with dollar
       instead of currency sign), ESC ( M selects a character set for African lan-
       guages, ESC ( ! A selects the Cuban character set, and so on.

       A 96-character set is designated as Gn character set by an escape sequence
       ESC - xx (for G1), ESC . xx (for G2) or ESC / xx (for G3).  For example,
       ESC - G selects the Hebrew alphabet as G1.

       A multibyte character set is designated as Gn character set by an escape
       sequence ESC $ xx or ESC $ ( xx (for G0), ESC $ ) xx (for G1), ESC $ * xx
       (for G2), ESC $ + xx (for G3).  For example, ESC $ ( C selects the Korean
       character set for G0.  The Japanese character set selected by ESC $ B has a
       more recent version selected by ESC & @ ESC $ B.

       ISO 4873 stipulates a narrower use of character sets, where G0 is fixed
       (always ASCII), so that G1, G2 and G3 can only be invoked for codes with
       the high order bit set.  In particular, ^N and ^O are not used anymore, ESC
       ( xx can be used only with xx=B, and ESC ) xx, ESC * xx, ESC + xx are
       equivalent to ESC - xx, ESC . xx, ESC / xx, respectively.

SEE ALSO top

       console(4), console_codes(4), console_ioctl(4), ascii(7), iso_8859-1(7),
       unicode(7), utf-8(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                         CHARSETS(7)


chdir(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CHDIR(2)                     Linux Programmer's Manual                    CHDIR(2)

NAME top

       chdir, fchdir - change working directory

SYNOPSIS top

       #include <unistd.h>

       int chdir(const char *path);
       int fchdir(int fd);

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

       fchdir():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       chdir() changes the current working directory of the calling process to the
       directory specified in path.

       fchdir() is identical to chdir(); the only difference is that the directory
       is given as an open file descriptor.

RETURN VALUE top

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

ERRORS top

       Depending on the file system, other errors can be returned.  The more
       general errors for chdir() are listed below:

       EACCES Search permission is denied for one of the components of path.  (See
              also path_resolution(7).)

       EFAULT path points outside your accessible address space.

       EIO    An I/O error occurred.

       ELOOP  Too many symbolic links were encountered in resolving path.

       ENAMETOOLONG
              path is too long.

       ENOENT The file does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of path is not a directory.

       The general errors for fchdir() are listed below:

       EACCES Search permission was denied on the directory open on fd.

       EBADF  fd is not a valid file descriptor.

CONFORMING TO top

       SVr4, 4.4BSD, POSIX.1-2001.

NOTES top

       The current working directory is the starting point for interpreting
       relative pathnames (those not starting with '/').

       A child process created via fork(2) inherits its parent's current working
       directory.  The current working directory is left unchanged by execve(2).

SEE ALSO top

       chroot(2), getcwd(3), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-25                            CHDIR(2)


chmod(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CHMOD(2)                     Linux Programmer's Manual                    CHMOD(2)

NAME top

       chmod, fchmod - change permissions of a file

SYNOPSIS top

       #include <sys/stat.h>

       int chmod(const char *path, mode_t mode);
       int fchmod(int fd, mode_t mode);

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

       fchmod():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       These system calls change the permissions of a file.  They differ only in
       how the file is specified:

       * chmod() changes the permissions of the file specified whose pathname is
         given in path, which is dereferenced if it is a symbolic link.

       * fchmod() changes the permissions of the file referred to by the open file
         descriptor fd.

       The new file permissions are specified in mode, which is a bit mask created
       by ORing together zero or more of the following:

       S_ISUID  (04000)  set-user-ID (set process effective user ID on execve(2))

       S_ISGID  (02000)  set-group-ID (set process effective group ID on
                         execve(2); mandatory locking, as described in fcntl(2);
                         take a new file's group from parent directory, as
                         described in chown(2) and mkdir(2))

       S_ISVTX  (01000)  sticky bit (restricted deletion flag, as described in
                         unlink(2))

       S_IRUSR  (00400)  read by owner

       S_IWUSR  (00200)  write by owner

       S_IXUSR  (00100)  execute/search by owner ("search" applies for
                         directories, and means that entries within the directory
                         can be accessed)

       S_IRGRP  (00040)  read by group

       S_IWGRP  (00020)  write by group

       S_IXGRP  (00010)  execute/search by group

       S_IROTH  (00004)  read by others

       S_IWOTH  (00002)  write by others

       S_IXOTH  (00001)  execute/search by others

       The effective UID of the calling process must match the owner of the file,
       or the process must be privileged (Linux: it must have the CAP_FOWNER
       capability).

       If the calling process is not privileged (Linux: does not have the
       CAP_FSETID capability), and the group of the file does not match the
       effective group ID of the process or one of its supplementary group IDs,
       the S_ISGID bit will be turned off, but this will not cause an error to be
       returned.

       As a security measure, depending on the file system, the set-user-ID and
       set-group-ID execution bits may be turned off if a file is written.  (On
       Linux this occurs if the writing process does not have the CAP_FSETID
       capability.)  On some file systems, only the superuser can set the sticky
       bit, which may have a special meaning.  For the sticky bit, and for set-
       user-ID and set-group-ID bits on directories, see stat(2).

       On NFS file systems, restricting the permissions will immediately influence
       already open files, because the access control is done on the server, but
       open files are maintained by the client.  Widening the permissions may be
       delayed for other clients if attribute caching is enabled on them.

RETURN VALUE top

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

ERRORS top

       Depending on the file system, other errors can be returned.  The more
       general errors for chmod() are listed below:

       EACCES Search permission is denied on a component of the path prefix.  (See
              also path_resolution(7).)

       EFAULT path points outside your accessible address space.

       EIO    An I/O error occurred.

       ELOOP  Too many symbolic links were encountered in resolving path.

       ENAMETOOLONG
              path is too long.

       ENOENT The file does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of the path prefix is not a directory.

       EPERM  The effective UID does not match the owner of the file, and the
              process is not privileged (Linux: it does not have the CAP_FOWNER
              capability).

       EROFS  The named file resides on a read-only file system.

       The general errors for fchmod() are listed below:

       EBADF  The file descriptor fd is not valid.

       EIO    See above.

       EPERM  See above.

       EROFS  See above.

CONFORMING TO top

       4.4BSD, SVr4, POSIX.1-2001.

SEE ALSO top

       chown(2), execve(2), fchmodat(2), open(2), stat(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                            CHMOD(2)


chown(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CHOWN(2)                     Linux Programmer's Manual                    CHOWN(2)

NAME top

       chown, fchown, lchown - change ownership of a file

SYNOPSIS top

       #include <unistd.h>

       int chown(const char *path, uid_t owner, gid_t group);
       int fchown(int fd, uid_t owner, gid_t group);
       int lchown(const char *path, uid_t owner, gid_t group);

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

       fchown(), lchown():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       These system calls change the owner and group of a file.  The differ only
       in how the file is specified:

       * chown() changes the ownership of the file specified by path, which is
         dereferenced if it is a symbolic link.

       * fchown() changes the ownership of the file referred to by the open file
         descriptor fd.

       * lchown() is like chown(), but does not dereference symbolic links.

       Only a privileged process (Linux: one with the CAP_CHOWN capability) may
       change the owner of a file.  The owner of a file may change the group of
       the file to any group of which that owner is a member.  A privileged
       process (Linux: with CAP_CHOWN) may change the group arbitrarily.

       If the owner or group is specified as -1, then that ID is not changed.

       When the owner or group of an executable file are changed by an
       unprivileged user the S_ISUID and S_ISGID mode bits are cleared.  POSIX
       does not specify whether this also should happen when root does the
       chown(); the Linux behavior depends on the kernel version.  In case of a
       non-group-executable file (i.e., one for which the S_IXGRP bit is not set)
       the S_ISGID bit indicates mandatory locking, and is not cleared by a
       chown().

RETURN VALUE top

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

ERRORS top

       Depending on the file system, other errors can be returned.  The more
       general errors for chown() are listed below.

       EACCES Search permission is denied on a component of the path prefix.  (See
              also path_resolution(7).)

       EFAULT path points outside your accessible address space.

       ELOOP  Too many symbolic links were encountered in resolving path.

       ENAMETOOLONG
              path is too long.

       ENOENT The file does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of the path prefix is not a directory.

       EPERM  The calling process did not have the required permissions (see
              above) to change owner and/or group.

       EROFS  The named file resides on a read-only file system.

       The general errors for fchown() are listed below:

       EBADF  The descriptor is not valid.

       EIO    A low-level I/O error occurred while modifying the inode.

       ENOENT See above.

       EPERM  See above.

       EROFS  See above.

CONFORMING TO top

       4.4BSD, SVr4, POSIX.1-2001.

       The 4.4BSD version can only be used by the superuser (that is, ordinary
       users cannot give away files).

NOTES top

       The original Linux chown(), fchown(), and lchown() system calls supported
       only 16-bit user and group IDs.  Subsequently, Linux 2.4 added chown32(),
       fchown32(), and lchown32(), supporting 32-bit IDs.  The glibc chown(),
       fchown(), and lchown() wrapper functions transparently deal with the
       variations across kernel versions.

       When a new file is created (by, for example, open(2) or mkdir(2)), its
       owner is made the same as the file system user ID of the creating process.
       The group of the file depends on a range of factors, including the type of
       file system, the options used to mount the file system, and whether or not
       the set-group-ID permission bit is enabled on the parent directory.  If the
       file system supports the -o grpid (or, synonymously -o bsdgroups) and
       -o nogrpid (or, synonymously -o sysvgroups) mount(8) options, then the
       rules are as follows:

       * If the file system is mounted with -o grpid, then the group of a new file
         is made the same as that of the parent directory.

       * If the file system is mounted with -o nogrpid and the set-group-ID bit is
         disabled on the parent directory, then the group of a new file is made
         the same as the process's file system GID.

       * If the file system is mounted with -o nogrpid and the set-group-ID bit is
         enabled on the parent directory, then the group of a new file is made the
         same as that of the parent directory.

       As at Linux 2.6.25, the -o grpid and -o nogrpid mount options are supported
       by ext2, ext3, ext4, and XFS.  File systems that don't support these mount
       options follow the -o nogrpid rules.

       The chown() semantics are deliberately violated on NFS file systems which
       have UID mapping enabled.  Additionally, the semantics of all system calls
       which access the file contents are violated, because chown() may cause
       immediate access revocation on already open files.  Client side caching may
       lead to a delay between the time where ownership have been changed to allow
       access for a user and the time where the file can actually be accessed by
       the user on other clients.

       In versions of Linux prior to 2.1.81 (and distinct from 2.1.46), chown()
       did not follow symbolic links.  Since Linux 2.1.81, chown() does follow
       symbolic links, and there is a new system call lchown() that does not
       follow symbolic links.  Since Linux 2.1.86, this new call (that has the
       same semantics as the old chown()) has got the same syscall number, and
       chown() got the newly introduced number.

EXAMPLE top

       The following program changes the ownership of the file named in its second
       command-line argument to the value specified in its first command-line
       argument.  The new owner can be specified either as a numeric user ID, or
       as a username (which is converted to a user ID by using getpwnam(3) to
       perform a lookup in the system password file).

       #include <pwd.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       int
       main(int argc, char *argv[])
       {
           uid_t uid;
           struct passwd *pwd;
           char *endptr;

           if (argc != 3 || argv[1][0] == '\0') {
               fprintf(stderr, "%s <owner> <file>\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           uid = strtol(argv[1], &endptr, 10);  /* Allow a numeric string */

           if (*endptr != '\0') {         /* Was not pure numeric string */
               pwd = getpwnam(argv[1]);   /* Try getting UID for username */
               if (pwd == NULL) {
                   perror("getpwnam");
                   exit(EXIT_FAILURE);
               }

               uid = pwd->pw_uid;
           }

           if (chown(argv[2], uid, -1) == -1) {
               perror("chown");
               exit(EXIT_FAILURE);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       chmod(2), fchownat(2), flock(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                            CHOWN(2)


chroot(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CHROOT(2)                    Linux Programmer's Manual                   CHROOT(2)

NAME top

       chroot - change root directory

SYNOPSIS top

       #include <unistd.h>

       int chroot(const char *path);

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

       chroot():
           Since glibc 2.2.2:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.2.2: none

DESCRIPTION top

       chroot() changes the root directory of the calling process to that
       specified in path.  This directory will be used for pathnames beginning
       with /.  The root directory is inherited by all children of the calling
       process.

       Only a privileged process (Linux: one with the CAP_SYS_CHROOT capability)
       may call chroot().

       This call changes an ingredient in the pathname resolution process and does
       nothing else.

       This call does not change the current working directory, so that after the
       call '.' can be outside the tree rooted at '/'.  In particular, the
       superuser can escape from a "chroot jail" by doing:

           mkdir foo; chroot foo; cd ..

       This call does not close open file descriptors, and such file descriptors
       may allow access to files outside the chroot tree.

RETURN VALUE top

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

ERRORS top

       Depending on the file system, other errors can be returned.  The more
       general errors are listed below:

       EACCES Search permission is denied on a component of the path prefix.  (See
              also path_resolution(7).)

       EFAULT path points outside your accessible address space.

       EIO    An I/O error occurred.

       ELOOP  Too many symbolic links were encountered in resolving path.

       ENAMETOOLONG
              path is too long.

       ENOENT The file does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of path is not a directory.

       EPERM  The caller has insufficient privilege.

CONFORMING TO top

       SVr4, 4.4BSD, SUSv2 (marked LEGACY).  This function is not part of
       POSIX.1-2001.

NOTES top

       A child process created via fork(2) inherits its parent's root directory.
       The root directory is left unchanged by execve(2).

       FreeBSD has a stronger jail() system call.

SEE ALSO top

       chdir(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                           CHROOT(2)


cimag(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CIMAG(3)                     Linux Programmer's Manual                    CIMAG(3)

NAME top

       cimag, cimagf, cimagl - get imaginary part of a complex number

SYNOPSIS top

       #include <complex.h>

       double cimag(double complex z);
       float cimagf(float complex z);
       long double cimagl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The cimag() function returns the imaginary part of the complex number z.

       One has:

           z = creal(z) + I * cimag(z)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

NOTES top

       gcc also supports __imag__.  That is a GNU extension.

SEE ALSO top

       cabs(3), creal(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CIMAG(3)


queue(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | COLOPHON The Linux Programming Interface

QUEUE(3)                     Linux Programmer's Manual                    QUEUE(3)

NAME top

       LIST_ENTRY,   LIST_HEAD,  LIST_INIT,  LIST_INSERT_AFTER,  LIST_INSERT_HEAD,
       LIST_REMOVE,  TAILQ_ENTRY,  TAILQ_HEAD,   TAILQ_INIT,   TAILQ_INSERT_AFTER,
       TAILQ_INSERT_HEAD,  TAILQ_INSERT_TAIL,  TAILQ_REMOVE,  CIRCLEQ_ENTRY,  CIR-
       CLEQ_HEAD, CIRCLEQ_INIT, CIRCLEQ_INSERT_AFTER, CIRCLEQ_INSERT_BEFORE,  CIR-
       CLEQ_INSERT_HEAD,  CIRCLEQ_INSERT_TAIL, CIRCLEQ_REMOVE - implementations of
       lists, tail queues, and circular queues

SYNOPSIS top

       #include <sys/queue.h>

       LIST_ENTRY(TYPE);
       LIST_HEAD(HEADNAME, TYPE);
       LIST_INIT(LIST_HEAD *head);
       LIST_INSERT_AFTER(LIST_ENTRY *listelm,
                       TYPE *elm, LIST_ENTRY NAME);
       LIST_INSERT_HEAD(LIST_HEAD *head,
                       TYPE *elm, LIST_ENTRY NAME);
       LIST_REMOVE(TYPE *elm, LIST_ENTRY NAME);

       TAILQ_ENTRY(TYPE);
       TAILQ_HEAD(HEADNAME, TYPE);
       TAILQ_INIT(TAILQ_HEAD *head);
       TAILQ_INSERT_AFTER(TAILQ_HEAD *head, TYPE *listelm,
                       TYPE *elm, TAILQ_ENTRY NAME);
       TAILQ_INSERT_HEAD(TAILQ_HEAD *head,
                       TYPE *elm, TAILQ_ENTRY NAME);
       TAILQ_INSERT_TAIL(TAILQ_HEAD *head,
                       TYPE *elm, TAILQ_ENTRY NAME);
       TAILQ_REMOVE(TAILQ_HEAD *head, TYPE *elm, TAILQ_ENTRY NAME);

       CIRCLEQ_ENTRY(TYPE);
       CIRCLEQ_HEAD(HEADNAME, TYPE);
       CIRCLEQ_INIT(CIRCLEQ_HEAD *head);
       CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *head, TYPE *listelm,
                       TYPE *elm, CIRCLEQ_ENTRY NAME);
       CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *head, TYPE *listelm,
                       TYPE *elm, CIRCLEQ_ENTRY NAME);
       CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *head,
                       TYPE *elm, CIRCLEQ_ENTRY NAME);
       CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *head,
                       TYPE *elm, CIRCLEQ_ENTRY NAME);
       CIRCLEQ_REMOVE(CIRCLEQ_HEAD *head,
                       TYPE *elm, CIRCLEQ_ENTRY NAME);

DESCRIPTION top

       These macros define and operate on three types of data structures: lists,
       tail queues, and circular queues.  All three structures support the
       following functionality:

           *   Insertion of a new entry at the head of the list.
           *   Insertion of a new entry after any element in the list.
           *   Removal of any entry in the list.
           *   Forward traversal through the list.

       Lists are the simplest of the three data structures and support only the
       above functionality.

       Tail queues add the following functionality:

           *   Entries can be added at the end of a list.

       However:

           1.  All list insertions and removals must specify the head of the list.
           2.  Each head entry requires two pointers rather than one.
           3.  Code size is about 15% greater and operations run about 20% slower
               than lists.

       Circular queues add the following functionality:

           *   Entries can be added at the end of a list.
           *   Entries can be added before another entry.
           *   They may be traversed backward, from tail to head.

       However:

           1.  All list insertions and removals must specify the head of the list.
           2.  Each head entry requires two pointers rather than one.
           3.  The termination condition for traversal is more complex.
           4.  Code size is about 40% greater and operations run about 45% slower
               than lists.

       In the macro definitions, TYPE is the name of a user-defined structure,
       that must contain a field of type LIST_ENTRY, TAILQ_ENTRY, or
       CIRCLEQ_ENTRY, named NAME.  The argument HEADNAME is the name of a user-
       defined structure that must be declared using the macros LIST_HEAD,
       TAILQ_HEAD, or CIRCLEQ_HEAD.  See the examples below for further
       explanation of how these macros are used.

Lists

       A list is headed by a structure defined by the LIST_HEAD macro.  This
       structure contains a single pointer to the first element on the list.  The
       elements are doubly linked so that an arbitrary element can be removed
       without traversing the list.  New elements can be added to the list after
       an existing element or at the head of the list.  A LIST_HEAD structure is
       declared as follows:

           LIST_HEAD(HEADNAME, TYPE) head;

       where HEADNAME is the name of the structure to be defined, and TYPE is the
       type of the elements to be linked into the list.  A pointer to the head of
       the list can later be declared as:

           struct HEADNAME *headp;

       (The names head and headp are user selectable.)

       The macro LIST_ENTRY declares a structure that connects the elements in the
       list.

       The macro LIST_INIT initializes the list referenced by head.

       The macro LIST_INSERT_HEAD inserts the new element elm at the head of the
       list.

       The macro LIST_INSERT_AFTER inserts the new element elm after the element
       listelm.

       The macro LIST_REMOVE removes the element elm from the list.

List Example

       LIST_HEAD(listhead, entry) head;
       struct listhead *headp;                 /* List head. */
       struct entry {
           ...
           LIST_ENTRY(entry) entries;          /* List. */
           ...
       } *n1, *n2, *np;

       LIST_INIT(&head);                       /* Initialize the list. */

       n1 = malloc(sizeof(struct entry));      /* Insert at the head. */
       LIST_INSERT_HEAD(&head, n1, entries);

       n2 = malloc(sizeof(struct entry));      /* Insert after. */
       LIST_INSERT_AFTER(n1, n2, entries);
                                               /* Forward traversal. */
       for (np = head.lh_first; np != NULL; np = np->entries.le_next)
           np-> ...

       while (head.lh_first != NULL)           /* Delete. */
           LIST_REMOVE(head.lh_first, entries);

Tail Queues

       A tail queue is headed by a structure defined by the TAILQ_HEAD macro.
       This structure contains a pair of pointers, one to the first element in the
       tail queue and the other to the last element in the tail queue.  The
       elements are doubly linked so that an arbitrary element can be removed
       without traversing the tail queue.  New elements can be added to the tail
       queue after an existing element, at the head of the tail queue, or at the
       end of the tail queue.  A TAILQ_HEAD structure is declared as follows:

           TAILQ_HEAD(HEADNAME, TYPE) head;

       where HEADNAME is the name of the structure to be defined, and TYPE is the
       type of the elements to be linked into the tail queue.  A pointer to the
       head of the tail queue can later be declared as:

           struct HEADNAME *headp;

       (The names head and headp are user selectable.)

       The macro TAILQ_ENTRY declares a structure that connects the elements in
       the tail queue.

       The macro TAILQ_INIT initializes the tail queue referenced by head.

       The macro TAILQ_INSERT_HEAD inserts the new element elm at the head of the
       tail queue.

       The macro TAILQ_INSERT_TAIL inserts the new element elm at the end of the
       tail queue.

       The macro TAILQ_INSERT_AFTER inserts the new element elm after the element
       listelm.

       The macro TAILQ_REMOVE removes the element elm from the tail queue.

Tail Queue Example

       TAILQ_HEAD(tailhead, entry) head;
       struct tailhead *headp;                 /* Tail queue head. */
       struct entry {
           ...
           TAILQ_ENTRY(entry) entries;         /* Tail queue. */
           ...
       } *n1, *n2, *np;

       TAILQ_INIT(&head);                      /* Initialize the queue. */

       n1 = malloc(sizeof(struct entry));      /* Insert at the head. */
       TAILQ_INSERT_HEAD(&head, n1, entries);

       n1 = malloc(sizeof(struct entry));      /* Insert at the tail. */
       TAILQ_INSERT_TAIL(&head, n1, entries);

       n2 = malloc(sizeof(struct entry));      /* Insert after. */
       TAILQ_INSERT_AFTER(&head, n1, n2, entries);
                                               /* Forward traversal. */
       for (np = head.tqh_first; np != NULL; np = np->entries.tqe_next)
           np-> ...
                                               /* Delete. */
       while (head.tqh_first != NULL)
           TAILQ_REMOVE(&head, head.tqh_first, entries);

Circular Queues

       A circular queue is headed by a structure defined by the CIRCLEQ_HEAD
       macro.  This structure contains a pair of pointers, one to the first
       element in the circular queue and the other to the last element in the
       circular queue.  The elements are doubly linked so that an arbitrary
       element can be removed without traversing the queue.  New elements can be
       added to the queue after an existing element, before an existing element,
       at the head of the queue, or at the end of the queue.  A CIRCLEQ_HEAD
       structure is declared as follows:

           CIRCLEQ_HEAD(HEADNAME, TYPE) head;

       where HEADNAME is the name of the structure to be defined, and TYPE is the
       type of the elements to be linked into the circular queue.  A pointer to
       the head of the circular queue can later be declared as:

           struct HEADNAME *headp;

       (The names head and headp are user selectable.)

       The macro CIRCLEQ_ENTRY declares a structure that connects the elements in
       the circular queue.

       The macro CIRCLEQ_INIT initializes the circular queue referenced by head.

       The macro CIRCLEQ_INSERT_HEAD inserts the new element elm at the head of
       the circular queue.

       The macro CIRCLEQ_INSERT_TAIL inserts the new element elm at the end of the
       circular queue.

       The macro CIRCLEQ_INSERT_AFTER inserts the new element elm after the
       element listelm.

       The macro CIRCLEQ_INSERT_BEFORE inserts the new element elm before the
       element listelm.

       The macro CIRCLEQ_REMOVE removes the element elm from the circular queue.

Circular Queue Example

       CIRCLEQ_HEAD(circleq, entry) head;
       struct circleq *headp;              /* Circular queue head. */
       struct entry {
           ...
           CIRCLEQ_ENTRY(entry) entries;   /* Circular queue. */
           ...
       } *n1, *n2, *np;

       CIRCLEQ_INIT(&head);                /* Initialize the circular queue. */

       n1 = malloc(sizeof(struct entry));  /* Insert at the head. */
       CIRCLEQ_INSERT_HEAD(&head, n1, entries);

       n1 = malloc(sizeof(struct entry));  /* Insert at the tail. */
       CIRCLEQ_INSERT_TAIL(&head, n1, entries);

       n2 = malloc(sizeof(struct entry));  /* Insert after. */
       CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries);

       n2 = malloc(sizeof(struct entry));  /* Insert before. */
       CIRCLEQ_INSERT_BEFORE(&head, n1, n2, entries);
                                           /* Forward traversal. */
       for (np = head.cqh_first; np != (void *)&head;
               np = np->entries.cqe_next)
           np-> ...
                                           /* Reverse traversal. */
       for (np = head.cqh_last; np != (void *)&head; np = np->entries.cqe_prev)
           np-> ...
                                           /* Delete. */
       while (head.cqh_first != (void *)&head)
           CIRCLEQ_REMOVE(&head, head.cqh_first, entries);

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs.  The queue functions first
       appeared in 4.4BSD.

COLOPHON top

       This page is part of release 3.45 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-12-28                            QUEUE(3)


clearenv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CLEARENV(3)                  Linux Programmer's Manual                 CLEARENV(3)

NAME top

       clearenv - clear the environment

SYNOPSIS top

       #include <stdlib.h>

       int clearenv(void);

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

       clearenv(): _SVID_SOURCE || _BSD_SOURCE

DESCRIPTION top

       The clearenv() function clears the environment of all name-value pairs and
       sets the value of the external variable environ to NULL.

RETURN VALUE top

       The clearenv() function returns zero on success, and a nonzero value on
       failure.

VERSIONS top

       Not in libc4, libc5.  In glibc since glibc 2.0.

CONFORMING TO top

       Various UNIX variants (DG/UX, HP-UX, QNX, ...).  POSIX.9 (bindings for
       FORTRAN77).  POSIX.1-1996 did not accept clearenv() and putenv(3), but
       changed its mind and scheduled these functions for some later issue of this
       standard (cf. B.4.6.1).  However, POSIX.1-2001 only adds putenv(3), and
       rejected clearenv().

NOTES top

       Used in security-conscious applications.  If it is unavailable the
       assignment

           environ = NULL;

       will probably do.

       The DG/UX and Tru64 man pages write: If environ has been modified by
       anything other than the putenv(3), getenv(3), or clearenv() functions, then
       clearenv() will return an error and the process environment will remain
       unchanged.

SEE ALSO top

       getenv(3), putenv(3), setenv(3), unsetenv(3), environ(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-04                         CLEARENV(3)


ferror(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FERROR(3)                    Linux Programmer's Manual                   FERROR(3)

NAME top

       clearerr, feof, ferror, fileno - check and reset stream status

SYNOPSIS top

       #include <stdio.h>

       void clearerr(FILE *stream);

       int feof(FILE *stream);

       int ferror(FILE *stream);

       int fileno(FILE *stream);

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

       fileno(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The function clearerr() clears the end-of-file and error indicators for the
       stream pointed to by stream.

       The function feof() tests the end-of-file indicator for the stream pointed
       to by stream, returning nonzero if it is set.  The end-of-file indicator
       can only be cleared by the function clearerr().

       The function ferror() tests the error indicator for the stream pointed to
       by stream, returning nonzero if it is set.  The error indicator can only be
       reset by the clearerr() function.

       The function fileno() examines the argument stream and returns its integer
       descriptor.

       For nonlocking counterparts, see unlocked_stdio(3).

ERRORS top

       These functions should not fail and do not set the external variable errno.
       (However, in case fileno() detects that its argument is not a valid stream,
       it must return -1 and set errno to EBADF.)

CONFORMING TO top

       The functions clearerr(), feof(), and ferror() conform to C89 and C99.

SEE ALSO top

       open(2), fdopen(3), stdio(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-29                           FERROR(3)


unlocked_stdio(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

UNLOCKED_STDIO(3)            Linux Programmer's Manual           UNLOCKED_STDIO(3)

NAME top

       getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked - nonlock-
       ing stdio functions

SYNOPSIS top

       #include <stdio.h>

       int getc_unlocked(FILE *stream);
       int getchar_unlocked(void);
       int putc_unlocked(int c, FILE *stream);
       int putchar_unlocked(int c);

       void clearerr_unlocked(FILE *stream);
       int feof_unlocked(FILE *stream);
       int ferror_unlocked(FILE *stream);
       int fileno_unlocked(FILE *stream);
       int fflush_unlocked(FILE *stream);
       int fgetc_unlocked(FILE *stream);
       int fputc_unlocked(int c, FILE *stream);
       size_t fread_unlocked(void *ptr, size_t size, size_t n,
                             FILE *stream);
       size_t fwrite_unlocked(const void *ptr, size_t size, size_t n,
                             FILE *stream);

       char *fgets_unlocked(char *s, int n, FILE *stream);
       int fputs_unlocked(const char *s, FILE *stream);

       #include <wchar.h>

       wint_t getwc_unlocked(FILE *stream);
       wint_t getwchar_unlocked(void);
       wint_t fgetwc_unlocked(FILE *stream);
       wint_t fputwc_unlocked(wchar_t wc, FILE *stream);
       wint_t putwc_unlocked(wchar_t wc, FILE *stream);
       wint_t putwchar_unlocked(wchar_t wc);
       wchar_t *fgetws_unlocked(wchar_t *ws, int n, FILE *stream);
       int fputws_unlocked(const wchar_t *ws, FILE *stream);

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

       getc_unlocked(), getchar_unlocked(), putc_unlocked(), putchar_unlocked():
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE || _BSD_SOURCE
           || _SVID_SOURCE

       clearerr_unlocked(), feof_unlocked(), ferror_unlocked(), fileno_unlocked(),
       fflush_unlocked(), fgetc_unlocked(), fputc_unlocked(), fread_unlocked(),
       fwrite_unlocked():
           _BSD_SOURCE || _SVID_SOURCE

       fgets_unlocked(), fputs_unlocked(), getwc_unlocked(), getwchar_unlocked(),
       fgetwc_unlocked(), fputwc_unlocked(), putwchar_unlocked(),
       fgetws_unlocked(), fputws_unlocked():
           _GNU_SOURCE

DESCRIPTION top

       Each of these functions has the same behavior as its counterpart without
       the "_unlocked" suffix, except that they do not use locking (they do not
       set locks themselves, and do not test for the presence of locks set by
       others) and hence are thread-unsafe.  See flockfile(3).

CONFORMING TO top

       The four functions getc_unlocked(), getchar_unlocked(), putc_unlocked(),
       putchar_unlocked() are in POSIX.1-2001.

       The nonstandard *_unlocked() variants occur on a few UNIX systems, and are
       available in recent glibc.  They should probably not be used.

SEE ALSO top

       flockfile(3), stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-29                   UNLOCKED_STDIO(3)


clock(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CLOCK(3)                     Linux Programmer's Manual                    CLOCK(3)

NAME top

       clock - determine processor time

SYNOPSIS top

       #include <time.h>

       clock_t clock(void);

DESCRIPTION top

       The clock() function returns an approximation of processor time used by the
       program.

RETURN VALUE top

       The value returned is the CPU time used so far as a clock_t; to get the
       number of seconds used, divide by CLOCKS_PER_SEC.  If the processor time
       used is not available or its value cannot be represented, the function
       returns the value (clock_t) -1.

CONFORMING TO top

       C89, C99, POSIX.1-2001.  POSIX requires that CLOCKS_PER_SEC equals 1000000
       independent of the actual resolution.

NOTES top

       The C standard allows for arbitrary values at the start of the program;
       subtract the value returned from a call to clock() at the start of the
       program to get maximum portability.

       Note that the time can wrap around.  On a 32-bit system where
       CLOCKS_PER_SEC equals 1000000 this function will return the same value
       approximately every 72 minutes.

       On several other implementations, the value returned by clock() also
       includes the times of any children whose status has been collected via
       wait(2) (or another wait-type call).  Linux does not include the times of
       waited-for children in the value returned by clock().  The times(2)
       function, which explicitly returns (separate) information about the caller
       and its children, may be preferable.

SEE ALSO top

       clock_gettime(2), getrusage(2), times(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-28                            CLOCK(3)


clock_getcpuclockid(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CLOCK_GETCPUCLOCKID(3)       Linux Programmer's Manual      CLOCK_GETCPUCLOCKID(3)

NAME top

       clock_getcpuclockid - obtain ID of a process CPU-time clock

SYNOPSIS top

       #include <time.h>

       int clock_getcpuclockid(pid_t pid, clockid_t *clock_id);

       Link with -lrt (only for glibc versions before 2.17).

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

       clock_getcpuclockid():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       The clock_getcpuclockid() function obtains the ID of the CPU-time clock of
       the process whose ID is pid, and returns it in the location pointed to by
       clock_id.  If pid is zero, then the clock ID of the CPU-time clock of the
       calling process is returned.

RETURN VALUE top

       On success, clock_getcpuclockid() returns 0; on error, it returns one of
       the positive error numbers listed in ERRORS.

ERRORS top

       ENOSYS The kernel does not support obtaining the per-process CPU-time clock
              of another process, and pid does not specify the calling process.

       EPERM  The caller does not have permission to access the CPU-time clock of
              the process specified by pid.  (Specified as an optional error in
              POSIX.1-2001; does not occur on Linux unless the kernel does not
              support obtaining the per-process CPU-time clock of another
              process.)

       ESRCH  There is no process with the ID pid.

VERSIONS top

       The clock_getcpuclockid() function is available in glibc since version 2.2.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Calling clock_gettime(2) with the clock ID obtained by a call to
       clock_getcpuclockid() with a pid of 0, is the same as using the clock ID
       CLOCK_PROCESS_CPUTIME_ID.

EXAMPLE top

       The example program below obtains the CPU-time clock ID of the process
       whose ID is given on the command line, and then uses clock_gettime(2) to
       obtain the time on that clock.  An example run is the following:

           $ ./a.out 1                 # Show CPU clock of init process
           CPU-time clock for PID 1 is 2.213466748 seconds

Program source

       #define _XOPEN_SOURCE 600
       #include <stdio.h>
       #include <unistd.h>
       #include <stdlib.h>
       #include <time.h>

       int
       main(int argc, char *argv[])
       {
           clockid_t clockid;
           struct timespec ts;

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

           if (clock_getcpuclockid(atoi(argv[1]), &clockid) != 0) {
            perror("clock_getcpuclockid");
            exit(EXIT_FAILURE);
           }

           if (clock_gettime(clockid, &ts) == -1) {
            perror("clock_gettime");
            exit(EXIT_FAILURE);
           }

           printf("CPU-time clock for PID %s is %ld.%09ld seconds\n",
                argv[1], (long) ts.tv_sec, (long) ts.tv_nsec);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       clock_getres(2), timer_create(2), pthread_getcpuclockid(3), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-29              CLOCK_GETCPUCLOCKID(3)


clock_getres(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | AVAILABILITY | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

CLOCK_GETRES(2)              Linux Programmer's Manual             CLOCK_GETRES(2)

NAME top

       clock_getres, clock_gettime, clock_settime - clock and time functions

SYNOPSIS top

       #include <time.h>

       int clock_getres(clockid_t clk_id, struct timespec *res);

       int clock_gettime(clockid_t clk_id, struct timespec *tp);

       int clock_settime(clockid_t clk_id, const struct timespec *tp);

       Link with -lrt (only for glibc versions before 2.17).

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

       clock_getres(), clock_gettime(), clock_settime():
              _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       The function clock_getres() finds the resolution (precision) of the
       specified clock clk_id, and, if res is non-NULL, stores it in the struct
       timespec pointed to by res.  The resolution of clocks depends on the
       implementation and cannot be configured by a particular process.  If the
       time value pointed to by the argument tp of clock_settime() is not a
       multiple of res, then it is truncated to a multiple of res.

       The functions clock_gettime() and clock_settime() retrieve and set the time
       of the specified clock clk_id.

       The res and tp arguments are timespec structures, as specified in <time.h>:

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

       The clk_id argument is the identifier of the particular clock on which to
       act.  A clock may be system-wide and hence visible for all processes, or
       per-process if it measures time only within a single process.

       All implementations support the system-wide real-time clock, which is
       identified by CLOCK_REALTIME.  Its time represents seconds and nanoseconds
       since the Epoch.  When its time is changed, timers for a relative interval
       are unaffected, but timers for an absolute point in time are affected.

       More clocks may be implemented.  The interpretation of the corresponding
       time values and the effect on timers is unspecified.

       Sufficiently recent versions of glibc and the Linux kernel support the
       following clocks:

       CLOCK_REALTIME
              System-wide clock that measures real (i.e., wall-clock) time.
              Setting this clock requires appropriate privileges.  This clock is
              affected by discontinuous jumps in the system time (e.g., if the
              system administrator manually changes the clock), and by the
              incremental adjustments performed by adjtime(3) and NTP.

       CLOCK_MONOTONIC
              Clock that cannot be set and represents monotonic time since some
              unspecified starting point.  This clock is not affected by
              discontinuous jumps in the system time (e.g., if the system
              administrator manually changes the clock), but is affected by the
              incremental adjustments performed by adjtime(3) and NTP.

       CLOCK_MONOTONIC_RAW (since Linux 2.6.28; Linux-specific)
              Similar to CLOCK_MONOTONIC, but provides access to a raw hardware-
              based time that is not subject to NTP adjustments or the incremental
              adjustments performed by adjtime(3).

       CLOCK_PROCESS_CPUTIME_ID
              High-resolution per-process timer from the CPU.

       CLOCK_THREAD_CPUTIME_ID
              Thread-specific CPU-time clock.

RETURN VALUE top

       clock_gettime(), clock_settime() and clock_getres() return 0 for success,
       or -1 for failure (in which case errno is set appropriately).

ERRORS top

       EFAULT tp points outside the accessible address space.

       EINVAL The clk_id specified is not supported on this system.

       EPERM  clock_settime() does not have permission to set the clock indicated.

CONFORMING TO top

       SUSv2, POSIX.1-2001.

AVAILABILITY top

       On POSIX systems on which these functions are available, the symbol
       _POSIX_TIMERS is defined in <unistd.h> to a value greater than 0.  The
       symbols _POSIX_MONOTONIC_CLOCK, _POSIX_CPUTIME, _POSIX_THREAD_CPUTIME
       indicate that CLOCK_MONOTONIC, CLOCK_PROCESS_CPUTIME_ID,
       CLOCK_THREAD_CPUTIME_ID are available.  (See also sysconf(3).)

NOTES top

Note for SMP systems

       The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks are
       realized on many platforms using timers from the CPUs (TSC on i386, AR.ITC
       on Itanium).  These registers may differ between CPUs and as a consequence
       these clocks may return bogus results if a process is migrated to another
       CPU.

       If the CPUs in an SMP system have different clock sources then there is no
       way to maintain a correlation between the timer registers since each CPU
       will run at a slightly different frequency.  If that is the case then
       clock_getcpuclockid(0) will return ENOENT to signify this condition.  The
       two clocks will then only be useful if it can be ensured that a process
       stays on a certain CPU.

       The processors in an SMP system do not start all at exactly the same time
       and therefore the timer registers are typically running at an offset.  Some
       architectures include code that attempts to limit these offsets on bootup.
       However, the code cannot guarantee to accurately tune the offsets.  Glibc
       contains no provisions to deal with these offsets (unlike the Linux
       Kernel).  Typically these offsets are small and therefore the effects may
       be negligible in most cases.

BUGS          top
       According to POSIX.1-2001, a process with "appropriate privileges" may set
       the CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks using
       clock_settime().  On Linux, these clocks are not settable (i.e., no process
       has "appropriate privileges").

SEE ALSO          top
       date(1), gettimeofday(2), settimeofday(2), time(2), adjtime(3),
       clock_getcpuclockid(3), ctime(3), ftime(3), pthread_getcpuclockid(3),
       sysconf(3), time(7)

COLOPHON          top
       This page is part of release 3.45 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/.

                                    2012-11-07                     CLOCK_GETRES(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


clock_nanosleep(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CLOCK_NANOSLEEP(2)           Linux Programmer's Manual          CLOCK_NANOSLEEP(2)

NAME top

       clock_nanosleep - high-resolution sleep with specifiable clock

SYNOPSIS top

       #include <time.h>

       int clock_nanosleep(clockid_t clock_id, int flags,
                           const struct timespec *request,
                           struct timespec *remain);

       Link with -lrt (only for glibc versions before 2.17).

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

       clock_nanosleep():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       Like nanosleep(2), clock_nanosleep() allows the calling thread to sleep for
       an interval specified with nanosecond precision.  It differs in allowing
       the caller to select the clock against which the sleep interval is to be
       measured, and in allowing the sleep interval to be specified as either an
       absolute or a relative value.

       The time values passed to and returned by this call are specified using
       timespec structures, defined as follows:

           struct timespec {
               time_t tv_sec;        /* seconds */
               long   tv_nsec;       /* nanoseconds [0 .. 999999999] */
           };

       The clock_id argument specifies the clock against which the sleep interval
       is to be measured.  This argument can have one of the following values:

       CLOCK_REALTIME   A settable system-wide real-time clock.

       CLOCK_MONOTONIC  A nonsettable, monotonically increasing clock that
                        measures time since some unspecified point in the past
                        that does not change after system startup.

       CLOCK_PROCESS_CPUTIME_ID
                        A settable per-process clock that measures CPU time
                        consumed by all threads in the process.

       See clock_getres(2) for further details on these clocks.

       If flags is 0, then the value specified in request is interpreted as an
       interval relative to the current value of the clock specified by clock_id.

       If flags is TIMER_ABSTIME, then request is interpreted as an absolute time
       as measured by the clock, clock_id.  If request is less than or equal to
       the current value of the clock, then clock_nanosleep() returns immediately
       without suspending the calling thread.

       clock_nanosleep() suspends the execution of the calling thread until either
       at least the time specified by request has elapsed, or a signal is
       delivered that causes a signal handler to be called or that terminates the
       process.

       If the call is interrupted by a signal handler, clock_nanosleep() fails
       with the error EINTR.  In addition, if remain is not NULL, and flags was
       not TIMER_ABSTIME, it returns the remaining unslept time in remain.  This
       value can then be used to call clock_nanosleep() again and complete a
       (relative) sleep.

RETURN VALUE top

       On successfully sleeping for the requested interval, clock_nanosleep()
       returns 0.  If the call is interrupted by a signal handler or encounters an
       error, then it returns one of the positive error number listed in ERRORS.

ERRORS top

       EFAULT request or remain specified an invalid address.

       EINTR  The sleep was interrupted by a signal handler.

       EINVAL The value in the tv_nsec field was not in the range 0 to 999999999
              or tv_sec was negative.

       EINVAL clock_id was invalid.  (CLOCK_THREAD_CPUTIME_ID is not a permitted
              value for clock_id.)

VERSIONS top

       The clock_nanosleep() system call first appeared in Linux 2.6.  Support is
       available in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       If the interval specified in request is not an exact multiple of the
       granularity underlying clock (see time(7)), then the interval will be
       rounded up to the next multiple.  Furthermore, after the sleep completes,
       there may still be a delay before the CPU becomes free to once again
       execute the calling thread.

       Using an absolute timer is useful for preventing timer drift problems of
       the type described in nanosleep(2).  (Such problems are exacerbated in
       programs that try to restart a relative sleep that is repeatedly
       interrupted by signals.)  To perform a relative sleep that avoids these
       problems, call clock_gettime(2) for the desired clock, add the desired
       interval to the returned time value, and then call clock_nanosleep() with
       the TIMER_ABSTIME flag.

       clock_nanosleep() is never restarted after being interrupted by a signal
       handler, regardless of the use of the sigaction(2) SA_RESTART flag.

       The remain argument is unused, and unnecessary, when flags is
       TIMER_ABSTIME.  (An absolute sleep can be restarted using the same request
       argument.)

       POSIX.1 specifies that clock_nanosleep() has no effect on signals
       dispositions or the signal mask.

       POSIX.1 specifies that after changing the value of the CLOCK_REALTIME clock
       via clock_settime(2), the new clock value shall be used to determine the
       time at which a thread blocked on an absolute clock_nanosleep() will wake
       up; if the new clock value falls past the end of the sleep interval, then
       the clock_nanosleep() call will return immediately.

       POSIX.1 specifies that changing the value of the CLOCK_REALTIME clock via
       clock_settime(2) shall have no effect on a thread that is blocked on a
       relative clock_nanosleep().

SEE ALSO top

       clock_getres(2), nanosleep(2), timer_create(2), sleep(3), usleep(3),
       time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-11-07                  CLOCK_NANOSLEEP(2)


clog(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CLOG(3)                      Linux Programmer's Manual                     CLOG(3)

NAME top

       clog, clogf, clogl - natural logarithm of a complex number

SYNOPSIS top

       #include <complex.h>

       double complex clog(double complex z);
       float complex clogf(float complex z);
       long double complex clogl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The logarithm clog() is the inverse function of the exponential cexp(3).
       Thus, if y = clog(z), then z = cexp(y).  The imaginary part of y is chosen
       in the interval [-pi,pi].

       One has:

           clog(z) = log(cabs(z)) + I * carg(z)

       Note that z close to zero will cause an overflow.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), cexp(3), clog10(3), clog2(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CLOG(3)


clog10(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CLOG10(3)                    Linux Programmer's Manual                   CLOG10(3)

NAME top

       clog10, clog10f, clog10l - base-10 logarithm of a complex number

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <complex.h>

       double complex clog10(double complex z);
       float complex clog10f(float complex z);
       long double complex clog10l(long double complex z);

       Link with -lm.

DESCRIPTION top

       The call clog10(z) is equivalent to clog(z)/log(10).  The other functions
       perform the same task for float and long double.

       Note that z close to zero will cause an overflow.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       This function is a GNU extension.  It is reserved for future use in C99.

SEE ALSO top

       cabs(3), cexp(3), clog(3), clog2(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                           CLOG10(3)


clog2(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | AVAILABILITY | SEE ALSO | COLOPHON The Linux Programming Interface

CLOG2(3)                     Linux Programmer's Manual                    CLOG2(3)

NAME top

       clog2, clog2f, clog2l - base-2 logarithm of a complex number

SYNOPSIS top

       #include <complex.h>

       double complex clog2(double complex z);
       float complex clog2f(float complex z);
       long double complex clog2l(long double complex z);

DESCRIPTION top

       The call clog2(z) is equivalent to clog(z)/log(2).

       The other functions perform the same task for float and long double.

       Note that z close to zero will cause an overflow.

CONFORMING TO top

       These function names are reserved for future use in C99.

AVAILABILITY top

       Not yet in glibc, as at version 2.8.

SEE ALSO top

       cabs(3), cexp(3), clog(3), clog10(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-07                            CLOG2(3)


clone(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

CLONE(2)                     Linux Programmer's Manual                    CLONE(2)

NAME top

       clone, __clone2 - create a child process

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sched.h>

       int clone(int (*fn)(void *), void *child_stack,
                 int flags, void *arg, ...
                 /* pid_t *ptid, struct user_desc *tls, pid_t *ctid */ );

DESCRIPTION top

       clone() creates a new process, in a manner similar to fork(2).  It is
       actually a library function layered on top of the underlying clone() system
       call, hereinafter referred to as sys_clone.  A description of sys_clone is
       given toward the end of this page.

       Unlike fork(2), these calls allow the child process to share parts of its
       execution context with the calling process, such as the memory space, the
       table of file descriptors, and the table of signal handlers.  (Note that on
       this manual page, "calling process" normally corresponds to "parent
       process".  But see the description of CLONE_PARENT below.)

       The main use of clone() is to implement threads: multiple threads of
       control in a program that run concurrently in a shared memory space.

       When the child process is created with clone(), it executes the function
       application fn(arg).  (This differs from fork(2), where execution continues
       in the child from the point of the fork(2) call.)  The fn argument is a
       pointer to a function that is called by the child process at the beginning
       of its execution.  The arg argument is passed to the fn function.

       When the fn(arg) function application returns, the child process
       terminates.  The integer returned by fn is the exit code for the child
       process.  The child process may also terminate explicitly by calling
       exit(2) or after receiving a fatal signal.

       The child_stack argument specifies the location of the stack used by the
       child process.  Since the child and calling process may share memory, it is
       not possible for the child process to execute in the same stack as the
       calling process.  The calling process must therefore set up memory space
       for the child stack and pass a pointer to this space to clone().  Stacks
       grow downward on all processors that run Linux (except the HP PA
       processors), so child_stack usually points to the topmost address of the
       memory space set up for the child stack.

       The low byte of flags contains the number of the termination signal sent to
       the parent when the child dies.  If this signal is specified as anything
       other than SIGCHLD, then the parent process must specify the __WALL or
       __WCLONE options when waiting for the child with wait(2).  If no signal is
       specified, then the parent process is not signaled when the child
       terminates.

       flags may also be bitwise-or'ed with zero or more of the following
       constants, in order to specify what is shared between the calling process
       and the child process:

       CLONE_CHILD_CLEARTID (since Linux 2.5.49)
              Erase child thread ID at location ctid in child memory when the
              child exits, and do a wakeup on the futex at that address.  The
              address involved may be changed by the set_tid_address(2) system
              call.  This is used by threading libraries.

       CLONE_CHILD_SETTID (since Linux 2.5.49)
              Store child thread ID at location ctid in child memory.

       CLONE_FILES
              If CLONE_FILES is set, the calling process and the child process
              share the same file descriptor table.  Any file descriptor created
              by the calling process or by the child process is also valid in the
              other process.  Similarly, if one of the processes closes a file
              descriptor, or changes its associated flags (using the fcntl(2)
              F_SETFD operation), the other process is also affected.

              If CLONE_FILES is not set, the child process inherits a copy of all
              file descriptors opened in the calling process at the time of
              clone().  (The duplicated file descriptors in the child refer to the
              same open file descriptions (see open(2)) as the corresponding file
              descriptors in the calling process.)  Subsequent operations that
              open or close file descriptors, or change file descriptor flags,
              performed by either the calling process or the child process do not
              affect the other process.

       CLONE_FS
              If CLONE_FS is set, the caller and the child process share the same
              file system information.  This includes the root of the file system,
              the current working directory, and the umask.  Any call to
              chroot(2), chdir(2), or umask(2) performed by the calling process or
              the child process also affects the other process.

              If CLONE_FS is not set, the child process works on a copy of the
              file system information of the calling process at the time of the
              clone() call.  Calls to chroot(2), chdir(2), umask(2) performed
              later by one of the processes do not affect the other process.

       CLONE_IO (since Linux 2.6.25)
              If CLONE_IO is set, then the new process shares an I/O context with
              the calling process.  If this flag is not set, then (as with
              fork(2)) the new process has its own I/O context.

              The I/O context is the I/O scope of the disk scheduler (i.e, what
              the I/O scheduler uses to model scheduling of a process's I/O).  If
              processes share the same I/O context, they are treated as one by the
              I/O scheduler.  As a consequence, they get to share disk time.  For
              some I/O schedulers, if two processes share an I/O context, they
              will be allowed to interleave their disk access.  If several threads
              are doing I/O on behalf of the same process (aio_read(3), for
              instance), they should employ CLONE_IO to get better I/O
              performance.

              If the kernel is not configured with the CONFIG_BLOCK option, this
              flag is a no-op.

       CLONE_NEWIPC (since Linux 2.6.19)
              If CLONE_NEWIPC is set, then create the process in a new IPC
              namespace.  If this flag is not set, then (as with fork(2)), the
              process is created in the same IPC namespace as the calling process.
              This flag is intended for the implementation of containers.

              An IPC namespace consists of the set of identifiers for System V IPC
              objects.  (These objects are created using msgctl(2), semctl(2), and
              shmctl(2)).  Objects created in an IPC namespace are visible to all
              other processes that are members of that namespace, but are not
              visible to processes in other IPC namespaces.

              Since Linux 2.6.30, CLONE_NEWIPC also supports POSIX message queues,
              meaning that CLONE_NEWIPC causes a new instance of a POSIX message
              queue file system (see mq_overview(7)) to be created and mounted.

              When an IPC namespace is destroyed (i.e, when the last process that
              is a member of the namespace terminates), all IPC objects in the
              namespace are automatically destroyed.

              Use of this flag requires: a kernel configured with the
              CONFIG_SYSVIPC and CONFIG_IPC_NS options and that the process be
              privileged (CAP_SYS_ADMIN).  This flag can't be specified in
              conjunction with CLONE_SYSVSEM.

       CLONE_NEWNET (since Linux 2.6.24)
              (The implementation of this flag was only completed by about kernel
              version 2.6.29.)

              If CLONE_NEWNET is set, then create the process in a new network
              namespace.  If this flag is not set, then (as with fork(2)), the
              process is created in the same network namespace as the calling
              process.  This flag is intended for the implementation of
              containers.

              A network namespace provides an isolated view of the networking
              stack (network device interfaces, IPv4 and IPv6 protocol stacks, IP
              routing tables, firewall rules, the /proc/net and /sys/class/net
              directory trees, sockets, etc.).  A physical network device can live
              in exactly one network namespace.  A virtual network device ("veth")
              pair provides a pipe-like abstraction that can be used to create
              tunnels between network namespaces, and can be used to create a
              bridge to a physical network device in another namespace.

              When a network namespace is freed (i.e., when the last process in
              the namespace terminates), its physical network devices are moved
              back to the initial network namespace (not to the parent of the
              process).

              Use of this flag requires: a kernel configured with the
              CONFIG_NET_NS option and that the process be privileged
              (CAP_SYS_ADMIN).

       CLONE_NEWNS (since Linux 2.4.19)
              Start the child in a new mount namespace.

              Every process lives in a mount namespace.  The namespace of a
              process is the data (the set of mounts) describing the file
              hierarchy as seen by that process.  After a fork(2) or clone() where
              the CLONE_NEWNS flag is not set, the child lives in the same mount
              namespace as the parent.  The system calls mount(2) and umount(2)
              change the mount namespace of the calling process, and hence affect
              all processes that live in the same namespace, but do not affect
              processes in a different mount namespace.

              After a clone() where the CLONE_NEWNS flag is set, the cloned child
              is started in a new mount namespace, initialized with a copy of the
              namespace of the parent.

              Only a privileged process (one having the CAP_SYS_ADMIN capability)
              may specify the CLONE_NEWNS flag.  It is not permitted to specify
              both CLONE_NEWNS and CLONE_FS in the same clone() call.

       CLONE_NEWPID (since Linux 2.6.24)
              If CLONE_NEWPID is set, then create the process in a new PID
              namespace.  If this flag is not set, then (as with fork(2)), the
              process is created in the same PID namespace as the calling process.
              This flag is intended for the implementation of containers.

              A PID namespace provides an isolated environment for PIDs: PIDs in a
              new namespace start at 1, somewhat like a standalone system, and
              calls to fork(2), vfork(2), or clone() will produce processes with
              PIDs that are unique within the namespace.

              The first process created in a new namespace (i.e., the process
              created using the CLONE_NEWPID flag) has the PID 1, and is the
              "init" process for the namespace.  Children that are orphaned within
              the namespace will be reparented to this process rather than
              init(8).  Unlike the traditional init process, the "init" process of
              a PID namespace can terminate, and if it does, all of the processes
              in the namespace are terminated.

              PID namespaces form a hierarchy.  When a new PID namespace is
              created, the processes in that namespace are visible in the PID
              namespace of the process that created the new namespace;
              analogously, if the parent PID namespace is itself the child of
              another PID namespace, then processes in the child and parent PID
              namespaces will both be visible in the grandparent PID namespace.
              Conversely, the processes in the "child" PID namespace do not see
              the processes in the parent namespace.  The existence of a namespace
              hierarchy means that each process may now have multiple PIDs: one
              for each namespace in which it is visible; each of these PIDs is
              unique within the corresponding namespace.  (A call to getpid(2)
              always returns the PID associated with the namespace in which the
              process lives.)

              After creating the new namespace, it is useful for the child to
              change its root directory and mount a new procfs instance at /proc
              so that tools such as ps(1) work correctly.  (If CLONE_NEWNS is also
              included in flags, then it isn't necessary to change the root
              directory: a new procfs instance can be mounted directly over
              /proc.)

              Use of this flag requires: a kernel configured with the
              CONFIG_PID_NS option and that the process be privileged
              (CAP_SYS_ADMIN).  This flag can't be specified in conjunction with
              CLONE_THREAD.

       CLONE_NEWUTS (since Linux 2.6.19)
              If CLONE_NEWUTS is set, then create the process in a new UTS
              namespace, whose identifiers are initialized by duplicating the
              identifiers from the UTS namespace of the calling process.  If this
              flag is not set, then (as with fork(2)), the process is created in
              the same UTS namespace as the calling process.  This flag is
              intended for the implementation of containers.

              A UTS namespace is the set of identifiers returned by uname(2);
              among these, the domain name and the host name can be modified by
              setdomainname(2) and  sethostname(2), respectively.  Changes made to
              the identifiers in a UTS namespace are visible to all other
              processes in the same namespace, but are not visible to processes in
              other UTS namespaces.

              Use of this flag requires: a kernel configured with the
              CONFIG_UTS_NS option and that the process be privileged
              (CAP_SYS_ADMIN).

       CLONE_PARENT (since Linux 2.3.12)
              If CLONE_PARENT is set, then the parent of the new child (as
              returned by getppid(2)) will be the same as that of the calling
              process.

              If CLONE_PARENT is not set, then (as with fork(2)) the child's
              parent is the calling process.

              Note that it is the parent process, as returned by getppid(2), which
              is signaled when the child terminates, so that if CLONE_PARENT is
              set, then the parent of the calling process, rather than the calling
              process itself, will be signaled.

       CLONE_PARENT_SETTID (since Linux 2.5.49)
              Store child thread ID at location ptid in parent and child memory.
              (In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did
              this.)

       CLONE_PID (obsolete)
              If CLONE_PID is set, the child process is created with the same
              process ID as the calling process.  This is good for hacking the
              system, but otherwise of not much use.  Since 2.3.21 this flag can
              be specified only by the system boot process (PID 0).  It
              disappeared in Linux 2.5.16.

       CLONE_PTRACE
              If CLONE_PTRACE is specified, and the calling process is being
              traced, then trace the child also (see ptrace(2)).

       CLONE_SETTLS (since Linux 2.5.32)
              The newtls argument is the new TLS (Thread Local Storage)
              descriptor.  (See set_thread_area(2).)

       CLONE_SIGHAND
              If CLONE_SIGHAND is set, the calling process and the child process
              share the same table of signal handlers.  If the calling process or
              child process calls sigaction(2) to change the behavior associated
              with a signal, the behavior is changed in the other process as well.
              However, the calling process and child processes still have distinct
              signal masks and sets of pending signals.  So, one of them may block
              or unblock some signals using sigprocmask(2) without affecting the
              other process.

              If CLONE_SIGHAND is not set, the child process inherits a copy of
              the signal handlers of the calling process at the time clone() is
              called.  Calls to sigaction(2) performed later by one of the
              processes have no effect on the other process.

              Since Linux 2.6.0-test6, flags must also include CLONE_VM if
              CLONE_SIGHAND is specified

       CLONE_STOPPED (since Linux 2.6.0-test2)
              If CLONE_STOPPED is set, then the child is initially stopped (as
              though it was sent a SIGSTOP signal), and must be resumed by sending
              it a SIGCONT signal.

              This flag was deprecated from Linux 2.6.25 onward, and was removed
              altogether in Linux 2.6.38.

       CLONE_SYSVSEM (since Linux 2.5.10)
              If CLONE_SYSVSEM is set, then the child and the calling process
              share a single list of System V semaphore undo values (see
              semop(2)).  If this flag is not set, then the child has a separate
              undo list, which is initially empty.

       CLONE_THREAD (since Linux 2.4.0-test8)
              If CLONE_THREAD is set, the child is placed in the same thread group
              as the calling process.  To make the remainder of the discussion of
              CLONE_THREAD more readable, the term "thread" is used to refer to
              the processes within a thread group.

              Thread groups were a feature added in Linux 2.4 to support the POSIX
              threads notion of a set of threads that share a single PID.
              Internally, this shared PID is the so-called thread group identifier
              (TGID) for the thread group.  Since Linux 2.4, calls to getpid(2)
              return the TGID of the caller.

              The threads within a group can be distinguished by their (system-
              wide) unique thread IDs (TID).  A new thread's TID is available as
              the function result returned to the caller of clone(), and a thread
              can obtain its own TID using gettid(2).

              When a call is made to clone() without specifying CLONE_THREAD, then
              the resulting thread is placed in a new thread group whose TGID is
              the same as the thread's TID.  This thread is the leader of the new
              thread group.

              A new thread created with CLONE_THREAD has the same parent process
              as the caller of clone() (i.e., like CLONE_PARENT), so that calls to
              getppid(2) return the same value for all of the threads in a thread
              group.  When a CLONE_THREAD thread terminates, the thread that
              created it using clone() is not sent a SIGCHLD (or other
              termination) signal; nor can the status of such a thread be obtained
              using wait(2).  (The thread is said to be detached.)

              After all of the threads in a thread group terminate the parent
              process of the thread group is sent a SIGCHLD (or other termination)
              signal.

              If any of the threads in a thread group performs an execve(2), then
              all threads other than the thread group leader are terminated, and
              the new program is executed in the thread group leader.

              If one of the threads in a thread group creates a child using
              fork(2), then any thread in the group can wait(2) for that child.

              Since Linux 2.5.35, flags must also include CLONE_SIGHAND if
              CLONE_THREAD is specified.

              Signals may be sent to a thread group as a whole (i.e., a TGID)
              using kill(2), or to a specific thread (i.e., TID) using tgkill(2).

              Signal dispositions and actions are process-wide: if an unhandled
              signal is delivered to a thread, then it will affect (terminate,
              stop, continue, be ignored in) all members of the thread group.

              Each thread has its own signal mask, as set by sigprocmask(2), but
              signals can be pending either: for the whole process (i.e.,
              deliverable to any member of the thread group), when sent with
              kill(2); or for an individual thread, when sent with tgkill(2).  A
              call to sigpending(2) returns a signal set that is the union of the
              signals pending for the whole process and the signals that are
              pending for the calling thread.

              If kill(2) is used to send a signal to a thread group, and the
              thread group has installed a handler for the signal, then the
              handler will be invoked in exactly one, arbitrarily selected member
              of the thread group that has not blocked the signal.  If multiple
              threads in a group are waiting to accept the same signal using
              sigwaitinfo(2), the kernel will arbitrarily select one of these
              threads to receive a signal sent using kill(2).

       CLONE_UNTRACED (since Linux 2.5.46)
              If CLONE_UNTRACED is specified, then a tracing process cannot force
              CLONE_PTRACE on this child process.

       CLONE_VFORK
              If CLONE_VFORK is set, the execution of the calling process is
              suspended until the child releases its virtual memory resources via
              a call to execve(2) or _exit(2) (as with vfork(2)).

              If CLONE_VFORK is not set then both the calling process and the
              child are schedulable after the call, and an application should not
              rely on execution occurring in any particular order.

       CLONE_VM
              If CLONE_VM is set, the calling process and the child process run in
              the same memory space.  In particular, memory writes performed by
              the calling process or by the child process are also visible in the
              other process.  Moreover, any memory mapping or unmapping performed
              with mmap(2) or munmap(2) by the child or calling process also
              affects the other process.

              If CLONE_VM is not set, the child process runs in a separate copy of
              the memory space of the calling process at the time of clone().
              Memory writes or file mappings/unmappings performed by one of the
              processes do not affect the other, as with fork(2).

sys_clone

       The sys_clone system call corresponds more closely to fork(2) in that
       execution in the child continues from the point of the call.  As such, the
       fn and arg arguments of the clone() wrapper function are omitted.
       Furthermore, the argument order changes.  The raw system call interface is
       roughly:

           long clone(unsigned long flags, void *child_stack,
                      void *ptid, void *ctid,
                      struct pt_regs *regs);

       Another difference for sys_clone is that the child_stack argument may be
       zero, in which case copy-on-write semantics ensure that the child gets
       separate copies of stack pages when either process modifies the stack.  In
       this case, for correct operation, the CLONE_VM option should not be
       specified.

Linux 2.4 and earlier

       In Linux 2.4 and earlier, clone() does not take arguments ptid, tls, and
       ctid.

RETURN VALUE top

       On success, the thread ID of the child process is returned in the caller's
       thread of execution.  On failure, -1 is returned in the caller's context,
       no child process will be created, and errno will be set appropriately.

ERRORS top

       EAGAIN Too many processes are already running.

       EINVAL CLONE_SIGHAND was specified, but CLONE_VM was not.  (Since Linux
              2.6.0-test6.)

       EINVAL CLONE_THREAD was specified, but CLONE_SIGHAND was not.  (Since Linux
              2.5.35.)

       EINVAL Both CLONE_FS and CLONE_NEWNS were specified in flags.

       EINVAL Both CLONE_NEWIPC and CLONE_SYSVSEM were specified in flags.

       EINVAL Both CLONE_NEWPID and CLONE_THREAD were specified in flags.

       EINVAL Returned by clone() when a zero value is specified for child_stack.

       EINVAL CLONE_NEWIPC was specified in flags, but the kernel was not
              configured with the CONFIG_SYSVIPC and CONFIG_IPC_NS options.

       EINVAL CLONE_NEWNET was specified in flags, but the kernel was not
              configured with the CONFIG_NET_NS option.

       EINVAL CLONE_NEWPID was specified in flags, but the kernel was not
              configured with the CONFIG_PID_NS option.

       EINVAL CLONE_NEWUTS was specified in flags, but the kernel was not
              configured with the CONFIG_UTS option.

       ENOMEM Cannot allocate sufficient memory to allocate a task structure for
              the child, or to copy those parts of the caller's context that need
              to be copied.

       EPERM  CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, or
              CLONE_NEWUTS was specified by an unprivileged process (process
              without CAP_SYS_ADMIN).

       EPERM  CLONE_PID was specified by a process other than process 0.

VERSIONS top

       There is no entry for clone() in libc5.  glibc2 provides clone() as
       described in this manual page.

CONFORMING TO top

       The clone() and sys_clone calls are Linux-specific and should not be used
       in programs intended to be portable.

NOTES top

       In the kernel 2.4.x series, CLONE_THREAD generally does not make the parent
       of the new thread the same as the parent of the calling process.  However,
       for kernel versions 2.4.7 to 2.4.18 the CLONE_THREAD flag implied the
       CLONE_PARENT flag (as in kernel 2.6).

       For a while there was CLONE_DETACHED (introduced in 2.5.32): parent wants
       no child-exit signal.  In 2.6.2 the need to give this together with
       CLONE_THREAD disappeared.  This flag is still defined, but has no effect.

       On i386, clone() should not be called through vsyscall, but directly
       through int $0x80.

       On ia64, a different system call is used:

       int __clone2(int (*fn)(void *),
                    void *child_stack_base, size_t stack_size,
                    int flags, void *arg, ...
                 /* pid_t *ptid, struct user_desc *tls, pid_t *ctid */ );

       The __clone2() system call operates in the same way as clone(), except that
       child_stack_base points to the lowest address of the child's stack area,
       and stack_size specifies the size of the stack pointed to by
       child_stack_base.

BUGS top

       Versions of the GNU C library that include the NPTL threading library
       contain a wrapper function for getpid(2) that performs caching of PIDs.
       This caching relies on support in the glibc wrapper for clone(), but as
       currently implemented, the cache may not be up to date in some
       circumstances.  In particular, if a signal is delivered to the child
       immediately after the clone() call, then a call to getpid(2) in a handler
       for the signal may return the PID of the calling process ("the parent"), if
       the clone wrapper has not yet had a chance to update the PID cache in the
       child.  (This discussion ignores the case where the child was created using
       CLONE_THREAD, when getpid(2) should return the same value in the child and
       in the process that called clone(), since the caller and the child are in
       the same thread group.  The stale-cache problem also does not occur if the
       flags argument includes CLONE_VM.)  To get the truth, it may be necessary
       to use code such as the following:

           #include <syscall.h>

           pid_t mypid;

           mypid = syscall(SYS_getpid);

SEE ALSO top

       fork(2), futex(2), getpid(2), gettid(2), set_thread_area(2),
       set_tid_address(2), tkill(2), unshare(2), wait(2), capabilities(7),
       pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-11-30                            CLONE(2)


close(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CLOSE(2)                     Linux Programmer's Manual                    CLOSE(2)

NAME top

       close - close a file descriptor

SYNOPSIS top

       #include <unistd.h>

       int close(int fd);

DESCRIPTION top

       close() closes a file descriptor, so that it no longer refers to any file
       and may be reused.  Any record locks (see fcntl(2)) held on the file it was
       associated with, and owned by the process, are removed (regardless of the
       file descriptor that was used to obtain the lock).

       If fd is the last file descriptor referring to the underlying open file
       description (see open(2)), the resources associated with the open file
       description are freed; if the descriptor was the last reference to a file
       which has been removed using unlink(2) the file is deleted.

RETURN VALUE top

       close() returns zero on success.  On error, -1 is returned, and errno is
       set appropriately.

ERRORS top

       EBADF  fd isn't a valid open file descriptor.

       EINTR  The close() call was interrupted by a signal; see signal(7).

       EIO    An I/O error occurred.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       Not checking the return value of close() is a common but nevertheless
       serious programming error.  It is quite possible that errors on a previous
       write(2) operation are first reported at the final close().  Not checking
       the return value when closing the file may lead to silent loss of data.
       This can especially be observed with NFS and with disk quota.

       A successful close does not guarantee that the data has been successfully
       saved to disk, as the kernel defers writes.  It is not common for a file
       system to flush the buffers when the stream is closed.  If you need to be
       sure that the data is physically stored use fsync(2).  (It will depend on
       the disk hardware at this point.)

       It is probably unwise to close file descriptors while they may be in use by
       system calls in other threads in the same process.  Since a file descriptor
       may be reused, there are some obscure race conditions that may cause
       unintended side effects.

SEE ALSO top

       fcntl(2), fsync(2), open(2), shutdown(2), unlink(2), fclose(3)

COLOPHON top

       This page is part of release 3.45 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-12-28                            CLOSE(2)


closedir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CLOSEDIR(3)                  Linux Programmer's Manual                 CLOSEDIR(3)

NAME top

       closedir - close a directory

SYNOPSIS top

       #include <sys/types.h>

       #include <dirent.h>

       int closedir(DIR *dirp);

DESCRIPTION top

       The closedir() function closes the directory stream associated with dirp.
       A successful call to closedir() also closes the underlying file descriptor
       associated with dirp.  The directory stream descriptor dirp is not
       available after this call.

RETURN VALUE top

       The closedir() function returns 0 on success.  On error, -1 is returned,
       and errno is set appropriately.

ERRORS top

       EBADF  Invalid directory stream descriptor dirp.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD.

SEE ALSO top

       close(2), opendir(3), readdir(3), rewinddir(3), scandir(3), seekdir(3),
       telldir(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-09-23                         CLOSEDIR(3)


syslog(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYSLOG(3)                    Linux Programmer's Manual                   SYSLOG(3)

NAME top

       closelog, openlog, syslog, vsyslog - send messages to the system logger

SYNOPSIS top

       #include <syslog.h>

       void openlog(const char *ident, int option, int facility);
       void syslog(int priority, const char *format, ...);
       void closelog(void);

       #include <stdarg.h>

       void vsyslog(int priority, const char *format, va_list ap);

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

       vsyslog(): _BSD_SOURCE

DESCRIPTION top

       closelog() closes the descriptor being used to write to the system logger.
       The use of closelog() is optional.

       openlog() opens a connection to the system logger for a program.  The
       string pointed to by ident is prepended to every message, and is typically
       set to the program name.  If ident is NULL, the program name is used.
       (POSIX.1-2008 does not specify the behavior when ident is NULL.)

       The option argument specifies flags which control the operation of
       openlog() and subsequent calls to syslog().  The facility argument
       establishes a default to be used if none is specified in subsequent calls
       to syslog().  Values for option and facility are given below.  The use of
       openlog() is optional; it will automatically be called by syslog() if
       necessary, in which case ident will default to NULL.

       syslog() generates a log message, which will be distributed by syslogd(8).
       The priority argument is formed by ORing the facility and the level values
       (explained below).  The remaining arguments are a format, as in printf(3)
       and any arguments required by the format, except that the two character
       sequence %m will be replaced by the error message string strerror(errno).
       A trailing newline may be added if needed.

       The function vsyslog() performs the same task as syslog() with the
       difference that it takes a set of arguments which have been obtained using
       the stdarg(3) variable argument list macros.

       The subsections below list the parameters used to set the values of option,
       facility, and priority.

option

       The option argument to openlog() is an OR of any of these:

       LOG_CONS       Write directly to system console if there is an error while
                      sending to system logger.

       LOG_NDELAY     Open the connection immediately (normally, the connection is
                      opened when the first message is logged).

       LOG_NOWAIT     Don't wait for child processes that may have been created
                      while logging the message.  (The GNU C library does not
                      create a child process, so this option has no effect on
                      Linux.)

       LOG_ODELAY     The converse of LOG_NDELAY; opening of the connection is
                      delayed until syslog() is called.  (This is the default, and
                      need not be specified.)

       LOG_PERROR     (Not in POSIX.1-2001 or POSIX.1-2008.)  Print to stderr as
                      well.

       LOG_PID        Include PID with each message.

facility

       The facility argument is used to specify what type of program is logging
       the message.  This lets the configuration file specify that messages from
       different facilities will be handled differently.

       LOG_AUTH       security/authorization messages

       LOG_AUTHPRIV   security/authorization messages (private)

       LOG_CRON       clock daemon (cron and at)

       LOG_DAEMON     system daemons without separate facility value

       LOG_FTP        ftp daemon

       LOG_KERN       kernel messages (these can't be generated from user
                      processes)

       LOG_LOCAL0 through LOG_LOCAL7
                      reserved for local use

       LOG_LPR        line printer subsystem

       LOG_MAIL       mail subsystem

       LOG_NEWS       USENET news subsystem

       LOG_SYSLOG     messages generated internally by syslogd(8)

       LOG_USER (default)
                      generic user-level messages

       LOG_UUCP       UUCP subsystem

level

       This determines the importance of the message.  The levels are, in order of
       decreasing importance:

       LOG_EMERG      system is unusable

       LOG_ALERT      action must be taken immediately

       LOG_CRIT       critical conditions

       LOG_ERR        error conditions

       LOG_WARNING    warning conditions

       LOG_NOTICE     normal, but significant, condition

       LOG_INFO       informational message

       LOG_DEBUG      debug-level message

       The function setlogmask(3) can be used to restrict logging to specified
       levels only.

CONFORMING TO top

       The functions openlog(), closelog(), and syslog() (but not vsyslog()) are
       specified in SUSv2, POSIX.1-2001, and POSIX.1-2008.  POSIX.1-2001 specifies
       only the LOG_USER and LOG_LOCAL* values for facility.  However, with the
       exception of LOG_AUTHPRIV and LOG_FTP, the other facility values appear on
       most UNIX systems.  The LOG_PERROR value for option is not specified by
       POSIX.1-2001 or POSIX.1-2008, but is available in most versions of UNIX.

NOTES top

       The argument ident in the call of openlog() is probably stored as-is.
       Thus, if the string it points to is changed, syslog() may start prepending
       the changed string, and if the string it points to ceases to exist, the
       results are undefined.  Most portable is to use a string constant.

       Never pass a string with user-supplied data as a format, use the following
       instead:

           syslog(priority, "%s", string);

SEE ALSO top

       logger(1), setlogmask(3), syslog.conf(5), syslogd(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-17                           SYSLOG(3)


cmsg(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CMSG(3)                      Linux Programmer's Manual                     CMSG(3)

NAME top

       CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - access ancillary data

SYNOPSIS top

       #include <sys/socket.h>

       struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
       struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh, struct cmsghdr *cmsg);
       size_t CMSG_ALIGN(size_t length);
       size_t CMSG_SPACE(size_t length);
       size_t CMSG_LEN(size_t length);
       unsigned char *CMSG_DATA(struct cmsghdr *cmsg);

       struct cmsghdr {
           socklen_t cmsg_len;    /* data byte count, including header */
           int       cmsg_level;  /* originating protocol */
           int       cmsg_type;   /* protocol-specific type */
           /* followed by unsigned char cmsg_data[]; */
       };

DESCRIPTION top

       These macros are used to create and access control messages (also called
       ancillary data) that are not a part of the socket payload.  This control
       information may include the interface the packet was received on, various
       rarely used header fields, an extended error description, a set of file
       descriptors or UNIX credentials.  For instance, control messages can be
       used to send additional header fields such as IP options.  Ancillary data
       is sent by calling sendmsg(2) and received by calling recvmsg(2).  See
       their manual pages for more information.

       Ancillary data is a sequence of struct cmsghdr structures with appended
       data.  This sequence should only be accessed using the macros described in
       this manual page and never directly.  See the specific protocol man pages
       for the available control message types.  The maximum ancillary buffer size
       allowed per socket can be set using /proc/sys/net/core/optmem_max; see
       socket(7).

       CMSG_FIRSTHDR() returns a pointer to the first cmsghdr in the ancillary
       data buffer associated with the passed msghdr.

       CMSG_NXTHDR() returns the next valid cmsghdr after the passed cmsghdr.  It
       returns NULL when there isn't enough space left in the buffer.

       CMSG_ALIGN(), given a length, returns it including the required alignment.
       This is a constant expression.

       CMSG_SPACE() returns the number of bytes an ancillary element with payload
       of the passed data length occupies.  This is a constant expression.

       CMSG_DATA() returns a pointer to the data portion of a cmsghdr.

       CMSG_LEN() returns the value to store in the cmsg_len member of the cmsghdr
       structure, taking into account any necessary alignment.  It takes the data
       length as an argument.  This is a constant expression.

       To create ancillary data, first initialize the msg_controllen member of the
       msghdr with the length of the control message buffer.  Use CMSG_FIRSTHDR()
       on the msghdr to get the first control message and CMSG_NXTHDR() to get all
       subsequent ones.  In each control message, initialize cmsg_len (with
       CMSG_LEN()), the other cmsghdr header fields, and the data portion using
       CMSG_DATA().  Finally, the msg_controllen field of the msghdr should be set
       to the sum of the CMSG_SPACE() of the length of all control messages in the
       buffer.  For more information on the msghdr, see recvmsg(2).

       When the control message buffer is too short to store all messages, the
       MSG_CTRUNC flag is set in the msg_flags member of the msghdr.

CONFORMING TO top

       This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, the
       IPv6 advanced API described in RFC 2292 and the SUSv2.  CMSG_ALIGN() is a
       Linux extension.

NOTES top

       For portability, ancillary data should be accessed only using the macros
       described here.  CMSG_ALIGN() is a Linux extension and should be not used
       in portable programs.

       In Linux, CMSG_LEN(), CMSG_DATA(), and CMSG_ALIGN() are constant
       expressions (assuming their argument is constant); this could be used to
       declare the size of global variables.  This may be not portable, however.

EXAMPLE top

       This code looks for the IP_TTL option in a received ancillary buffer:

           struct msghdr msgh;
           struct cmsghdr *cmsg;
           int *ttlptr;
           int received_ttl;

           /* Receive auxiliary data in msgh */
           for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
                   cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
               if (cmsg->cmsg_level == IPPROTO_IP
                       && cmsg->cmsg_type == IP_TTL) {
                   ttlptr = (int *) CMSG_DATA(cmsg);
                   received_ttl = *ttlptr;
                   break;
               }
           }
           if (cmsg == NULL) {
               /*
                * Error: IP_TTL not enabled or small buffer
                * or I/O error.
                */
           }

       The code below passes an array of file descriptors over a UNIX domain
       socket using SCM_RIGHTS:

           struct msghdr msg = {0};
           struct cmsghdr *cmsg;
           int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
           char buf[CMSG_SPACE(sizeof myfds)];  /* ancillary data buffer */
           int *fdptr;

           msg.msg_control = buf;
           msg.msg_controllen = sizeof buf;
           cmsg = CMSG_FIRSTHDR(&msg);
           cmsg->cmsg_level = SOL_SOCKET;
           cmsg->cmsg_type = SCM_RIGHTS;
           cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
           /* Initialize the payload: */
           fdptr = (int *) CMSG_DATA(cmsg);
           memcpy(fdptr, myfds, NUM_FD * sizeof(int));
           /* Sum of the length of all control messages in the buffer: */
           msg.msg_controllen = cmsg->cmsg_len;

SEE ALSO top

       recvmsg(2), sendmsg(2)

       RFC 2292

COLOPHON top

       This page is part of release 3.45 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-20                             CMSG(3)


complex(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

COMPLEX(7)                   Linux Programmer's Manual                  COMPLEX(7)

NAME top

       complex - basics of complex mathematics

SYNOPSIS top

       #include <complex.h>

DESCRIPTION top

       Complex numbers are numbers of the form z = a+b*i, where a and b are real
       numbers and i = sqrt(-1), so that i*i = -1.
       There are other ways to represent that number.  The pair (a,b) of real
       numbers may be viewed as a point in the plane, given by X- and Y-
       coordinates.  This same point may also be described by giving the pair of
       real numbers (r,phi), where r is the distance to the origin O, and phi the
       angle between the X-axis and the line Oz.  Now z = r*exp(i*phi) =
       r*(cos(phi)+i*sin(phi)).

       The basic operations are defined on z = a+b*i and w = c+d*i as:

       addition: z+w = (a+c) + (b+d)*i

       multiplication: z*w = (a*c - b*d) + (a*d + b*c)*i

       division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c - a*d)/(c*c + d*d))*i

       Nearly all math function have a complex counterpart but there are some
       complex-only functions.

EXAMPLE top

       Your C-compiler can work with complex numbers if it supports the C99
       standard.  Link with -lm.  The imaginary unit is represented by I.

       /* check that exp(i * pi) == -1 */
       #include <math.h>        /* for atan */
       #include <stdio.h>
       #include <complex.h>

       int
       main(void)
       {
           double pi = 4 * atan(1.0);
           double complex z = cexp(I * pi);
           printf("%f + %f * i\n", creal(z), cimag(z));
       }

SEE ALSO top

       cabs(3), cacos(3), cacosh(3), carg(3), casin(3), casinh(3), catan(3),
       catanh(3), ccos(3), ccosh(3), cerf(3), cexp(3), cexp2(3), cimag(3),
       clog(3), clog10(3), clog2(3), conj(3), cpow(3), cproj(3), creal(3),
       csin(3), csinh(3), csqrt(3), ctan(3), ctanh(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2011-09-16                          COMPLEX(7)


confstr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CONFSTR(3)                   Linux Programmer's Manual                  CONFSTR(3)

NAME top

       confstr - get configuration dependent string variables

SYNOPSIS top

       #include <unistd.h>

       size_t confstr(int name, char *buf, size_t len);

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

       confstr(): _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE

DESCRIPTION top

       confstr() gets the value of configuration-dependent string variables.

       The name argument is the system variable to be queried.  The following
       variables are supported:

       _CS_GNU_LIBC_VERSION (GNU C library only; since glibc 2.3.2)
              A string which identifies the GNU C library version on this system
              (e.g, "glibc 2.3.4").

       _CS_GNU_LIBPTHREAD_VERSION (GNU C library only; since glibc 2.3.2)
              A string which identifies the POSIX implementation supplied by this
              C library (e.g, "NPTL 2.3.4" or "linuxthreads-0.10").

       _CS_PATH
              A value for the PATH variable which indicates where all the POSIX.2
              standard utilities can be found.

       If buf is not NULL and len is not zero, confstr() copies the value of the
       string to buf truncated to len - 1 bytes if necessary, with a null byte
       ('\0') as terminator.  This can be detected by comparing the return value
       of confstr() against len.

       If len is zero and buf is NULL, confstr() just returns the value as defined
       below.

RETURN VALUE top

       If name is a valid configuration variable, confstr() returns the number of
       bytes (including the terminating null byte) that would be required to hold
       the entire value of that variable.  This value may be greater than len,
       which means that the value in buf is truncated.

       If name is a valid configuration variable, but that variable does not have
       a value, then confstr() returns 0.  If name does not correspond to a valid
       configuration variable, confstr() returns 0, and errno is set to EINVAL.

ERRORS top

       EINVAL If the value of name is invalid.

CONFORMING TO top

       POSIX.1-2001.

EXAMPLE top

       The following code fragment determines the path where to find the POSIX.2
       system utilities:

           char *pathbuf;
           size_t n;

           n = confstr(_CS_PATH, NULL, (size_t) 0);
           pathbuf = malloc(n);
           if (pathbuf == NULL)
               abort();
           confstr(_CS_PATH, pathbuf, n);

SEE ALSO top

       sh(1), exec(3), system(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                          CONFSTR(3)


conj(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CONJ(3)                      Linux Programmer's Manual                     CONJ(3)

NAME top

       conj, conjf, conjl - calculate the complex conjugate

SYNOPSIS top

       #include <complex.h>

       double complex conj(double complex z);
       float complex conjf(float complex z);
       long double complex conjl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The conj() function returns the complex conjugate value of z.  That is the
       value obtained by changing the sign of the imaginary part.

       One has:

           cabs(z) = csqrt(z * conj(z))

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), csqrt(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CONJ(3)


connect(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CONNECT(2)                   Linux Programmer's Manual                  CONNECT(2)

NAME top

       connect - initiate a connection on a socket

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int connect(int sockfd, const struct sockaddr *addr,
                   socklen_t addrlen);

DESCRIPTION top

       The connect() system call connects the socket referred to by the file
       descriptor sockfd to the address specified by addr.  The addrlen argument
       specifies the size of addr.  The format of the address in addr is
       determined by the address space of the socket sockfd; see socket(2) for
       further details.

       If the socket sockfd is of type SOCK_DGRAM then addr is the address to
       which datagrams are sent by default, and the only address from which
       datagrams are received.  If the socket is of type SOCK_STREAM or
       SOCK_SEQPACKET, this call attempts to make a connection to the socket that
       is bound to the address specified by addr.

       Generally, connection-based protocol sockets may successfully connect()
       only once; connectionless protocol sockets may use connect() multiple times
       to change their association.  Connectionless sockets may dissolve the
       association by connecting to an address with the sa_family member of
       sockaddr set to AF_UNSPEC (supported on Linux since kernel 2.2).

RETURN VALUE top

       If the connection or binding succeeds, zero is returned.  On error, -1 is
       returned, and errno is set appropriately.

ERRORS top

       The following are general socket errors only.  There may be other domain-
       specific error codes.

       EACCES For UNIX domain sockets, which are identified by pathname: Write
              permission is denied on the socket file, or search permission is
              denied for one of the directories in the path prefix.  (See also
              path_resolution(7).)

       EACCES, EPERM
              The user tried to connect to a broadcast address without having the
              socket broadcast flag enabled or the connection request failed
              because of a local firewall rule.

       EADDRINUSE
              Local address is already in use.

       EAFNOSUPPORT
              The passed address didn't have the correct address family in its
              sa_family field.

       EAGAIN No more free local ports or insufficient entries in the routing
              cache.  For AF_INET see the description of
              /proc/sys/net/ipv4/ip_local_port_range ip(7) for information on how
              to increase the number of local ports.

       EALREADY
              The socket is nonblocking and a previous connection attempt has not
              yet been completed.

       EBADF  The file descriptor is not a valid index in the descriptor table.

       ECONNREFUSED
              No-one listening on the remote address.

       EFAULT The socket structure address is outside the user's address space.

       EINPROGRESS
              The socket is nonblocking and the connection cannot be completed
              immediately.  It is possible to select(2) or poll(2) for completion
              by selecting the socket for writing.  After select(2) indicates
              writability, use getsockopt(2) to read the SO_ERROR option at level
              SOL_SOCKET to determine whether connect() completed successfully
              (SO_ERROR is zero) or unsuccessfully (SO_ERROR is one of the usual
              error codes listed here, explaining the reason for the failure).

       EINTR  The system call was interrupted by a signal that was caught; see
              signal(7).

       EISCONN
              The socket is already connected.

       ENETUNREACH
              Network is unreachable.

       ENOTSOCK
              The file descriptor is not associated with a socket.

       ETIMEDOUT
              Timeout while attempting connection.  The server may be too busy to
              accept new connections.  Note that for IP sockets the timeout may be
              very long when syncookies are enabled on the server.

CONFORMING TO top

       SVr4, 4.4BSD, (the connect() function first appeared in 4.2BSD),
       POSIX.1-2001.

NOTES top

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

       The third argument of connect() is in reality an int (and this is what 4.x
       BSD and libc4 and libc5 have).  Some POSIX confusion resulted in the
       present socklen_t, also used by glibc.  See also accept(2).

EXAMPLE top

       An example of the use of connect() is shown in getaddrinfo(3).

SEE ALSO top

       accept(2), bind(2), getsockname(2), listen(2), socket(2),
       path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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-03                          CONNECT(2)


console(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

CONSOLE(4)                   Linux Programmer's Manual                  CONSOLE(4)

NAME top

       console - console terminal and virtual consoles

DESCRIPTION top

       A Linux system has up to 63 virtual consoles (character devices with major
       number 4 and minor number 1 to 63), usually called /dev/ttyn with 1 <= n <=
       63.  The current console is also addressed by /dev/console or /dev/tty0,
       the character device with major number 4 and minor number 0.  The device
       files /dev/* are usually created using the script MAKEDEV, or using
       mknod(1), usually with mode 0622 and owner root.tty.

       Before kernel version 1.1.54 the number of virtual consoles was compiled
       into the kernel (in tty.h: #define NR_CONSOLES 8) and could be changed by
       editing and recompiling.  Since version 1.1.54 virtual consoles are created
       on the fly, as soon as they are needed.

       Common ways to start a process on a console are: (a) tell init(8) (in
       inittab(5)) to start a mingetty(8) (or agetty(8)) on the console; (b) ask
       openvt(1) to start a process on the console; (c) start X--it will find the
       first unused console, and display its output there.  (There is also the
       ancient doshell(8).)

       Common ways to switch consoles are: (a) use Alt+Fn or Ctrl+Alt+Fn to switch
       to console n; AltGr+Fn might bring you to console n+12 [here Alt and AltGr
       refer to the left and right Alt keys, respectively]; (b) use Alt+RightArrow
       or Alt+LeftArrow to cycle through the presently allocated consoles; (c) use
       the program chvt(1).  (The key mapping is user settable, see loadkeys(1);
       the above mentioned key combinations are according to the default
       settings.)

       The command deallocvt(1) (formerly disalloc) will free the memory taken by
       the screen buffers for consoles that no longer have any associated process.

Properties

       Consoles carry a lot of state.  I hope to document that some other time.
       The most important fact is that the consoles simulate vt100 terminals.  In
       particular, a console is reset to the initial state by printing the two
       characters ESC c.  All escape sequences can be found in console_codes(4).

FILES top

       /dev/console
       /dev/tty*

SEE ALSO top

       chvt(1), deallocvt(1), loadkeys(1), mknod(1), openvt(1), console_codes(4),
       console_ioctl(4), tty(4), ttyS(4), charsets(7), agetty(8), init(8),
       mapscrn(8), mingetty(8), resizecons(8), setfont(8)

COLOPHON top

       This page is part of release 3.45 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                               1994-10-31                          CONSOLE(4)


console_codes(4) - Linux manual page

NAME | DESCRIPTION | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

CONSOLE_CODES(4)             Linux Programmer's Manual            CONSOLE_CODES(4)

NAME top

       console_codes - Linux console escape and control sequences

DESCRIPTION top

       The Linux console implements a large subset of the VT102 and ECMA-48/ISO
       6429/ANSI X3.64 terminal controls, plus certain private-mode sequences for
       changing the color palette, character-set mapping, and so on.  In the
       tabular descriptions below, the second column gives ECMA-48 or DEC
       mnemonics (the latter if prefixed with DEC) for the given function.
       Sequences without a mnemonic are neither ECMA-48 nor VT102.

       After all the normal output processing has been done, and a stream of
       characters arrives at the console driver for actual printing, the first
       thing that happens is a translation from the code used for processing to
       the code used for printing.

       If the console is in UTF-8 mode, then the incoming bytes are first
       assembled into 16-bit Unicode codes.  Otherwise each byte is transformed
       according to the current mapping table (which translates it to a Unicode
       value).  See the Character Sets section below for discussion.

       In the normal case, the Unicode value is converted to a font index, and
       this is stored in video memory, so that the corresponding glyph (as found
       in video ROM) appears on the screen.  Note that the use of Unicode (and the
       design of the PC hardware) allows us to use 512 different glyphs
       simultaneously.

       If the current Unicode value is a control character, or we are currently
       processing an escape sequence, the value will treated specially.  Instead
       of being turned into a font index and rendered as a glyph, it may trigger
       cursor movement or other control functions.  See the Linux Console Controls
       section below for discussion.

       It is generally not good practice to hard-wire terminal controls into
       programs.  Linux supports a terminfo(5) database of terminal capabilities.
       Rather than emitting console escape sequences by hand, you will almost
       always want to use a terminfo-aware screen library or utility such as
       ncurses(3), tput(1), or reset(1).

Linux Console Controls

       This section describes all the control characters and escape sequences that
       invoke special functions (i.e., anything other than writing a glyph at the
       current cursor location) on the Linux console.

       Control characters

       A character is a control character if (before transformation according to
       the mapping table) it has one of the 14 codes 00 (NUL), 07 (BEL), 08 (BS),
       09 (HT), 0a (LF), 0b (VT), 0c (FF), 0d (CR), 0e (SO), 0f (SI), 18 (CAN), 1a
       (SUB), 1b (ESC), 7f (DEL).  One can set a "display control characters" mode
       (see below), and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs.
       On the other hand, in UTF-8 mode all codes 00-1f are regarded as control
       characters, regardless of any "display control characters" mode.

       If we have a control character, it is acted upon immediately and then
       discarded (even in the middle of an escape sequence) and the escape
       sequence continues with the next character.  (However, ESC starts a new
       escape sequence, possibly aborting a previous unfinished one, and CAN and
       SUB abort any escape sequence.)  The recognized control characters are BEL,
       BS, HT, LF, VT, FF, CR, SO, SI, CAN, SUB, ESC, DEL, CSI.  They do what one
       would expect:

       BEL (0x07, ^G) beeps;

       BS (0x08, ^H) backspaces one column (but not past the beginning of the
              line);

       HT (0x09, ^I) goes to the next tab stop or to the end of the line if there
              is no earlier tab stop;

       LF (0x0A, ^J), VT (0x0B, ^K) and FF (0x0C, ^L) all give a linefeed, and if
              LF/NL (new-line mode) is set also a carriage return;

       CR (0x0D, ^M) gives a carriage return;

       SO (0x0E, ^N) activates the G1 character set;

       SI (0x0F, ^O) activates the G0 character set;

       CAN (0x18, ^X) and SUB (0x1A, ^Z) interrupt escape sequences;

       ESC (0x1B, ^[) starts an escape sequence;

       DEL (0x7F) is ignored;

       CSI (0x9B) is equivalent to ESC [.

       ESC- but not CSI-sequences

       ESC c     RIS      Reset.
       ESC D     IND      Linefeed.
       ESC E     NEL      Newline.
       ESC H     HTS      Set tab stop at current column.
       ESC M     RI       Reverse linefeed.
       ESC Z     DECID    DEC private identification. The kernel returns the
                          string  ESC [ ? 6 c, claiming that it is a VT102.
       ESC 7     DECSC    Save current state (cursor coordinates,
                          attributes, character sets pointed at by G0, G1).
       ESC 8     DECRC    Restore state most recently saved by ESC 7.
       ESC [     CSI      Control sequence introducer
       ESC %              Start sequence selecting character set
       ESC % @               Select default (ISO 646 / ISO 8859-1)
       ESC % G               Select UTF-8
       ESC % 8               Select UTF-8 (obsolete)
       ESC # 8   DECALN   DEC screen alignment test - fill screen with E's.
       ESC (              Start sequence defining G0 character set
       ESC ( B               Select default (ISO 8859-1 mapping)
       ESC ( 0               Select VT100 graphics mapping
       ESC ( U               Select null mapping - straight to character ROM
       ESC ( K               Select user mapping - the map that is loaded by
                             the utility mapscrn(8).
       ESC )              Start sequence defining G1
                          (followed by one of B, 0, U, K, as above).
       ESC >     DECPNM   Set numeric keypad mode
       ESC =     DECPAM   Set application keypad mode
       ESC ]     OSC      (Should be: Operating system command) ESC ] P
                          nrrggbb: set palette, with parameter given in 7
                          hexadecimal digits after the final P :-(.  Here n
                          is the color (0-15), and rrggbb indicates the
                          red/green/blue values (0-255).  ESC ] R: reset
                          palette

       ECMA-48 CSI sequences

       CSI (or ESC [) is followed by a sequence of parameters, at most NPAR (16),
       that are decimal numbers separated by semicolons.  An empty or absent
       parameter is taken to be 0.  The sequence of parameters may be preceded by
       a single question mark.

       However, after CSI [ (or ESC [ [) a single character is read and this
       entire sequence is ignored.  (The idea is to ignore an echoed function
       key.)

       The action of a CSI sequence is determined by its final character.

       @   ICH       Insert the indicated # of blank characters.
       A   CUU       Move cursor up the indicated # of rows.
       B   CUD       Move cursor down the indicated # of rows.
       C   CUF       Move cursor right the indicated # of columns.
       D   CUB       Move cursor left the indicated # of columns.
       E   CNL       Move cursor down the indicated # of rows, to column 1.
       F   CPL       Move cursor up the indicated # of rows, to column 1.
       G   CHA       Move cursor to indicated column in current row.
       H   CUP       Move cursor to the indicated row, column (origin at 1,1).
       J   ED        Erase display (default: from cursor to end of display).
                     ESC [ 1 J: erase from start to cursor.
                     ESC [ 2 J: erase whole display.
                     ESC [ 3 J: erase whole display including scroll-back
                                buffer (since Linux 3.0).
       K   EL        Erase line (default: from cursor to end of line).
                     ESC [ 1 K: erase from start of line to cursor.
                     ESC [ 2 K: erase whole line.
       L   IL        Insert the indicated # of blank lines.
       M   DL        Delete the indicated # of lines.
       P   DCH       Delete the indicated # of characters on current line.
       X   ECH       Erase the indicated # of characters on current line.
       a   HPR       Move cursor right the indicated # of columns.
       c   DA        Answer ESC [ ? 6 c: "I am a VT102".
       d   VPA       Move cursor to the indicated row, current column.
       e   VPR       Move cursor down the indicated # of rows.
       f   HVP       Move cursor to the indicated row, column.
       g   TBC       Without parameter: clear tab stop at current position.
                     ESC [ 3 g: delete all tab stops.
       h   SM        Set Mode (see below).
       l   RM        Reset Mode (see below).
       m   SGR       Set attributes (see below).
       n   DSR       Status report (see below).
       q   DECLL     Set keyboard LEDs.
                     ESC [ 0 q: clear all LEDs
                     ESC [ 1 q: set Scroll Lock LED
                     ESC [ 2 q: set Num Lock LED
                     ESC [ 3 q: set Caps Lock LED
       r   DECSTBM   Set scrolling region; parameters are top and bottom row.
       s   ?         Save cursor location.
       u   ?         Restore cursor location.
       `   HPA       Move cursor to indicated column in current row.

       ECMA-48 Set Graphics Rendition

       The ECMA-48 SGR sequence ESC [ parameters m sets display attributes.
       Several attributes can be set in the same sequence, separated by
       semicolons.  An empty parameter (between semicolons or string initiator or
       terminator) is interpreted as a zero.

       param   result
       0       reset all attributes to their defaults
       1       set bold
       2       set half-bright (simulated with color on a color display)
       4       set underscore (simulated with color on a color display)
               (the colors used to simulate dim or underline are set
               using ESC ] ...)
       5       set blink
       7       set reverse video

       10      reset selected mapping, display control flag, and toggle
               meta flag (ECMA-48 says "primary font").
       11      select null mapping, set display control flag, reset
               toggle meta flag (ECMA-48 says "first alternate font").
       12      select null mapping, set display control flag, set toggle
               meta flag (ECMA-48 says "second alternate font").  The
               toggle meta flag causes the high bit of a byte to be
               toggled before the mapping table translation is done.
       21      set normal intensity (ECMA-48 says "doubly underlined")
       22      set normal intensity
       24      underline off
       25      blink off
       27      reverse video off
       30      set black foreground
       31      set red foreground
       32      set green foreground
       33      set brown foreground
       34      set blue foreground
       35      set magenta foreground
       36      set cyan foreground
       37      set white foreground
       38      set underscore on, set default foreground color
       39      set underscore off, set default foreground color
       40      set black background
       41      set red background
       42      set green background
       43      set brown background
       44      set blue background
       45      set magenta background
       46      set cyan background
       47      set white background
       49      set default background color

       ECMA-48 Mode Switches

       ESC [ 3 h
              DECCRM (default off): Display control chars.

       ESC [ 4 h
              DECIM (default off): Set insert mode.

       ESC [ 20 h
              LF/NL (default off): Automatically follow echo of LF, VT or FF with
              CR.

       ECMA-48 Status Report Commands

       ESC [ 5 n
              Device status report (DSR): Answer is ESC [ 0 n (Terminal OK).

       ESC [ 6 n
              Cursor position report (CPR): Answer is ESC [ y ; x R, where x,y is
              the cursor location.

       DEC Private Mode (DECSET/DECRST) sequences

       These are not described in ECMA-48.  We list the Set Mode sequences; the
       Reset Mode sequences are obtained by replacing the final 'h' by 'l'.

       ESC [ ? 1 h
              DECCKM (default off): When set, the cursor keys send an ESC O
              prefix, rather than ESC [.

       ESC [ ? 3 h
              DECCOLM (default off = 80 columns): 80/132 col mode switch.  The
              driver sources note that this alone does not suffice; some user-mode
              utility such as resizecons(8) has to change the hardware registers
              on the console video card.

       ESC [ ? 5 h
              DECSCNM (default off): Set reverse-video mode.

       ESC [ ? 6 h
              DECOM (default off): When set, cursor addressing is relative to the
              upper left corner of the scrolling region.

       ESC [ ? 7 h
              DECAWM (default on): Set autowrap on.  In this mode, a graphic
              character emitted after column 80 (or column 132 of DECCOLM is on)
              forces a wrap to the beginning of the following line first.

       ESC [ ? 8 h
              DECARM (default on): Set keyboard autorepeat on.

       ESC [ ? 9 h
              X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset
              to 0)--see below.

       ESC [ ? 25 h
              DECTECM (default on): Make cursor visible.

       ESC [ ? 1000 h
              X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset
              to 0)--see below.

       Linux Console Private CSI Sequences

       The following sequences are neither ECMA-48 nor native VT102.  They are
       native to the Linux console driver.  Colors are in SGR parameters: 0 =
       black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 = cyan, 7 =
       white.

       ESC [ 1 ; n ]       Set color n as the underline color
       ESC [ 2 ; n ]       Set color n as the dim color
       ESC [ 8 ]           Make the current color pair the default attributes.
       ESC [ 9 ; n ]       Set screen blank timeout to n minutes.
       ESC [ 10 ; n ]      Set bell frequency in Hz.
       ESC [ 11 ; n ]      Set bell duration in msec.
       ESC [ 12 ; n ]      Bring specified console to the front.
       ESC [ 13 ]          Unblank the screen.
       ESC [ 14 ; n ]      Set the VESA powerdown interval in minutes.

Character Sets

       The kernel knows about 4 translations of bytes into console-screen symbols.
       The four tables are: a) Latin1 -> PC, b) VT100 graphics -> PC, c) PC -> PC,
       d) user-defined.

       There are two character sets, called G0 and G1, and one of them is the
       current character set.  (Initially G0.)  Typing ^N causes G1 to become
       current, ^O causes G0 to become current.

       These variables G0 and G1 point at a translation table, and can be changed
       by the user.  Initially they point at tables a) and b), respectively.  The
       sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point at
       translation table a), b), c) and d), respectively.  The sequences ESC ) B
       and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point at translation table
       a), b), c) and d), respectively.

       The sequence ESC c causes a terminal reset, which is what you want if the
       screen is all garbled.  The oft-advised "echo ^V^O" will only make G0
       current, but there is no guarantee that G0 points at table a).  In some
       distributions there is a program reset(1) that just does "echo ^[c".  If
       your terminfo entry for the console is correct (and has an entry rs1=\Ec),
       then "tput reset" will also work.

       The user-defined mapping table can be set using mapscrn(8).  The result of
       the mapping is that if a symbol c is printed, the symbol s = map[c] is sent
       to the video memory.  The bitmap that corresponds to s is found in the
       character ROM, and can be changed using setfont(8).

Mouse Tracking

       The mouse tracking facility is intended to return xterm(1)-compatible mouse
       status reports.  Because the console driver has no way to know the device
       or type of the mouse, these reports are returned in the console input
       stream only when the virtual terminal driver receives a mouse update ioctl.
       These ioctls must be generated by a mouse-aware user-mode application such
       as the gpm(8) daemon.

       The mouse tracking escape sequences generated by xterm(1) encode numeric
       parameters in a single character as value+040.  For example, '!' is 1.  The
       screen coordinate system is 1-based.

       The X10 compatibility mode sends an escape sequence on button press
       encoding the location and the mouse button pressed.  It is enabled by
       sending ESC [ ? 9 h and disabled with ESC [ ? 9 l.  On button press,
       xterm(1) sends ESC [ M bxy (6 characters).  Here b is button-1, and x and y
       are the x and y coordinates of the mouse when the button was pressed.  This
       is the same code the kernel also produces.

       Normal tracking mode (not implemented in Linux 2.0.24) sends an escape
       sequence on both button press and release.  Modifier information is also
       sent.  It is enabled by sending ESC [ ? 1000 h and disabled with ESC [ ?
       1000 l.  On button press or release, xterm(1) sends ESC [ M bxy.  The low
       two bits of b encode button information: 0=MB1 pressed, 1=MB2 pressed,
       2=MB3 pressed, 3=release.  The upper bits encode what modifiers were down
       when the button was pressed and are added together: 4=Shift, 8=Meta,
       16=Control.  Again x and y are the x and y coordinates of the mouse event.
       The upper left corner is (1,1).

Comparisons With Other Terminals

       Many different terminal types are described, like the Linux console, as
       being "VT100-compatible".  Here we discuss differences between the Linux
       console and the two most important others, the DEC VT102 and xterm(1).

       Control-character handling

       The VT102 also recognized the following control characters:

       NUL (0x00) was ignored;

       ENQ (0x05) triggered an answerback message;

       DC1 (0x11, ^Q, XON) resumed transmission;

       DC3 (0x13, ^S, XOFF) caused VT100 to ignore (and stop transmitting) all
              codes except XOFF and XON.

       VT100-like DC1/DC3 processing may be enabled by the tty driver.

       The xterm(1) program (in VT100 mode) recognizes the control characters BEL,
       BS, HT, LF, VT, FF, CR, SO, SI, ESC.

       Escape sequences

       VT100 console sequences not implemented on the Linux console:

       ESC N       SS2   Single shift 2. (Select G2 character set for the next

                         character only.)
       ESC O       SS3   Single shift 3. (Select G3 character set for the next
                         character only.)
       ESC P       DCS   Device control string (ended by ESC \)
       ESC X       SOS   Start of string.
       ESC ^       PM    Privacy message (ended by ESC \)
       ESC \       ST    String terminator
       ESC * ...         Designate G2 character set
       ESC + ...         Designate G3 character set

       The program xterm(1) (in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC
       =, ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \, ESC Z (it
       answers ESC [ ? 1 ; 2 c, "I am a VT100 with advanced video option") and ESC
       ^ ... ESC \ with the same meanings as indicated above.  It accepts ESC (,
       ESC ), ESC *,  ESC + followed by 0, A, B for the DEC special character and
       line drawing set, UK, and US-ASCII, respectively.

       The user can configure xterm(1) to respond to VT220-specific control
       sequences, and it will identify itself as a VT52, VT100, and up depending
       on the way it is configured and initialized.

       It accepts ESC ] (OSC) for the setting of certain resources.  In addition
       to the ECMA-48 string terminator (ST), xterm(1) accepts a BEL to terminate
       an OSC string.  These are a few of the OSC control sequences recognized by
       xterm(1):

       ESC ] 0 ; txt ST        Set icon name and window title to txt.
       ESC ] 1 ; txt ST        Set icon name to txt.
       ESC ] 2 ; txt ST        Set window title to txt.
       ESC ] 4 ; num; txt ST   Set ANSI color num to txt.
       ESC ] 10 ; txt ST       Set dynamic text color to txt.
       ESC ] 4 6 ; name ST     Change log file to name (normally disabled
                               by a compile-time option)
       ESC ] 5 0 ; fn ST       Set font to fn.

       It recognizes the following with slightly modified meaning (saving more
       state, behaving closer to VT100/VT220):

       ESC 7  DECSC   Save cursor
       ESC 8  DECRC   Restore cursor

       It also recognizes

       ESC F          Cursor to lower left corner of screen (if enabled by
                      xterm(1)'s hpLowerleftBugCompat resource)
       ESC l          Memory lock (per HP terminals).
                      Locks memory above the cursor.
       ESC m          Memory unlock (per HP terminals).
       ESC n   LS2    Invoke the G2 character set.
       ESC o   LS3    Invoke the G3 character set.
       ESC |   LS3R   Invoke the G3 character set as GR.
       ESC }   LS2R   Invoke the G2 character set as GR.
       ESC ~   LS1R   Invoke the G1 character set as GR.

       It also recognizes ESC % and provides a more complete UTF-8 implementation
       than Linux console.

       CSI Sequences

       Old versions of xterm(1), for example, from X11R5, interpret the blink SGR
       as a bold SGR.  Later versions which implemented ANSI colors, for example,
       XFree86 3.1.2A in 1995, improved this by allowing the blink attribute to be
       displayed as a color.  Modern versions of xterm implement blink SGR as
       blinking text and still allow colored text as an alternate rendering of
       SGRs.  Stock X11R6 versions did not recognize the color-setting SGRs until
       the X11R6.8 release, which incorporated XFree86 xterm.  All ECMA-48 CSI
       sequences recognized by Linux are also recognized by xterm, however
       xterm(1) implements several ECMA-48 and DEC control sequences not
       recognized by Linux.

       The xterm(1) program recognizes all of the DEC Private Mode sequences
       listed above, but none of the Linux private-mode sequences.  For discussion
       of xterm(1)'s own private-mode sequences, refer to the Xterm Control
       Sequences document by Edward Moy, Stephen Gildea, and Thomas E. Dickey
       available with the X distribution.  That document, though terse, is much
       longer than this manual page.  For a chronological overview,

           <http://invisible-island.net/xterm/xterm.log.html>

       details changes to xterm.

       The vttest program

           <http://invisible-island.net/vttest/>

       demonstrates many of these control sequences.  The xterm(1) source distri-
       bution also contains sample scripts which exercise other features.

NOTES top

       ESC 8 (DECRC) is not able to restore the character set changed with ESC %.

BUGS top

       In 2.0.23, CSI is broken, and NUL is not ignored inside escape sequences.

       Some older kernel versions (after 2.0) interpret 8-bit control sequences.
       These "C1 controls" use codes between 128 and 159 to replace ESC [, ESC ]
       and similar two-byte control sequence initiators.  There are fragments of
       that in modern kernels (either overlooked or broken by changes to support
       UTF-8), but the implementation is incomplete and should be regarded as
       unreliable.

       Linux "private mode" sequences do not follow the rules in ECMA-48 for pri-
       vate mode control sequences.  In particular, those ending with ] do not use
       a standard terminating character.  The OSC (set palette) sequence is a
       greater problem, since xterm(1) may interpret this as a control sequence
       which requires a string terminator (ST).  Unlike the setterm(1) sequences
       which will be ignored (since they are invalid control sequences), the pal-
       ette sequence will make xterm(1) appear to hang (though pressing the
       return-key will fix that).  To accommodate applications which have been
       hardcoded to use Linux control sequences, set the xterm(1) resource broken-
       LinuxOSC to true.

       An older version of this document implied that Linux recognizes the ECMA-48
       control sequence for invisible text.  It is ignored.

SEE ALSO top

       console(4), console_ioctl(4), charsets(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                    CONSOLE_CODES(4)


console_ioctl(4) - Linux manual page

NAME | DESCRIPTION | RETURN VALUE | ERRORS | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CONSOLE_IOCTL(4)             Linux Programmer's Manual            CONSOLE_IOCTL(4)

NAME top

       console_ioctl - ioctl's for console terminal and virtual consoles

DESCRIPTION top

       The following Linux-specific ioctl(2) requests are supported.  Each
       requires a third argument, assumed here to be argp.

       KDGETLED
              Get state of LEDs.  argp points to a char.  The lower three bits of
              *argp are set to the state of the LEDs, as follows:

                  LED_CAP       0x04   caps lock led
                  LEC_NUM       0x02   num lock led
                  LED_SCR       0x01   scroll lock led

       KDSETLED
              Set the LEDs.  The LEDs are set to correspond to the lower three
              bits of argp.  However, if a higher order bit is set, the LEDs
              revert to normal: displaying the state of the keyboard functions of
              caps lock, num lock, and scroll lock.

       Before 1.1.54, the LEDs just reflected the state of the corresponding
       keyboard flags, and KDGETLED/KDSETLED would also change the keyboard flags.
       Since 1.1.54 the leds can be made to display arbitrary information, but by
       default they display the keyboard flags.  The following two ioctl's are
       used to access the keyboard flags.

       KDGKBLED
              Get keyboard flags CapsLock, NumLock, ScrollLock (not lights).  argp
              points to a char which is set to the flag state.  The low order
              three bits (mask 0x7) get the current flag state, and the low order
              bits of the next nibble (mask 0x70) get the default flag state.
              (Since 1.1.54.)

       KDSKBLED
              Set keyboard flags CapsLock, NumLock, ScrollLock (not lights).  argp
              has the desired flag state.  The low order three bits (mask 0x7)
              have the flag state, and the low order bits of the next nibble (mask
              0x70) have the default flag state.  (Since 1.1.54.)

       KDGKBTYPE
              Get keyboard type.  This returns the value KB_101, defined as 0x02.

       KDADDIO
              Add I/O port as valid.  Equivalent to ioperm(arg,1,1).

       KDDELIO
              Delete I/O port as valid.  Equivalent to ioperm(arg,1,0).

       KDENABIO
              Enable I/O to video board.  Equivalent to ioperm(0x3b4,
              0x3df-0x3b4+1, 1).

       KDDISABIO
              Disable I/O to video board.  Equivalent to ioperm(0x3b4,
              0x3df-0x3b4+1, 0).

       KDSETMODE
              Set text/graphics mode.  argp is one of these:

                  KD_TEXT       0x00
                  KD_GRAPHICS   0x01

       KDGETMODE
              Get text/graphics mode.  argp points to a long which is set to one
              of the above values.

       KDMKTONE
              Generate tone of specified length.  The lower 16 bits of argp
              specify the period in clock cycles, and the upper 16 bits give the
              duration in msec.  If the duration is zero, the sound is turned off.
              Control returns immediately.  For example, argp = (125<<16) + 0x637
              would specify the beep normally associated with a ctrl-G.  (Thus
              since 0.99pl1; broken in 2.1.49-50.)

       KIOCSOUND
              Start or stop sound generation.  The lower 16 bits of argp specify
              the period in clock cycles (that is, argp = 1193180/frequency).
              argp = 0 turns sound off.  In either case, control returns
              immediately.

       GIO_CMAP
              Get the current default color map from kernel.  argp points to a
              48-byte array.  (Since 1.3.3.)

       PIO_CMAP
              Change the default text-mode color map.  argp points to a 48-byte
              array which contains, in order, the Red, Green, and Blue values for
              the 16 available screen colors: 0 is off, and 255 is full intensity.
              The default colors are, in order: black, dark red, dark green,
              brown, dark blue, dark purple, dark cyan, light grey, dark grey,
              bright red, bright green, yellow, bright blue, bright purple, bright
              cyan and white.  (Since 1.3.3.)

       GIO_FONT
              Gets 256-character screen font in expanded form.  argp points to an
              8192 byte array.  Fails with error code EINVAL if the currently
              loaded font is a 512-character font, or if the console is not in
              text mode.

       GIO_FONTX
              Gets screen font and associated information.  argp points to a
              struct consolefontdesc (see PIO_FONTX).  On call, the charcount
              field should be set to the maximum number of characters that would
              fit in the buffer pointed to by chardata.  On return, the charcount
              and charheight are filled with the respective data for the currently
              loaded font, and the chardata array contains the font data if the
              initial value of charcount indicated enough space was available;
              otherwise the buffer is untouched and errno is set to ENOMEM.
              (Since 1.3.1.)

       PIO_FONT
              Sets 256-character screen font.  Load font into the EGA/VGA
              character generator.  argp points to a 8192 byte map, with 32 bytes
              per character.  Only first N of them are used for an 8xN font (0 < N
              <= 32).  This call also invalidates the Unicode mapping.

       PIO_FONTX
              Sets screen font and associated rendering information.  argp points
              to a

                  struct consolefontdesc {
                      unsigned short charcount;  /* characters in font
                                                    (256 or 512) */
                      unsigned short charheight; /* scan lines per
                                                    character (1-32) */
                      char          *chardata;   /* font data in
                                                    expanded form */
                  };

              If necessary, the screen will be appropriately resized, and SIGWINCH
              sent to the appropriate processes.  This call also invalidates the
              Unicode mapping.  (Since 1.3.1.)

       PIO_FONTRESET
              Resets the screen font, size and Unicode mapping to the bootup
              defaults.  argp is unused, but should be set to NULL to ensure
              compatibility with future versions of Linux.  (Since 1.3.28.)

       GIO_SCRNMAP
              Get screen mapping from kernel.  argp points to an area of size
              E_TABSZ, which is loaded with the font positions used to display
              each character.  This call is likely to return useless information
              if the currently loaded font is more than 256 characters.

       GIO_UNISCRNMAP
              Get full Unicode screen mapping from kernel.  argp points to an area
              of size E_TABSZ*sizeof(unsigned short), which is loaded with the
              Unicodes each character represent.  A special set of Unicodes,
              starting at U+F000, are used to represent "direct to font" mappings.
              (Since 1.3.1.)

       PIO_SCRNMAP
              Loads the "user definable" (fourth) table in the kernel which maps
              bytes into console screen symbols.  argp points to an area of size
              E_TABSZ.

       PIO_UNISCRNMAP
              Loads the "user definable" (fourth) table in the kernel which maps
              bytes into Unicodes, which are then translated into screen symbols
              according to the currently loaded Unicode-to-font map.  Special
              Unicodes starting at U+F000 can be used to map directly to the font
              symbols.  (Since 1.3.1.)

       GIO_UNIMAP
              Get Unicode-to-font mapping from kernel.  argp points to a

                  struct unimapdesc {
                      unsigned short  entry_ct;
                      struct unipair *entries;
                  };

              where entries points to an array of

                  struct unipair {
                      unsigned short unicode;
                      unsigned short fontpos;
                  };

              (Since 1.1.92.)

       PIO_UNIMAP
              Put unicode-to-font mapping in kernel.
                  argp points to a struct unimapdesc.  (Since 1.1.92)

       PIO_UNIMAPCLR
              Clear table, possibly advise hash algorithm.  argp points to a

                  struct unimapinit {
                      unsigned short advised_hashsize;  /* 0 if no opinion */
                      unsigned short advised_hashstep;  /* 0 if no opinion */
                      unsigned short advised_hashlevel; /* 0 if no opinion */
                  };

              (Since 1.1.92.)

       KDGKBMODE
              Gets current keyboard mode.  argp points to a long which is set to
              one of these:

                  K_RAW         0x00
                  K_XLATE       0x01
                  K_MEDIUMRAW   0x02
                  K_UNICODE     0x03

       KDSKBMODE
              Sets current keyboard mode.  argp is a long equal to one of the
              above values.

       KDGKBMETA
              Gets meta key handling mode.  argp points to a long which is set to
              one of these:

                  K_METABIT     0x03   set high order bit
                  K_ESCPREFIX   0x04   escape prefix

       KDSKBMETA
              Sets meta key handling mode.  argp is a long equal to one of the
              above values.

       KDGKBENT
              Gets one entry in key translation table (keycode to action code).
              argp points to a

                  struct kbentry {
                      unsigned char  kb_table;
                      unsigned char  kb_index;
                      unsigned short kb_value;
                  };

              with the first two members filled in: kb_table selects the key table
              (0 <= kb_table < MAX_NR_KEYMAPS), and kb_index is the keycode (0 <=
              kb_index < NR_KEYS).  kb_value is set to the corresponding action
              code, or K_HOLE if there is no such key, or K_NOSUCHMAP if kb_table
              is invalid.

       KDSKBENT
              Sets one entry in translation table.  argp points to a struct
              kbentry.

       KDGKBSENT
              Gets one function key string.  argp points to a

                  struct kbsentry {
                      unsigned char kb_func;
                      unsigned char kb_string[512];
                  };

              kb_string is set to the (null-terminated) string corresponding to
              the kb_functh function key action code.

       KDSKBSENT
              Sets one function key string entry.  argp points to a struct
              kbsentry.

       KDGKBDIACR
              Read kernel accent table.  argp points to a

                  struct kbdiacrs {
                      unsigned int   kb_cnt;
                      struct kbdiacr kbdiacr[256];
                  };

              where kb_cnt is the number of entries in the array, each of which is
              a

                  struct kbdiacr {
                      unsigned char diacr;
                      unsigned char base;
                      unsigned char result;
                  };

       KDGETKEYCODE
              Read kernel keycode table entry (scan code to keycode).  argp points
              to a

                  struct kbkeycode {
                      unsigned int scancode;
                      unsigned int keycode;
                  };

              keycode is set to correspond to the given scancode.  (89 <= scancode
              <= 255 only.  For 1 <= scancode <= 88, keycode==scancode.)  (Since
              1.1.63.)

       KDSETKEYCODE
              Write kernel keycode table entry.  argp points to a struct
              kbkeycode.  (Since 1.1.63.)

       KDSIGACCEPT
              The calling process indicates its willingness to accept the signal
              argp when it is generated by pressing an appropriate key
              combination.  (1 <= argp <= NSIG).  (See spawn_console() in
              linux/drivers/char/keyboard.c.)

       VT_OPENQRY
              Returns the first available (non-opened) console.  argp points to an
              int which is set to the number of the vt (1 <= *argp <=
              MAX_NR_CONSOLES).

       VT_GETMODE
              Get mode of active vt.  argp points to a

                  struct vt_mode {
                      char  mode;    /* vt mode */
                      char  waitv;   /* if set, hang on writes if not active */
                      short relsig;  /* signal to raise on release req */
                      short acqsig;  /* signal to raise on acquisition */
                      short frsig;   /* unused (set to 0) */
                  };

              which is set to the mode of the active vt.  mode is set to one of
              these values:

                  VT_AUTO       auto vt switching
                  VT_PROCESS    process controls switching
                  VT_ACKACQ     acknowledge switch

       VT_SETMODE
              Set mode of active vt.  argp points to a struct vt_mode.

       VT_GETSTATE
              Get global vt state info.  argp points to a

                  struct vt_stat {
                      unsigned short v_active;  /* active vt */
                      unsigned short v_signal;  /* signal to send */
                      unsigned short v_state;   /* vt bit mask */
                  };

              For each vt in use, the corresponding bit in the v_state member is
              set.  (Kernels 1.0 through 1.1.92.)

       VT_RELDISP
              Release a display.

       VT_ACTIVATE
              Switch to vt argp (1 <= argp <= MAX_NR_CONSOLES).

       VT_WAITACTIVE
              Wait until vt argp has been activated.

       VT_DISALLOCATE
              Deallocate the memory associated with vt argp.  (Since 1.1.54.)

       VT_RESIZE
              Set the kernel's idea of screensize.  argp points to a

                  struct vt_sizes {
                      unsigned short v_rows;       /* # rows */
                      unsigned short v_cols;       /* # columns */
                      unsigned short v_scrollsize; /* no longer used */
                  };

              Note that this does not change the videomode.  See resizecons(8).
              (Since 1.1.54.)

       VT_RESIZEX
              Set the kernel's idea of various screen parameters.  argp points to
              a

                  struct vt_consize {
                      unsigned short v_rows;  /* number of rows */
                      unsigned short v_cols;  /* number of columns */
                      unsigned short v_vlin;  /* number of pixel rows
                                                 on screen */
                      unsigned short v_clin;  /* number of pixel rows
                                                 per character */
                      unsigned short v_vcol;  /* number of pixel columns
                                                 on screen */
                      unsigned short v_ccol;  /* number of pixel columns
                                                 per character */
                  };

              Any parameter may be set to zero, indicating "no change", but if
              multiple parameters are set, they must be self-consistent.  Note
              that this does not change the videomode.  See resizecons(8).  (Since
              1.3.3.)

       The action of the following ioctls depends on the first byte in the struct
       pointed to by argp, referred to here as the subcode.  These are legal only
       for the superuser or the owner of the current tty.

       TIOCLINUX, subcode=0
              Dump the screen.  Disappeared in 1.1.92.  (With kernel 1.1.92 or
              later, read from /dev/vcsN or /dev/vcsaN instead.)

       TIOCLINUX, subcode=1
              Get task information.  Disappeared in 1.1.92.

       TIOCLINUX, subcode=2
              Set selection.  argp points to a

                  struct {
                     char  subcode;
                     short xs, ys, xe, ye;
                     short sel_mode;
                  };

              xs and ys are the starting column and row.  xe and ye are the ending
              column and row.  (Upper left corner is row=column=1.)  sel_mode is 0
              for character-by-character selection, 1 for word-by-word selection,
              or 2 for line-by-line selection.  The indicated screen characters
              are highlighted and saved in the static array sel_buffer in
              devices/char/console.c.

       TIOCLINUX, subcode=3
              Paste selection.  The characters in the selection buffer are written
              to fd.

       TIOCLINUX, subcode=4
              Unblank the screen.

       TIOCLINUX, subcode=5
              Sets contents of a 256-bit look up table defining characters in a
              "word", for word-by-word selection.  (Since 1.1.32.)

       TIOCLINUX, subcode=6
              argp points to a char which is set to the value of the kernel
              variable shift_state.  (Since 1.1.32.)

       TIOCLINUX, subcode=7
              argp points to a char which is set to the value of the kernel
              variable report_mouse.  (Since 1.1.33.)

       TIOCLINUX, subcode=8
              Dump screen width and height, cursor position, and all the
              character-attribute pairs.  (Kernels 1.1.67 through 1.1.91 only.
              With kernel 1.1.92 or later, read from /dev/vcsa* instead.)

       TIOCLINUX, subcode=9
              Restore screen width and height, cursor position, and all the
              character-attribute pairs.  (Kernels 1.1.67 through 1.1.91 only.
              With kernel 1.1.92 or later, write to /dev/vcsa* instead.)

       TIOCLINUX, subcode=10
              Handles the Power Saving feature of the new generation of monitors.
              VESA screen blanking mode is set to argp[1], which governs what
              screen blanking does:

                  0: Screen blanking is disabled.

                  1: The current video adapter register settings are saved, then
              the controller is programmed to turn off the vertical
              synchronization pulses.  This puts the monitor into "standby" mode.
              If your monitor has an Off_Mode timer, then it will eventually power
              down by itself.

                  2: The current settings are saved, then both the vertical and
              horizontal synchronization pulses are turned off.  This puts the
              monitor into "off" mode.  If your monitor has no Off_Mode timer, or
              if you want your monitor to power down immediately when the
              blank_timer times out, then you choose this option.  (Caution:
              Powering down frequently will damage the monitor.)

              (Since 1.1.76.)

RETURN VALUE top

       On success, 0 is returned.  On error -1 is returned, and errno is set.

ERRORS top

       errno may take on these values:

       EBADF  The file descriptor is invalid.

       ENOTTY The file descriptor is not associated with a character special
              device, or the specified request does not apply to it.

       EINVAL The file descriptor or argp is invalid.

       EPERM  Insufficient permission.

NOTES top

       Warning: Do not regard this man page as documentation of the Linux console
       ioctl's.  This is provided for the curious only, as an alternative to
       reading the source.  Ioctl's are undocumented Linux internals, liable to be
       changed without warning.  (And indeed, this page more or less describes the
       situation as of kernel version 1.1.94; there are many minor and not-so-
       minor differences with earlier versions.)

       Very often, ioctl's are introduced for communication between the kernel and
       one particular well-known program (fdisk, hdparm, setserial, tunelp,
       loadkeys, selection, setfont, etc.), and their behavior will be changed
       when required by this particular program.

       Programs using these ioctl's will not be portable to other versions of
       UNIX, will not work on older versions of Linux, and will not work on future
       versions of Linux.

       Use POSIX functions.

SEE ALSO top

       dumpkeys(1), kbd_mode(1), loadkeys(1), mknod(1), setleds(1),
       setmetamode(1), execve(2), fcntl(2), ioperm(2), termios(3), console(4),
       console_codes(4), mt(4), sd(4), tty(4), tty_ioctl(4), ttyS(4), vcs(4),
       vcsa(4), charsets(7), mapscrn(8), resizecons(8), setfont(8)

       /usr/include/linux/kd.h, /usr/include/linux/vt.h

COLOPHON top

       This page is part of release 3.45 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                               2009-02-28                    CONSOLE_IOCTL(4)


copysign(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

COPYSIGN(3)                  Linux Programmer's Manual                 COPYSIGN(3)

NAME top

       copysign, copysignf, copysignl - copy sign of a number

SYNOPSIS top

       #include <math.h>

       double copysign(double x, double y);
       float copysignf(float x, float y);
       long double copysignl(long double x, long double y);

       Link with -lm.

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

       copysign(), copysignf(), copysignl():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The copysign() functions return a value whose absolute value matches that
       of x, but whose sign bit matches that of y.

       For example, copysign(42.0, -1.0) and copysign(-42.0, -1.0) both return
       -42.0.

RETURN VALUE top

       On success, these functions return a value whose magnitude is taken from x
       and whose sign is taken from y.

       If x is a NaN, a NaN with the sign bit of y is returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  This function is defined in IEC 559 (and the appendix
       with recommended functions in IEEE 754/IEEE 854).

NOTES top

       On architectures where the floating-point formats are not IEEE 754
       compliant, the copysign() functions may treat a negative zero as positive.

SEE ALSO top

       signbit(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-25                         COPYSIGN(3)


core(5) - Linux manual page

NAME | DESCRIPTION | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CORE(5)                      Linux Programmer's Manual                     CORE(5)

NAME top

       core - core dump file

DESCRIPTION top

       The default action of certain signals is to cause a process to terminate
       and produce a core dump file, a disk file containing an image of the
       process's memory at the time of termination.  This image can be used in a
       debugger (e.g., gdb(1)) to inspect the state of the program at the time
       that it terminated.  A list of the signals which cause a process to dump
       core can be found in signal(7).

       A process can set its soft RLIMIT_CORE resource limit to place an upper
       limit on the size of the core dump file that will be produced if it
       receives a "core dump" signal; see getrlimit(2) for details.

       There are various circumstances in which a core dump file is not produced:

       *  The process does not have permission to write the core file.  (By
          default the core file is called core, and is created in the current
          working directory.  See below for details on naming.)  Writing the core
          file will fail if the directory in which it is to be created is
          nonwritable, or if a file with the same name exists and is not writable
          or is not a regular file (e.g., it is a directory or a symbolic link).

       *  A (writable, regular) file with the same name as would be used for the
          core dump already exists, but there is more than one hard link to that
          file.

       *  The file system where the core dump file would be created is full; or
          has run out of inodes; or is mounted read-only; or the user has reached
          their quota for the file system.

       *  The directory in which the core dump file is to be created does not
          exist.

       *  The RLIMIT_CORE (core file size) or RLIMIT_FSIZE (file size) resource
          limits for the process are set to zero; see getrlimit(2) and the
          documentation of the shell's ulimit command (limit in csh(1)).

       *  The binary being executed by the process does not have read permission
          enabled.

       *  The process is executing a set-user-ID (set-group-ID) program that is
          owned by a user (group) other than the real user (group) ID of the
          process.  (However, see the description of the prctl(2) PR_SET_DUMPABLE
          operation, and the description of the /proc/sys/fs/suid_dumpable file in
          proc(5).)

       In addition, a core dump may exclude part of the address space of the
       process if the madvise(2) MADV_DONTDUMP flag was employed.

Naming of core dump files

       By default, a core dump file is named core, but the
       /proc/sys/kernel/core_pattern file (since Linux 2.6 and 2.4.21) can be set
       to define a template that is used to name core dump files.  The template
       can contain % specifiers which are substituted by the following values when
       a core file is created:

           %%  a single % character
           %p  PID of dumped process
           %u  (numeric) real UID of dumped process
           %g  (numeric) real GID of dumped process
           %s  number of signal causing dump
           %t  time of dump, expressed as seconds since the Epoch, 1970-01-01
               00:00:00 +0000 (UTC)
           %h  hostname (same as nodename returned by uname(2))
           %e  executable filename (without path prefix)
           %E  pathname of executable, with slashes ('/') replaced by exclamation
               marks ('!').
           %c  core file size soft resource limit of crashing process (since Linux
               2.6.24)

       A single % at the end of the template is dropped from the core filename, as
       is the combination of a % followed by any character other than those listed
       above.  All other characters in the template become a literal part of the
       core filename.  The template may include '/' characters, which are
       interpreted as delimiters for directory names.  The maximum size of the
       resulting core filename is 128 bytes (64 bytes in kernels before 2.6.19).
       The default value in this file is "core".  For backward compatibility, if
       /proc/sys/kernel/core_pattern does not include "%p" and
       /proc/sys/kernel/core_uses_pid (see below) is nonzero, then .PID will be
       appended to the core filename.

       Since version 2.4, Linux has also provided a more primitive method of
       controlling the name of the core dump file.  If the
       /proc/sys/kernel/core_uses_pid file contains the value 0, then a core dump
       file is simply named core.  If this file contains a nonzero value, then the
       core dump file includes the process ID in a name of the form core.PID.

Piping core dumps to a program

       Since kernel 2.6.19, Linux supports an alternate syntax for the
       /proc/sys/kernel/core_pattern file.  If the first character of this file is
       a pipe symbol (|), then the remainder of the line is interpreted as a
       program to be executed.  Instead of being written to a disk file, the core
       dump is given as standard input to the program.  Note the following points:

       *  The program must be specified using an absolute pathname (or a pathname
          relative to the root directory, /), and must immediately follow the '|'
          character.

       *  The process created to run the program runs as user and group root.

       *  Command-line arguments can be supplied to the program (since kernel
          2.6.24), delimited by white space (up to a total line length of 128
          bytes).

       *  The command-line arguments can include any of the % specifiers listed
          above.  For example, to pass the PID of the process that is being
          dumped, specify %p in an argument.

Controlling which mappings are written to the core dump

       Since kernel 2.6.23, the Linux-specific /proc/PID/coredump_filter file can
       be used to control which memory segments are written to the core dump file
       in the event that a core dump is performed for the process with the
       corresponding process ID.

       The value in the file is a bit mask of memory mapping types (see mmap(2)).
       If a bit is set in the mask, then memory mappings of the corresponding type
       are dumped; otherwise they are not dumped.  The bits in this file have the
       following meanings:

           bit 0  Dump anonymous private mappings.
           bit 1  Dump anonymous shared mappings.
           bit 2  Dump file-backed private mappings.
           bit 3  Dump file-backed shared mappings.
           bit 4 (since Linux 2.6.24)
                  Dump ELF headers.
           bit 5 (since Linux 2.6.28)
                  Dump private huge pages.
           bit 6 (since Linux 2.6.28)
                  Dump shared huge pages.

       By default, the following bits are set: 0, 1, 4 (if the
       CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS kernel configuration option is
       enabled), and 5.  The value of this file is displayed in hexadecimal.  (The
       default value is thus displayed as 33.)

       Memory-mapped I/O pages such as frame buffer are never dumped, and virtual
       DSO pages are always dumped, regardless of the coredump_filter value.

       A child process created via fork(2) inherits its parent's coredump_filter
       value; the coredump_filter value is preserved across an execve(2).

       It can be useful to set coredump_filter in the parent shell before running
       a program, for example:

           $ echo 0x7 > /proc/self/coredump_filter
           $ ./some_program

       This file is only provided if the kernel was built with the CONFIG_ELF_CORE
       configuration option.

NOTES top

       The gdb(1) gcore command can be used to obtain a core dump of a running
       process.

       If a multithreaded process (or, more precisely, a process that shares its
       memory with another process by being created with the CLONE_VM flag of
       clone(2)) dumps core, then the process ID is always appended to the core
       filename, unless the process ID was already included elsewhere in the
       filename via a %p specification in /proc/sys/kernel/core_pattern.  (This is
       primarily useful when employing the LinuxThreads implementation, where each
       thread of a process has a different PID.)

EXAMPLE top

       The program below can be used to demonstrate the use of the pipe syntax in
       the /proc/sys/kernel/core_pattern file.  The following shell session
       demonstrates the use of this program (compiled to create an executable
       named core_pattern_pipe_test):

           $ cc -o core_pattern_pipe_test core_pattern_pipe_test.c
           $ su
           Password:
           # echo "|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s" > \
               /proc/sys/kernel/core_pattern
           # exit
           $ sleep 100
           ^\                     # type control-backslash
           Quit (core dumped)
           $ cat core.info
           argc=5
           argc[0]=</home/mtk/core_pattern_pipe_test>
           argc[1]=<20575>
           argc[2]=<UID=1000>
           argc[3]=<GID=100>
           argc[4]=<sig=3>
           Total bytes in core dump: 282624

Program source

       /* core_pattern_pipe_test.c */

       #define _GNU_SOURCE
       #include <sys/stat.h>
       #include <fcntl.h>
       #include <limits.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define BUF_SIZE 1024

       int
       main(int argc, char *argv[])
       {
           int tot, j;
           ssize_t nread;
           char buf[BUF_SIZE];
           FILE *fp;
           char cwd[PATH_MAX];

           /* Change our current working directory to that of the
              crashing process */

           snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
           chdir(cwd);

           /* Write output to file "core.info" in that directory */

           fp = fopen("core.info", "w+");
           if (fp == NULL)
               exit(EXIT_FAILURE);

           /* Display command-line arguments given to core_pattern
              pipe program */

           fprintf(fp, "argc=%d\n", argc);
           for (j = 0; j < argc; j++)
               fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);

           /* Count bytes in standard input (the core dump) */

           tot = 0;
           while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
               tot += nread;
           fprintf(fp, "Total bytes in core dump: %d\n", tot);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       bash(1), gdb(1), getrlimit(2), mmap(2), prctl(2), sigaction(2), elf(5),
       proc(5), pthreads(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-16                             CORE(5)


cos(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

COS(3)                       Linux Programmer's Manual                      COS(3)

NAME top

       cos, cosf, cosl - cosine function

SYNOPSIS top

       #include <math.h>

       double cos(double x);
       float cosf(float x);
       long double cosl(long double x);

       Link with -lm.

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

       cosf(), cosl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The cos() function returns the cosine of x, where x is given in radians.

RETURN VALUE top

       On success, these functions return the cosine of x.

       If x is a NaN, a NaN is returned.

       If x is positive infinity or negative infinity, a domain error occurs, and
       a NaN is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity
              errno is set to EDOM (but see BUGS).  An invalid floating-point
              exception (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD.

BUGS top

       Before version 2.10, the glibc implementation did not set errno to EDOM
       when a domain error occurred.

SEE ALSO top

       acos(3), asin(3), atan(3), atan2(3), ccos(3), sin(3), sincos(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-11                              COS(3)


cosh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

COSH(3)                      Linux Programmer's Manual                     COSH(3)

NAME top

       cosh, coshf, coshl - hyperbolic cosine function

SYNOPSIS top

       #include <math.h>

       double cosh(double x);
       float coshf(float x);
       long double coshl(long double x);

       Link with -lm.

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

       coshf(), coshl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The cosh() function returns the hyperbolic cosine of x, which is defined
       mathematically as:

           cosh(x) = (exp(x) + exp(-x)) / 2

RETURN VALUE top

       On success, these functions return the hyperbolic cosine of x.

       If x is a NaN, a NaN is returned.

       If x is +0 or -0, 1 is returned.

       If x is positive infinity or negative infinity, positive infinity is
       returned.

       If the result overflows, a range error occurs, and the functions return
       +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL, respectively.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD.

BUGS top

       In glibc version 2.3.4 and earlier, an overflow floating-point
       (FE_OVERFLOW) exception is not raised when an overflow occurs.

SEE ALSO top

       acosh(3), asinh(3), atanh(3), ccos(3), sinh(3), tanh(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             COSH(3)


cp1251(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CP1251(7)                    Linux Programmer's Manual                   CP1251(7)

NAME top

       cp1251 - CP 1251 character set encoded in octal, decimal, and hexadecimal

DESCRIPTION top

       The Windows Code Pages include several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  CP 1251 encodes the characters
       used in Cyrillic scripts.  The following table displays the characters in
       CP 1251, which are printable and unlisted in the ascii(7) manual page.  The
       fourth column will only show the proper glyphs in an environment configured
       for CP 1251.

       Oct  Dec  Hex  Char  Description
       ----------------------------------------------------------------------
       200  128  80         CYRILLIC CAPITAL LETTER DJE
       201  129  81         CYRILLIC CAPITAL LETTER GJE
       202  130  82         SINGLE LOW-9 QUOTATION MARK
       203  131  83         CYRILLIC SMALL LETTER GJE
       204  132  84         DOUBLE LOW-9 QUOTATION MARK
       205  133  85         HORIZONTAL ELLIPSIS
       206  134  86         DAGGER
       207  135  87         DOUBLE DAGGER
       210  136  88         EURO SIGN
       211  137  89         PER MILLE SIGN
       212  138  8A         CYRILLIC CAPITAL LETTER LJE
       213  139  8B         SINGLE LEFT-POINTING ANGLE QUOTATION MARK
       214  140  8C         CYRILLIC CAPITAL LETTER NJE
       215  141  8D         CYRILLIC CAPITAL LETTER KJE
       216  142  8E         CYRILLIC CAPITAL LETTER TSHE
       217  143  8F         CYRILLIC CAPITAL LETTER DZHE
       220  144  90         CYRILLIC SMALL LETTER DJE
       221  145  91         LEFT SINGLE QUOTATION MARK
       222  146  92         RIGHT SINGLE QUOTATION MARK
       223  147  93         LEFT DOUBLE QUOTATION MARK
       224  148  94         RIGHT DOUBLE QUOTATION MARK
       225  149  95         BULLET
       226  150  96         EN DASH
       227  151  97         EM DASH
       230  152  98         UNDEFINED
       231  153  99         TRADE MARK SIGN
       232  154  9A         CYRILLIC SMALL LETTER LJE
       233  155  9B         SINGLE RIGHT-POINTING ANGLE QUOTATION MARK
       234  156  9C         CYRILLIC SMALL LETTER NJE
       235  157  9D         CYRILLIC SMALL LETTER KJE
       236  158  9E         CYRILLIC SMALL LETTER TSHE
       237  159  9F         CYRILLIC SMALL LETTER DZHE
       240  160  A0         NO-BREAK SPACE
       241  161  A1    ,i    CYRILLIC CAPITAL LETTER SHORT U
       242  162  A2    /c    CYRILLIC SMALL LETTER SHORT U
       243  163  A3    -L    CYRILLIC CAPITAL LETTER JE
       244  164  A4    ox    CURRENCY SIGN
       245  165  A5    =Y    CYRILLIC CAPITAL LETTER GHE WITH UPTURN
       246  166  A6    |    BROKEN BAR
       247  167  A7    S    SECTION SIGN
       250  168  A8    "    CYRILLIC CAPITAL LETTER IO
       251  169  A9   (C)   COPYRIGHT SIGN
       252  170  AA    _a    CYRILLIC CAPITAL LETTER UKRAINIAN IE
       253  171  AB    <<   LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254  172  AC    ~    NOT SIGN
       255  173  AD         SOFT HYPHEN
       256  174  AE   (R_)   REGISTERED SIGN
       257  175  AF         CYRILLIC CAPITAL LETTER YI

       260  176  B0    o    DEGREE SIGN
       261  177  B1    +-   PLUS-MINUS SIGN
       262  178  B2    2    CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I
       263  179  B3    3    CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I
       264  180  B4    '    CYRILLIC SMALL LETTER GHE WITH UPTURN
       265  181  B5    ,u    MICRO SIGN
       266  182  B6    9|   PILCROW SIGN
       267  183  B7    .    MIDDLE DOT
       270  184  B8    ,    CYRILLIC SMALL LETTER IO
       271  185  B9    1    NUMERO SIGN
       272  186  BA    _o    CYRILLIC SMALL LETTER UKRAINIAN IE
       273  187  BB    >>   RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274  188  BC   1/4   CYRILLIC SMALL LETTER JE
       275  189  BD   1/2   CYRILLIC CAPITAL LETTER DZE
       276  190  BE   3/4   CYRILLIC SMALL LETTER DZE
       277  191  BF    'c    CYRILLIC SMALL LETTER YI
       300  192  C0    `A    CYRILLIC CAPITAL LETTER A
       301  193  C1    'A    CYRILLIC CAPITAL LETTER BE
       302  194  C2    ^A    CYRILLIC CAPITAL LETTER VE
       303  195  C3    ~A    CYRILLIC CAPITAL LETTER GHE
       304  196  C4    "A    CYRILLIC CAPITAL LETTER DE
       305  197  C5    oA    CYRILLIC CAPITAL LETTER IE
       306  198  C6    AE   CYRILLIC CAPITAL LETTER ZHE
       307  199  C7    v    CYRILLIC CAPITAL LETTER ZE
       310  200  C8    `E    CYRILLIC CAPITAL LETTER I
       311  201  C9    'E    CYRILLIC CAPITAL LETTER SHORT I
       312  202  CA    ^E    CYRILLIC CAPITAL LETTER KA
       313  203  CB    "E    CYRILLIC CAPITAL LETTER EL
       314  204  CC    `I    CYRILLIC CAPITAL LETTER EM
       315  205  CD    'I    CYRILLIC CAPITAL LETTER EN
       316  206  CE    ^I    CYRILLIC CAPITAL LETTER O
       317  207  CF    "I    CYRILLIC CAPITAL LETTER PE
       320  208  D0    -D    CYRILLIC CAPITAL LETTER ER
       321  209  D1    ~N    CYRILLIC CAPITAL LETTER ES
       322  210  D2    `O    CYRILLIC CAPITAL LETTER TE
       323  211  D3    'O    CYRILLIC CAPITAL LETTER U
       324  212  D4    ^O    CYRILLIC CAPITAL LETTER EF
       325  213  D5    ~O    CYRILLIC CAPITAL LETTER HA
       326  214  D6    "O    CYRILLIC CAPITAL LETTER TSE
       327  215  D7    x    CYRILLIC CAPITAL LETTER CHE
       330  216  D8    /O    CYRILLIC CAPITAL LETTER SHA
       331  217  D9    `U    CYRILLIC CAPITAL LETTER SHCHA
       332  218  DA    'U    CYRILLIC CAPITAL LETTER HARD SIGN
       333  219  DB    ^U    CYRILLIC CAPITAL LETTER YERU
       334  220  DC    "U    CYRILLIC CAPITAL LETTER SOFT SIGN
       335  221  DD    'Y    CYRILLIC CAPITAL LETTER E
       336  222  DE    Ib    CYRILLIC CAPITAL LETTER YU
       337  223  DF    B    CYRILLIC CAPITAL LETTER YA
       340  224  E0    `a    CYRILLIC SMALL LETTER A
       341  225  E1    'a    CYRILLIC SMALL LETTER BE
       342  226  E2    ^a    CYRILLIC SMALL LETTER VE
       343  227  E3    ~a    CYRILLIC SMALL LETTER GHE
       344  228  E4    "a    CYRILLIC SMALL LETTER DE
       345  229  E5    oa    CYRILLIC SMALL LETTER IE
       346  230  E6    ae   CYRILLIC SMALL LETTER ZHE
       347  231  E7    ,c    CYRILLIC SMALL LETTER ZE
       350  232  E8    `e    CYRILLIC SMALL LETTER I
       351  233  E9    'e    CYRILLIC SMALL LETTER SHORT I
       352  234  EA    ^e    CYRILLIC SMALL LETTER KA
       353  235  EB    "e    CYRILLIC SMALL LETTER EL
       354  236  EC    `i    CYRILLIC SMALL LETTER EM
       355  237  ED    'i    CYRILLIC SMALL LETTER EN
       356  238  EE    ^i    CYRILLIC SMALL LETTER O
       357  239  EF    "i    CYRILLIC SMALL LETTER PE
       360  240  F0    `'o    CYRILLIC SMALL LETTER ER

       361  241  F1    ~n    CYRILLIC SMALL LETTER ES
       362  242  F2    `o    CYRILLIC SMALL LETTER TE
       363  243  F3    'o    CYRILLIC SMALL LETTER U
       364  244  F4    ^o    CYRILLIC SMALL LETTER EF
       365  245  F5    ~o    CYRILLIC SMALL LETTER HA
       366  246  F6    "o    CYRILLIC SMALL LETTER TSE
       367  247  F7   -:-   CYRILLIC SMALL LETTER CHE
       370  248  F8    /o    CYRILLIC SMALL LETTER SHA
       371  249  F9    `u    CYRILLIC SMALL LETTER SHCHA
       372  250  FA    'u    CYRILLIC SMALL LETTER HARD SIGN
       373  251  FB    ^u    CYRILLIC SMALL LETTER YERU
       374  252  FC    "u    CYRILLIC SMALL LETTER SOFT SIGN
       375  253  FD    'y    CYRILLIC SMALL LETTER E
       376  254  FE    pb    CYRILLIC SMALL LETTER YU
       377  255  FF    "y    CYRILLIC SMALL LETTER YA

NOTES top

       CP 1251 is also known as Windows Cyrillic.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                           CP1251(7)


cpow(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CPOW(3)                      Linux Programmer's Manual                     CPOW(3)

NAME top

       cpow, cpowf, cpowl - complex power function

SYNOPSIS top

       #include <complex.h>

       double complex cpow(double complex x, complex double z);
       float complex cpowf(float complex x, complex float z);
       long double complex cpowl(long double complex x,
                                 complex long double z);

       Link with -lm.

DESCRIPTION top

       The function calculates x raised to the power z.  (With a branch cut for x
       along the negative real axis.)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), pow(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CPOW(3)


cproj(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CPROJ(3)                     Linux Programmer's Manual                    CPROJ(3)

NAME top

       cproj, cprojf, cprojl - project into Riemann Sphere

SYNOPSIS top

       #include <complex.h>

       double complex cproj(double complex z);
       float complex cprojf(float complex z);
       long double complex cprojl(long double complex z);

       Link with -lm.

DESCRIPTION top

       This function projects a point in the plane onto the surface of a Riemann
       Sphere, the one-point compactification of the complex plane.  Each finite
       point z projects to z itself.  Every complex infinite value is projected to
       a single infinite value, namely to positive infinity on the real axis.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

NOTES top

       In glibc 2.11 and earlier, the implementation does something different (a
       stereographic projection onto a Riemann Sphere).

SEE ALSO top

       cabs(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-06-10                            CPROJ(3)


cpuid(4) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CPUID(4)                     Linux Programmer's Manual                    CPUID(4)

NAME top

       cpuid - x86 CPUID access device

DESCRIPTION top

       CPUID provides an interface for querying information about the x86 CPU.

       This device is accessed by lseek(2) or pread(2) to the appropriate CPUID
       level and reading in chunks of 16 bytes.  A larger read size means multiple
       reads of consecutive levels.

       The lower 32 bits of the file position is used as the incoming %eax, and
       the upper 32 bits of the file position as the incoming %ecx, the latter
       intended for "counting" eax levels like eax=4.

       This driver uses /dev/cpu/CPUNUM/cpuid, where CPUNUM is the minor number,
       and on an SMP box will direct the access to CPU CPUNUM as listed in
       /proc/cpuinfo.

       This file is protected so that it can only be read by the user root, or
       members of the group root.

NOTES top

       The CPUID instruction can be directly executed by a program using inline
       assembler.  However this device allows convenient access to all CPUs
       without changing process affinity.

       Most of the information in cpuid is reported by the kernel in cooked form
       either in /proc/cpuinfo or through subdirectories in
       /sys/devices/system/cpu.  Direct CPUID access through this device should
       only be used in exceptional cases.

       The cpuid driver is not auto-loaded.  On modular kernels you might need to
       use the following command to load it explicitly before use:

            $ modprobe cpuid

       There is no support for CPUID functions that require additional input
       registers.

       Very old x86 CPUs don't support CPUID.

SEE ALSO top

       Intel Corporation, Intel 64 and IA-32 Architectures Software Developer's
       Manual Volume 2A: Instruction Set Reference, A-M, 3-180 CPUID reference.

       Intel Corporation, Intel Processor Identification and the CPUID
       Instruction, Application note 485.

COLOPHON top

       This page is part of release 3.45 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                               2009-03-31                            CPUID(4)


cpuset(7) - Linux manual page

NAME | DESCRIPTION | FILES | EXTENDED CAPABILITIES | FORMATS | RULES | PERMISSIONS | WARNINGS | EXCEPTIONS | ERRORS | VERSIONS | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CPUSET(7)                    Linux Programmer's Manual                   CPUSET(7)

NAME top

       cpuset - confine processes to processor and memory node subsets

DESCRIPTION top

       The cpuset file system is a pseudo-file-system interface to the kernel
       cpuset mechanism, which is used to control the processor placement and
       memory placement of processes.  It is commonly mounted at /dev/cpuset.

       On systems with kernels compiled with built in support for cpusets, all
       processes are attached to a cpuset, and cpusets are always present.  If a
       system supports cpusets, then it will have the entry nodev cpuset in the
       file /proc/filesystems.  By mounting the cpuset file system (see the
       EXAMPLE section below), the administrator can configure the cpusets on a
       system to control the processor and memory placement of processes on that
       system.  By default, if the cpuset configuration on a system is not
       modified or if the cpuset file system is not even mounted, then the cpuset
       mechanism, though present, has no affect on the system's behavior.

       A cpuset defines a list of CPUs and memory nodes.

       The CPUs of a system include all the logical processing units on which a
       process can execute, including, if present, multiple processor cores within
       a package and Hyper-Threads within a processor core.  Memory nodes include
       all distinct banks of main memory; small and SMP systems typically have
       just one memory node that contains all the system's main memory, while NUMA
       (non-uniform memory access) systems have multiple memory nodes.

       Cpusets are represented as directories in a hierarchical pseudo-file
       system, where the top directory in the hierarchy (/dev/cpuset) represents
       the entire system (all online CPUs and memory nodes) and any cpuset that is
       the child (descendant) of another parent cpuset contains a subset of that
       parent's CPUs and memory nodes.  The directories and files representing
       cpusets have normal file-system permissions.

       Every process in the system belongs to exactly one cpuset.  A process is
       confined to only run on the CPUs in the cpuset it belongs to, and to
       allocate memory only on the memory nodes in that cpuset.  When a process
       fork(2)s, the child process is placed in the same cpuset as its parent.
       With sufficient privilege, a process may be moved from one cpuset to
       another and the allowed CPUs and memory nodes of an existing cpuset may be
       changed.

       When the system begins booting, a single cpuset is defined that includes
       all CPUs and memory nodes on the system, and all processes are in that
       cpuset.  During the boot process, or later during normal system operation,
       other cpusets may be created, as subdirectories of this top cpuset, under
       the control of the system administrator, and processes may be placed in
       these other cpusets.

       Cpusets are integrated with the sched_setaffinity(2) scheduling affinity
       mechanism and the mbind(2) and set_mempolicy(2) memory-placement mechanisms
       in the kernel.  Neither of these mechanisms let a process make use of a CPU
       or memory node that is not allowed by that process's cpuset.  If changes to
       a process's cpuset placement conflict with these other mechanisms, then
       cpuset placement is enforced even if it means overriding these other
       mechanisms.  The kernel accomplishes this overriding by silently
       restricting the CPUs and memory nodes requested by these other mechanisms
       to those allowed by the invoking process's cpuset.  This can result in
       these other calls returning an error, if for example, such a call ends up
       requesting an empty set of CPUs or memory nodes, after that request is
       restricted to the invoking process's cpuset.

       Typically, a cpuset is used to manage the CPU and memory-node confinement
       for a set of cooperating processes such as a batch scheduler job, and these
       other mechanisms are used to manage the placement of individual processes
       or memory regions within that set or job.

FILES top

       Each directory below /dev/cpuset represents a cpuset and contains a fixed
       set of pseudo-files describing the state of that cpuset.

       New cpusets are created using the mkdir(2) system call or the mkdir(1)
       command.  The properties of a cpuset, such as its flags, allowed CPUs and
       memory nodes, and attached processes, are queried and modified by reading
       or writing to the appropriate file in that cpuset's directory, as listed
       below.

       The pseudo-files in each cpuset directory are automatically created when
       the cpuset is created, as a result of the mkdir(2) invocation.  It is not
       possible to directly add or remove these pseudo-files.

       A cpuset directory that contains no child cpuset directories, and has no
       attached processes, can be removed using rmdir(2) or rmdir(1).  It is not
       necessary, or possible, to remove the pseudo-files inside the directory
       before removing it.

       The pseudo-files in each cpuset directory are small text files that may be
       read and written using traditional shell utilities such as cat(1), and
       echo(1), or from a program by using file I/O library functions or system
       calls, such as open(2), read(2), write(2), and close(2).

       The pseudo-files in a cpuset directory represent internal kernel state and
       do not have any persistent image on disk.  Each of these per-cpuset files
       is listed and described below.

       tasks  List of the process IDs (PIDs) of the processes in that cpuset.  The
              list is formatted as a series of ASCII decimal numbers, each
              followed by a newline.  A process may be added to a cpuset
              (automatically removing it from the cpuset that previously contained
              it) by writing its PID to that cpuset's tasks file (with or without
              a trailing newline.)

              Warning: only one PID may be written to the tasks file at a time.
              If a string is written that contains more than one PID, only the
              first one will be used.

       notify_on_release
              Flag (0 or 1).  If set (1), that cpuset will receive special
              handling after it is released, that is, after all processes cease
              using it (i.e., terminate or are moved to a different cpuset) and
              all child cpuset directories have been removed.  See the Notify On
              Release section, below.

       cpus   List of the physical numbers of the CPUs on which processes in that
              cpuset are allowed to execute.  See List Format below for a
              description of the format of cpus.

              The CPUs allowed to a cpuset may be changed by writing a new list to
              its cpus file.

       cpu_exclusive
              Flag (0 or 1).  If set (1), the cpuset has exclusive use of its CPUs
              (no sibling or cousin cpuset may overlap CPUs).  By default this is
              off (0).  Newly created cpusets also initially default this to off
              (0).

              Two cpusets are sibling cpusets if they share the same parent cpuset
              in the /dev/cpuset hierarchy.  Two cpusets are cousin cpusets if
              neither is the ancestor of the other.  Regardless of the
              cpu_exclusive setting, if one cpuset is the ancestor of another, and
              if both of these cpusets have nonempty cpus, then their cpus must
              overlap, because the cpus of any cpuset are always a subset of the
              cpus of its parent cpuset.

       mems   List of memory nodes on which processes in this cpuset are allowed
              to allocate memory.  See List Format below for a description of the
              format of mems.

       mem_exclusive
              Flag (0 or 1).  If set (1), the cpuset has exclusive use of its
              memory nodes (no sibling or cousin may overlap).  Also if set (1),
              the cpuset is a Hardwall cpuset (see below.)  By default this is off
              (0).  Newly created cpusets also initially default this to off (0).

              Regardless of the mem_exclusive setting, if one cpuset is the
              ancestor of another, then their memory nodes must overlap, because
              the memory nodes of any cpuset are always a subset of the memory
              nodes of that cpuset's parent cpuset.

       mem_hardwall (since Linux 2.6.26)
              Flag (0 or 1).  If set (1), the cpuset is a Hardwall cpuset (see
              below.)  Unlike mem_exclusive, there is no constraint on whether
              cpusets marked mem_hardwall may have overlapping memory nodes with
              sibling or cousin cpusets.  By default this is off (0).  Newly
              created cpusets also initially default this to off (0).

       memory_migrate (since Linux 2.6.16)
              Flag (0 or 1).  If set (1), then memory migration is enabled.  By
              default this is off (0).  See the Memory Migration section, below.

       memory_pressure (since Linux 2.6.16)
              A measure of how much memory pressure the processes in this cpuset
              are causing.  See the Memory Pressure section, below.  Unless
              memory_pressure_enabled is enabled, always has value zero (0).  This
              file is read-only.  See the WARNINGS section, below.

       memory_pressure_enabled (since Linux 2.6.16)
              Flag (0 or 1).  This file is only present in the root cpuset,
              normally /dev/cpuset.  If set (1), the memory_pressure calculations
              are enabled for all cpusets in the system.  By default this is off
              (0).  See the Memory Pressure section, below.

       memory_spread_page (since Linux 2.6.17)
              Flag (0 or 1).  If set (1), pages in the kernel page cache (file-
              system buffers) are uniformly spread across the cpuset.  By default
              this is off (0) in the top cpuset, and inherited from the parent
              cpuset in newly created cpusets.  See the Memory Spread section,
              below.

       memory_spread_slab (since Linux 2.6.17)
              Flag (0 or 1).  If set (1), the kernel slab caches for file I/O
              (directory and inode structures) are uniformly spread across the
              cpuset.  By default this is off (0) in the top cpuset, and inherited
              from the parent cpuset in newly created cpusets.  See the Memory
              Spread section, below.

       sched_load_balance (since Linux 2.6.24)
              Flag (0 or 1).  If set (1, the default) the kernel will
              automatically load balance processes in that cpuset over the allowed
              CPUs in that cpuset.  If cleared (0) the kernel will avoid load
              balancing processes in this cpuset, unless some other cpuset with
              overlapping CPUs has its sched_load_balance flag set.  See Scheduler
              Load Balancing, below, for further details.

       sched_relax_domain_level (since Linux 2.6.26)
              Integer, between -1 and a small positive value.  The
              sched_relax_domain_level controls the width of the range of CPUs
              over which the kernel scheduler performs immediate rebalancing of
              runnable tasks across CPUs.  If sched_load_balance is disabled, then
              the setting of sched_relax_domain_level does not matter, as no such
              load balancing is done.  If sched_load_balance is enabled, then the
              higher the value of the sched_relax_domain_level, the wider the
              range of CPUs over which immediate load balancing is attempted.  See
              Scheduler Relax Domain Level, below, for further details.

       In addition to the above pseudo-files in each directory below /dev/cpuset,
       each process has a pseudo-file, /proc/<pid>/cpuset, that displays the path
       of the process's cpuset directory relative to the root of the cpuset file
       system.

       Also the /proc/<pid>/status file for each process has four added lines,
       displaying the process's Cpus_allowed (on which CPUs it may be scheduled)
       and Mems_allowed (on which memory nodes it may obtain memory), in the two
       formats Mask Format and List Format (see below) as shown in the following
       example:

              Cpus_allowed:   ffffffff,ffffffff,ffffffff,ffffffff
              Cpus_allowed_list:     0-127
              Mems_allowed:   ffffffff,ffffffff
              Mems_allowed_list:     0-63

       The "allowed" fields were added in Linux 2.6.24; the "allowed_list" fields
       were added in Linux 2.6.26.

EXTENDED CAPABILITIES top

       In addition to controlling which cpus and mems a process is allowed to use,
       cpusets provide the following extended capabilities.

Exclusive Cpusets

       If a cpuset is marked cpu_exclusive or mem_exclusive, no other cpuset,
       other than a direct ancestor or descendant, may share any of the same CPUs
       or memory nodes.

       A cpuset that is mem_exclusive restricts kernel allocations for buffer
       cache pages and other internal kernel data pages commonly shared by the
       kernel across multiple users.  All cpusets, whether mem_exclusive or not,
       restrict allocations of memory for user space.  This enables configuring a
       system so that several independent jobs can share common kernel data, while
       isolating each job's user allocation in its own cpuset.  To do this,
       construct a large mem_exclusive cpuset to hold all the jobs, and construct
       child, non-mem_exclusive cpusets for each individual job.  Only a small
       amount of kernel memory, such as requests from interrupt handlers, is
       allowed to be placed on memory nodes outside even a mem_exclusive cpuset.

Hardwall

       A cpuset that has mem_exclusive or mem_hardwall set is a hardwall cpuset.
       A hardwall cpuset restricts kernel allocations for page, buffer, and other
       data commonly shared by the kernel across multiple users.  All cpusets,
       whether hardwall or not, restrict allocations of memory for user space.

       This enables configuring a system so that several independent jobs can
       share common kernel data, such as file system pages, while isolating each
       job's user allocation in its own cpuset.  To do this, construct a large
       hardwall cpuset to hold all the jobs, and construct child cpusets for each
       individual job which are not hardwall cpusets.

       Only a small amount of kernel memory, such as requests from interrupt
       handlers, is allowed to be taken outside even a hardwall cpuset.

Notify On Release

       If the notify_on_release flag is enabled (1) in a cpuset, then whenever the
       last process in the cpuset leaves (exits or attaches to some other cpuset)
       and the last child cpuset of that cpuset is removed, the kernel will run
       the command /sbin/cpuset_release_agent, supplying the pathname (relative to
       the mount point of the cpuset file system) of the abandoned cpuset.  This
       enables automatic removal of abandoned cpusets.

       The default value of notify_on_release in the root cpuset at system boot is
       disabled (0).  The default value of other cpusets at creation is the
       current value of their parent's notify_on_release setting.

       The command /sbin/cpuset_release_agent is invoked, with the name
       (/dev/cpuset relative path) of the to-be-released cpuset in argv[1].

       The usual contents of the command /sbin/cpuset_release_agent is simply the
       shell script:

           #!/bin/sh
           rmdir /dev/cpuset/$1

       As with other flag values below, this flag can be changed by writing an
       ASCII number 0 or 1 (with optional trailing newline) into the file, to
       clear or set the flag, respectively.

Memory Pressure

       The memory_pressure of a cpuset provides a simple per-cpuset running
       average of the rate that the processes in a cpuset are attempting to free
       up in-use memory on the nodes of the cpuset to satisfy additional memory
       requests.

       This enables batch managers that are monitoring jobs running in dedicated
       cpusets to efficiently detect what level of memory pressure that job is
       causing.

       This is useful both on tightly managed systems running a wide mix of
       submitted jobs, which may choose to terminate or reprioritize jobs that are
       trying to use more memory than allowed on the nodes assigned them, and with
       tightly coupled, long-running, massively parallel scientific computing jobs
       that will dramatically fail to meet required performance goals if they
       start to use more memory than allowed to them.

       This mechanism provides a very economical way for the batch manager to
       monitor a cpuset for signs of memory pressure.  It's up to the batch
       manager or other user code to decide what action to take if it detects
       signs of memory pressure.

       Unless memory pressure calculation is enabled by setting the pseudo-file
       /dev/cpuset/memory_pressure_enabled, it is not computed for any cpuset, and
       reads from any memory_pressure always return zero, as represented by the
       ASCII string "0\n".  See the WARNINGS section, below.

       A per-cpuset, running average is employed for the following reasons:

       *  Because this meter is per-cpuset rather than per-process or per virtual
          memory region, the system load imposed by a batch scheduler monitoring
          this metric is sharply reduced on large systems, because a scan of the
          tasklist can be avoided on each set of queries.

       *  Because this meter is a running average rather than an accumulating
          counter, a batch scheduler can detect memory pressure with a single
          read, instead of having to read and accumulate results for a period of
          time.

       *  Because this meter is per-cpuset rather than per-process, the batch
          scheduler can obtain the key information--memory pressure in a cpuset--
          with a single read, rather than having to query and accumulate results
          over all the (dynamically changing) set of processes in the cpuset.

       The memory_pressure of a cpuset is calculated using a per-cpuset simple
       digital filter that is kept within the kernel.  For each cpuset, this
       filter tracks the recent rate at which processes attached to that cpuset
       enter the kernel direct reclaim code.

       The kernel direct reclaim code is entered whenever a process has to satisfy
       a memory page request by first finding some other page to repurpose, due to
       lack of any readily available already free pages.  Dirty file system pages
       are repurposed by first writing them to disk.  Unmodified file system
       buffer pages are repurposed by simply dropping them, though if that page is
       needed again, it will have to be reread from disk.

       The memory_pressure file provides an integer number representing the recent
       (half-life of 10 seconds) rate of entries to the direct reclaim code caused
       by any process in the cpuset, in units of reclaims attempted per second,
       times 1000.

Memory Spread

       There are two Boolean flag files per cpuset that control where the kernel
       allocates pages for the file-system buffers and related in-kernel data
       structures.  They are called memory_spread_page and memory_spread_slab.

       If the per-cpuset Boolean flag file memory_spread_page is set, then the
       kernel will spread the file-system buffers (page cache) evenly over all the
       nodes that the faulting process is allowed to use, instead of preferring to
       put those pages on the node where the process is running.

       If the per-cpuset Boolean flag file memory_spread_slab is set, then the
       kernel will spread some file-system-related slab caches, such as those for
       inodes and directory entries, evenly over all the nodes that the faulting
       process is allowed to use, instead of preferring to put those pages on the
       node where the process is running.

       The setting of these flags does not affect the data segment (see brk(2)) or
       stack segment pages of a process.

       By default, both kinds of memory spreading are off and the kernel prefers
       to allocate memory pages on the node local to where the requesting process
       is running.  If that node is not allowed by the process's NUMA memory
       policy or cpuset configuration or if there are insufficient free memory
       pages on that node, then the kernel looks for the nearest node that is
       allowed and has sufficient free memory.

       When new cpusets are created, they inherit the memory spread settings of
       their parent.

       Setting memory spreading causes allocations for the affected page or slab
       caches to ignore the process's NUMA memory policy and be spread instead.
       However, the effect of these changes in memory placement caused by cpuset-
       specified memory spreading is hidden from the mbind(2) or set_mempolicy(2)
       calls.  These two NUMA memory policy calls always appear to behave as if no
       cpuset-specified memory spreading is in effect, even if it is.  If cpuset
       memory spreading is subsequently turned off, the NUMA memory policy most
       recently specified by these calls is automatically reapplied.

       Both memory_spread_page and memory_spread_slab are Boolean flag files.  By
       default they contain "0", meaning that the feature is off for that cpuset.
       If a "1" is written to that file, that turns the named feature on.

       Cpuset-specified memory spreading behaves similarly to what is known (in
       other contexts) as round-robin or interleave memory placement.

       Cpuset-specified memory spreading can provide substantial performance
       improvements for jobs that:

       a) need to place thread-local data on memory nodes close to the CPUs which
          are running the threads that most frequently access that data; but also

       b) need to access large file-system data sets that must to be spread across
          the several nodes in the job's cpuset in order to fit.

       Without this policy, the memory allocation across the nodes in the job's
       cpuset can become very uneven, especially for jobs that might have just a
       single thread initializing or reading in the data set.

Memory Migration

       Normally, under the default setting (disabled) of memory_migrate, once a
       page is allocated (given a physical page of main memory) then that page
       stays on whatever node it was allocated, so long as it remains allocated,
       even if the cpuset's memory-placement policy mems subsequently changes.

       When memory migration is enabled in a cpuset, if the mems setting of the
       cpuset is changed, then any memory page in use by any process in the cpuset
       that is on a memory node that is no longer allowed will be migrated to a
       memory node that is allowed.

       Furthermore, if a process is moved into a cpuset with memory_migrate
       enabled, any memory pages it uses that were on memory nodes allowed in its
       previous cpuset, but which are not allowed in its new cpuset, will be
       migrated to a memory node allowed in the new cpuset.

       The relative placement of a migrated page within the cpuset is preserved
       during these migration operations if possible.  For example, if the page
       was on the second valid node of the prior cpuset, then the page will be
       placed on the second valid node of the new cpuset, if possible.

Scheduler Load Balancing

       The kernel scheduler automatically load balances processes.  If one CPU is
       underutilized, the kernel will look for processes on other more overloaded
       CPUs and move those processes to the underutilized CPU, within the
       constraints of such placement mechanisms as cpusets and
       sched_setaffinity(2).

       The algorithmic cost of load balancing and its impact on key shared kernel
       data structures such as the process list increases more than linearly with
       the number of CPUs being balanced.  For example, it costs more to load
       balance across one large set of CPUs than it does to balance across two
       smaller sets of CPUs, each of half the size of the larger set.  (The
       precise relationship between the number of CPUs being balanced and the cost
       of load balancing depends on implementation details of the kernel process
       scheduler, which is subject to change over time, as improved kernel
       scheduler algorithms are implemented.)

       The per-cpuset flag sched_load_balance provides a mechanism to suppress
       this automatic scheduler load balancing in cases where it is not needed and
       suppressing it would have worthwhile performance benefits.

       By default, load balancing is done across all CPUs, except those marked
       isolated using the kernel boot time "isolcpus=" argument.  (See Scheduler
       Relax Domain Level, below, to change this default.)

       This default load balancing across all CPUs is not well suited to the
       following two situations:

       *  On large systems, load balancing across many CPUs is expensive.  If the
          system is managed using cpusets to place independent jobs on separate
          sets of CPUs, full load balancing is unnecessary.

       *  Systems supporting real-time on some CPUs need to minimize system
          overhead on those CPUs, including avoiding process load balancing if
          that is not needed.

       When the per-cpuset flag sched_load_balance is enabled (the default
       setting), it requests load balancing across all the CPUs in that cpuset's
       allowed CPUs, ensuring that load balancing can move a process (not
       otherwise pinned, as by sched_setaffinity(2)) from any CPU in that cpuset
       to any other.

       When the per-cpuset flag sched_load_balance is disabled, then the scheduler
       will avoid load balancing across the CPUs in that cpuset, except in so far
       as is necessary because some overlapping cpuset has sched_load_balance
       enabled.

       So, for example, if the top cpuset has the flag sched_load_balance enabled,
       then the scheduler will load balance across all CPUs, and the setting of
       the sched_load_balance flag in other cpusets has no effect, as we're
       already fully load balancing.

       Therefore in the above two situations, the flag sched_load_balance should
       be disabled in the top cpuset, and only some of the smaller, child cpusets
       would have this flag enabled.

       When doing this, you don't usually want to leave any unpinned processes in
       the top cpuset that might use nontrivial amounts of CPU, as such processes
       may be artificially constrained to some subset of CPUs, depending on the
       particulars of this flag setting in descendant cpusets.  Even if such a
       process could use spare CPU cycles in some other CPUs, the kernel scheduler
       might not consider the possibility of load balancing that process to the
       underused CPU.

       Of course, processes pinned to a particular CPU can be left in a cpuset
       that disables sched_load_balance as those processes aren't going anywhere
       else anyway.

Scheduler Relax Domain Level

       The kernel scheduler performs immediate load balancing whenever a CPU
       becomes free or another task becomes runnable.  This load balancing works
       to ensure that as many CPUs as possible are usefully employed running
       tasks.  The kernel also performs periodic load balancing off the software
       clock described in time(7).  The setting of sched_relax_domain_level only
       applies to immediate load balancing.  Regardless of the
       sched_relax_domain_level setting, periodic load balancing is attempted over
       all CPUs (unless disabled by turning off sched_load_balance.)  In any case,
       of course, tasks will only be scheduled to run on CPUs allowed by their
       cpuset, as modified by sched_setaffinity(2) system calls.

       On small systems, such as those with just a few CPUs, immediate load
       balancing is useful to improve system interactivity and to minimize
       wasteful idle CPU cycles.  But on large systems, attempting immediate load
       balancing across a large number of CPUs can be more costly than it is
       worth, depending on the particular performance characteristics of the job
       mix and the hardware.

       The exact meaning of the small integer values of sched_relax_domain_level
       will depend on internal implementation details of the kernel scheduler code
       and on the non-uniform architecture of the hardware.  Both of these will
       evolve over time and vary by system architecture and kernel version.

       As of this writing, when this capability was introduced in Linux 2.6.26, on
       certain popular architectures, the positive values of
       sched_relax_domain_level have the following meanings.

       (1) Perform immediate load balancing across Hyper-Thread siblings on the
           same core.
       (2) Perform immediate load balancing across other cores in the same
           package.
       (3) Perform immediate load balancing across other CPUs on the same node or
           blade.
       (4) Perform immediate load balancing across over several (implementation
           detail) nodes [On NUMA systems].
       (5) Perform immediate load balancing across over all CPUs in system [On
           NUMA systems].

       The sched_relax_domain_level value of zero (0) always means don't perform
       immediate load balancing, hence that load balancing is only done
       periodically, not immediately when a CPU becomes available or another task
       becomes runnable.

       The sched_relax_domain_level value of minus one (-1) always means use the
       system default value.  The system default value can vary by architecture
       and kernel version.  This system default value can be changed by kernel
       boot-time "relax_domain_level=" argument.

       In the case of multiple overlapping cpusets which have conflicting
       sched_relax_domain_level values, then the highest such value applies to all
       CPUs in any of the overlapping cpusets.  In such cases, the value minus one
       (-1) is the lowest value, overridden by any other value, and the value zero
       (0) is the next lowest value.

FORMATS top

       The following formats are used to represent sets of CPUs and memory nodes.

Mask Format

       The Mask Format is used to represent CPU and memory-node bitmasks in the
       /proc/<pid>/status file.

       This format displays each 32-bit word in hexadecimal (using ASCII
       characters "0" - "9" and "a" - "f"); words are filled with leading zeros,
       if required.  For masks longer than one word, a comma separator is used
       between words.  Words are displayed in big-endian order, which has the most
       significant bit first.  The hex digits within a word are also in big-endian
       order.

       The number of 32-bit words displayed is the minimum number needed to
       display all bits of the bitmask, based on the size of the bitmask.

       Examples of the Mask Format:

              00000001                        # just bit 0 set
              40000000,00000000,00000000      # just bit 94 set
              00000001,00000000,00000000      # just bit 64 set
              000000ff,00000000               # bits 32-39 set
              00000000,000E3862               # 1,5,6,11-13,17-19 set

       A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as:

              00000001,00000001,00010117

       The first "1" is for bit 64, the second for bit 32, the third for bit 16,
       the fourth for bit 8, the fifth for bit 4, and the "7" is for bits 2, 1,
       and 0.

List Format

       The List Format for cpus and mems is a comma-separated list of CPU or
       memory-node numbers and ranges of numbers, in ASCII decimal.

       Examples of the List Format:

              0-4,9           # bits 0, 1, 2, 3, 4, and 9 set
              0-2,7,12-14     # bits 0, 1, 2, 7, 12, 13, and 14 set

RULES top

       The following rules apply to each cpuset:

       *  Its CPUs and memory nodes must be a (possibly equal) subset of its
          parent's.

       *  It can only be marked cpu_exclusive if its parent is.

       *  It can only be marked mem_exclusive if its parent is.

       *  If it is cpu_exclusive, its CPUs may not overlap any sibling.

       *  If it is memory_exclusive, its memory nodes may not overlap any sibling.

PERMISSIONS top

       The permissions of a cpuset are determined by the permissions of the
       directories and pseudo-files in the cpuset file system, normally mounted at
       /dev/cpuset.

       For instance, a process can put itself in some other cpuset (than its
       current one) if it can write the tasks file for that cpuset.  This requires
       execute permission on the encompassing directories and write permission on
       the tasks file.

       An additional constraint is applied to requests to place some other process
       in a cpuset.  One process may not attach another to a cpuset unless it
       would have permission to send that process a signal (see kill(2)).

       A process may create a child cpuset if it can access and write the parent
       cpuset directory.  It can modify the CPUs or memory nodes in a cpuset if it
       can access that cpuset's directory (execute permissions on the each of the
       parent directories) and write the corresponding cpus or mems file.

       There is one minor difference between the manner in which these permissions
       are evaluated and the manner in which normal file-system operation
       permissions are evaluated.  The kernel interprets relative pathnames
       starting at a process's current working directory.  Even if one is
       operating on a cpuset file, relative pathnames are interpreted relative to
       the process's current working directory, not relative to the process's
       current cpuset.  The only ways that cpuset paths relative to a process's
       current cpuset can be used are if either the process's current working
       directory is its cpuset (it first did a cd or chdir(2) to its cpuset
       directory beneath /dev/cpuset, which is a bit unusual) or if some user code
       converts the relative cpuset path to a full file-system path.

       In theory, this means that user code should specify cpusets using absolute
       pathnames, which requires knowing the mount point of the cpuset file system
       (usually, but not necessarily, /dev/cpuset).  In practice, all user level
       code that this author is aware of simply assumes that if the cpuset file
       system is mounted, then it is mounted at /dev/cpuset.  Furthermore, it is
       common practice for carefully written user code to verify the presence of
       the pseudo-file /dev/cpuset/tasks in order to verify that the cpuset
       pseudo-file system is currently mounted.

WARNINGS top

Enabling memory_pressure

       By default, the per-cpuset file memory_pressure always contains zero (0).
       Unless this feature is enabled by writing "1" to the pseudo-file
       /dev/cpuset/memory_pressure_enabled, the kernel does not compute per-cpuset
       memory_pressure.

Using the echo command

       When using the echo command at the shell prompt to change the values of
       cpuset files, beware that the built-in echo command in some shells does not
       display an error message if the write(2) system call fails.  For example,
       if the command:

           echo 19 > mems

       failed because memory node 19 was not allowed (perhaps the current system
       does not have a memory node 19), then the echo command might not display
       any error.  It is better to use the /bin/echo external command to change
       cpuset file settings, as this command will display write(2) errors, as in
       the example:

           /bin/echo 19 > mems
           /bin/echo: write error: Invalid argument

EXCEPTIONS          top
Memory placement

       Not all allocations of system memory are constrained by cpusets, for the
       following reasons.

       If hot-plug functionality is used to remove all the CPUs that are currently
       assigned to a cpuset, then the kernel will automatically update the
       cpus_allowed of all processes attached to CPUs in that cpuset to allow all
       CPUs.  When memory hot-plug functionality for removing memory nodes is
       available, a similar exception is expected to apply there as well.  In
       general, the kernel prefers to violate cpuset placement, rather than
       starving a process that has had all its allowed CPUs or memory nodes taken
       offline.  User code should reconfigure cpusets to only refer to online CPUs
       and memory nodes when using hot-plug to add or remove such resources.

       A few kernel-critical, internal memory-allocation requests, marked
       GFP_ATOMIC, must be satisfied immediately.  The kernel may drop some
       request or malfunction if one of these allocations fail.  If such a request
       cannot be satisfied within the current process's cpuset, then we relax the
       cpuset, and look for memory anywhere we can find it.  It's better to
       violate the cpuset than stress the kernel.

       Allocations of memory requested by kernel drivers while processing an
       interrupt lack any relevant process context, and are not confined by
       cpusets.

Renaming cpusets

       You can use the rename(2) system call to rename cpusets.  Only simple
       renaming is supported; that is, changing the name of a cpuset directory is
       permitted, but moving a directory into a different directory is not
       permitted.

ERRORS          top
       The Linux kernel implementation of cpusets sets errno to specify the reason
       for a failed system call affecting cpusets.

       The possible errno settings and their meaning when set on a failed cpuset
       call are as listed below.

       E2BIG  Attempted a write(2) on a special cpuset file with a length larger
              than some kernel-determined upper limit on the length of such
              writes.

       EACCES Attempted to write(2) the process ID (PID) of a process to a cpuset
              tasks file when one lacks permission to move that process.

       EACCES Attempted to add, using write(2), a CPU or memory node to a cpuset,
              when that CPU or memory node was not already in its parent.

       EACCES Attempted to set, using write(2), cpu_exclusive or mem_exclusive on
              a cpuset whose parent lacks the same setting.

       EACCES Attempted to write(2) a memory_pressure file.

       EACCES Attempted to create a file in a cpuset directory.

       EBUSY  Attempted to remove, using rmdir(2), a cpuset with attached
              processes.

       EBUSY  Attempted to remove, using rmdir(2), a cpuset with child cpusets.

       EBUSY  Attempted to remove a CPU or memory node from a cpuset that is also
              in a child of that cpuset.

       EEXIST Attempted to create, using mkdir(2), a cpuset that already exists.

       EEXIST Attempted to rename(2) a cpuset to a name that already exists.

       EFAULT Attempted to read(2) or write(2) a cpuset file using a buffer that
              is outside the writing processes accessible address space.

       EINVAL Attempted to change a cpuset, using write(2), in a way that would
              violate a cpu_exclusive or mem_exclusive attribute of that cpuset or
              any of its siblings.

       EINVAL Attempted to write(2) an empty cpus or mems list to a cpuset which
              has attached processes or child cpusets.

       EINVAL Attempted to write(2) a cpus or mems list which included a range
              with the second number smaller than the first number.

       EINVAL Attempted to write(2) a cpus or mems list which included an invalid
              character in the string.

       EINVAL Attempted to write(2) a list to a cpus file that did not include any
              online CPUs.

       EINVAL Attempted to write(2) a list to a mems file that did not include any
              online memory nodes.

       EINVAL Attempted to write(2) a list to a mems file that included a node
              that held no memory.

       EIO    Attempted to write(2) a string to a cpuset tasks file that does not
              begin with an ASCII decimal integer.

       EIO    Attempted to rename(2) a cpuset into a different directory.

       ENAMETOOLONG
              Attempted to read(2) a /proc/<pid>/cpuset file for a cpuset path
              that is longer than the kernel page size.

       ENAMETOOLONG
              Attempted to create, using mkdir(2), a cpuset whose base directory
              name is longer than 255 characters.

       ENAMETOOLONG
              Attempted to create, using mkdir(2), a cpuset whose full pathname,
              including the mount point (typically "/dev/cpuset/") prefix, is
              longer than 4095 characters.

       ENODEV The cpuset was removed by another process at the same time as a
              write(2) was attempted on one of the pseudo-files in the cpuset
              directory.

       ENOENT Attempted to create, using mkdir(2), a cpuset in a parent cpuset
              that doesn't exist.

       ENOENT Attempted to access(2) or open(2) a nonexistent file in a cpuset
              directory.

       ENOMEM Insufficient memory is available within the kernel; can occur on a
              variety of system calls affecting cpusets, but only if the system is
              extremely short of memory.

       ENOSPC Attempted to write(2) the process ID (PID) of a process to a cpuset
              tasks file when the cpuset had an empty cpus or empty mems setting.

       ENOSPC Attempted to write(2) an empty cpus or mems setting to a cpuset that
              has tasks attached.

       ENOTDIR
              Attempted to rename(2) a nonexistent cpuset.

       EPERM  Attempted to remove a file from a cpuset directory.

       ERANGE Specified a cpus or mems list to the kernel which included a number
              too large for the kernel to set in its bitmasks.

       ESRCH  Attempted to write(2) the process ID (PID) of a nonexistent process
              to a cpuset tasks file.

VERSIONS          top
       Cpusets appeared in version 2.6.12 of the Linux kernel.

NOTES          top
       Despite its name, the pid parameter is actually a thread ID, and each
       thread in a threaded group can be attached to a different cpuset.  The
       value returned from a call to gettid(2) can be passed in the argument pid.

BUGS          top
       memory_pressure cpuset files can be opened for writing, creation, or
       truncation, but then the write(2) fails with errno set to EACCES, and the
       creation and truncation options on open(2) have no effect.

EXAMPLE          top
       The following examples demonstrate querying and setting cpuset options
       using shell commands.

Creating and attaching to a cpuset.

       To create a new cpuset and attach the current command shell to it, the
       steps are:

       1)  mkdir /dev/cpuset (if not already done)
       2)  mount -t cpuset none /dev/cpuset (if not already done)
       3)  Create the new cpuset using mkdir(1).
       4)  Assign CPUs and memory nodes to the new cpuset.
       5)  Attach the shell to the new cpuset.

       For example, the following sequence of commands will set up a cpuset named
       "Charlie", containing just CPUs 2 and 3, and memory node 1, and then attach
       the current shell to that cpuset.

           $ mkdir /dev/cpuset
           $ mount -t cpuset cpuset /dev/cpuset
           $ cd /dev/cpuset
           $ mkdir Charlie
           $ cd Charlie
           $ /bin/echo 2-3 > cpus
           $ /bin/echo 1 > mems
           $ /bin/echo $$ > tasks
           # The current shell is now running in cpuset Charlie
           # The next line should display '/Charlie'
           $ cat /proc/self/cpuset

Migrating a job to different memory nodes.

       To migrate a job (the set of processes attached to a cpuset) to different
       CPUs and memory nodes in the system, including moving the memory pages
       currently allocated to that job, perform the following steps.

       1)  Let's say we want to move the job in cpuset alpha (CPUs 4-7 and memory
           nodes 2-3) to a new cpuset beta (CPUs 16-19 and memory nodes 8-9).
       2)  First create the new cpuset beta.
       3)  Then allow CPUs 16-19 and memory nodes 8-9 in beta.
       4)  Then enable memory_migration in beta.
       5)  Then move each process from alpha to beta.

       The following sequence of commands accomplishes this.

           $ cd /dev/cpuset
           $ mkdir beta
           $ cd beta
           $ /bin/echo 16-19 > cpus
           $ /bin/echo 8-9 > mems
           $ /bin/echo 1 > memory_migrate
           $ while read i; do /bin/echo $i; done < ../alpha/tasks > tasks

       The above should move any processes in alpha to beta, and any memory held
       by these processes on memory nodes 2-3 to memory nodes 8-9, respectively.

       Notice that the last step of the above sequence did not do:

           $ cp ../alpha/tasks tasks

       The while loop, rather than the seemingly easier use of the cp(1) command,
       was necessary because only one process PID at a time may be written to the
       tasks file.

       The same effect (writing one PID at a time) as the while loop can be
       accomplished more efficiently, in fewer keystrokes and in syntax that works
       on any shell, but alas more obscurely, by using the -u (unbuffered) option
       of sed(1):

           $ sed -un p < ../alpha/tasks > tasks

SEE ALSO          top
       taskset(1), get_mempolicy(2), getcpu(2), mbind(2), sched_getaffinity(2),
       sched_setaffinity(2), sched_setscheduler(2), set_mempolicy(2), CPU_SET(3),
       proc(5), numa(7), migratepages(8), numactl(8)

       Documentation/cpusets.txt in the Linux kernel source tree

COLOPHON          top
       This page is part of release 3.45 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-12                           CPUSET(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


CPU_SET(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

CPU_SET(3)                   Linux Programmer's Manual                  CPU_SET(3)

NAME top

       CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, CPU_AND, CPU_OR, CPU_XOR,
       CPU_EQUAL,  CPU_ALLOC,  CPU_ALLOC_SIZE,  CPU_FREE,  CPU_SET_S,   CPU_CLR_S,
       CPU_ISSET_S,   CPU_ZERO_S,  CPU_COUNT_S,  CPU_AND_S,  CPU_OR_S,  CPU_XOR_S,
       CPU_EQUAL_S - macros for manipulating CPU sets

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sched.h>

       void CPU_ZERO(cpu_set_t *set);

       void CPU_SET(int cpu, cpu_set_t *set);
       void CPU_CLR(int cpu, cpu_set_t *set);
       int  CPU_ISSET(int cpu, cpu_set_t *set);

       int  CPU_COUNT(cpu_set_t *set);

       void CPU_AND(cpu_set_t *destset,
                    cpu_set_t *srcset1, cpu_set_t *srcset2);
       void CPU_OR(cpu_set_t *destset,
                    cpu_set_t *srcset1, cpu_set_t *srcset2);
       void CPU_XOR(cpu_set_t *destset,
                    cpu_set_t *srcset1, cpu_set_t *srcset2);

       int  CPU_EQUAL(cpu_set_t *set1, cpu_set_t *set2);

       cpu_set_t *CPU_ALLOC(int num_cpus);
       void CPU_FREE(cpu_set_t *set);
       size_t CPU_ALLOC_SIZE(int num_cpus);

       void CPU_ZERO_S(size_t setsize, cpu_set_t *set);

       void CPU_SET_S(int cpu, size_t setsize, cpu_set_t *set);
       void CPU_CLR_S(int cpu, size_t setsize, cpu_set_t *set);
       int  CPU_ISSET_S(int cpu, size_t setsize, cpu_set_t *set);

       int  CPU_COUNT_S(size_t setsize, cpu_set_t *set);

       void CPU_AND_S(size_t setsize, cpu_set_t *destset,
                    cpu_set_t *srcset1, cpu_set_t *srcset2);
       void CPU_OR_S(size_t setsize, cpu_set_t *destset,
                    cpu_set_t *srcset1, cpu_set_t *srcset2);
       void CPU_XOR_S(size_t setsize, cpu_set_t *destset,
                    cpu_set_t *srcset1, cpu_set_t *srcset2);

       int  CPU_EQUAL_S(size_t setsize, cpu_set_t *set1, cpu_set_t *set2);

DESCRIPTION top

       The cpu_set_t data structure represents a set of CPUs.  CPU sets are used
       by sched_setaffinity(2) and similar interfaces.

       The cpu_set_t data type is implemented as a bitset.  However, the data
       structure treated as considered opaque: all manipulation of CPU sets should
       be done via the macros described in this page.

       The following macros are provided to operate on the CPU set set:

       CPU_ZERO()       Clears set, so that it contains no CPUs.

       CPU_SET()        Add CPU cpu to set.

       CPU_CLR()        Remove CPU cpu from set.

       CPU_ISSET()      Test to see if CPU cpu is a member of set.

       CPU_COUNT()      Return the number of CPUs in set.

       Where a cpu argument is specified, it should not produce side effects,
       since the above macros may evaluate the argument more than once.

       The first available CPU on the system corresponds to a cpu value of 0, the
       next CPU corresponds to a cpu value of 1, and so on.  The constant
       CPU_SETSIZE (currently 1024) specifies a value one greater than the maximum
       CPU number that can be stored in cpu_set_t.

       The following macros perform logical operations on CPU sets:

       CPU_AND()        Store the intersection of the sets srcset1 and srcset2 in
                        destset (which may be one of the source sets).

       CPU_OR()         Store the union of the sets srcset1 and srcset2 in destset
                        (which may be one of the source sets).

       CPU_XOR()        Store the XOR of the sets srcset1 and srcset2 in destset
                        (which may be one of the source sets).  The XOR means the
                        set of CPUs that are in either srcset1 or srcset2, but not
                        both.

       CPU_EQUAL()      Test whether two CPU set contain exactly the same CPUs.

Dynamically sized CPU sets

       Because some applications may require the ability to dynamically size CPU
       sets (e.g., to allocate sets larger than that defined by the standard
       cpu_set_t data type), glibc nowadays provides a set of macros to support
       this.

       The following macros are used to allocate and deallocate CPU sets:

       CPU_ALLOC()      Allocate a CPU set large enough to hold CPUs in the range
                        0 to num_cpus-1.

       CPU_ALLOC_SIZE() Return the size in bytes of the CPU set that would be
                        needed to hold CPUs in the range 0 to num_cpus-1.  This
                        macro provides the value that can be used for the setsize
                        argument in the CPU_*_S() macros described below.

       CPU_FREE()       Free a CPU set previously allocated by CPU_ALLOC().

       The macros whose names end with "_S" are the analogs of the similarly named
       macros without the suffix.  These macros perform the same tasks as their
       analogs, but operate on the dynamically allocated CPU set(s) whose size is
       setsize bytes.

RETURN VALUE top

       CPU_ISSET() and CPU_ISSET_S() return nonzero if cpu is in set; otherwise,
       it returns 0.

       CPU_COUNT() and CPU_COUNT_S() return the number of CPUs in set.

       CPU_EQUAL() and CPU_EQUAL_S() return nonzero if the two CPU sets are equal;
       otherwise it returns 0.

       CPU_ALLOC() returns a pointer on success, or NULL on failure.  (Errors are
       as for malloc(3).)

       CPU_ALLOC_SIZE() returns the number of bytes required to store a CPU set of
       the specified cardinality.

       The other functions do not return a value.

VERSIONS top

       The CPU_ZERO(), CPU_SET(), CPU_CLR(), and CPU_ISSET() macros were added in
       glibc 2.3.3.

       CPU_COUNT() first appeared in glibc 2.6.

       CPU_AND(), CPU_OR(), CPU_XOR(), CPU_EQUAL(), CPU_ALLOC(), CPU_ALLOC_SIZE(),
       CPU_FREE(), CPU_ZERO_S(), CPU_SET_S(), CPU_CLR_S(), CPU_ISSET_S(),
       CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and CPU_EQUAL_S() first appeared in
       glibc 2.7.

CONFORMING TO top

       These interfaces are Linux-specific.

NOTES top

       To duplicate a CPU set, use memcpy(3).

       Since CPU sets are bitsets allocated in units of long words, the actual
       number of CPUs in a dynamically allocated CPU set will be rounded up to the
       next multiple of sizeof(unsigned long).  An application should consider the
       contents of these extra bits to be undefined.

       Notwithstanding the similarity in the names, note that the constant
       CPU_SETSIZE indicates the number of CPUs in the cpu_set_t data type (thus,
       it is effectively a count of bits in the bitset), while the setsize
       argument of the CPU_*_S() macros is a size in bytes.

       The data types for arguments and return values shown in the SYNOPSIS are
       hints what about is expected in each case.  However, since these interfaces
       are implemented as macros, the compiler won't necessarily catch all type
       errors if you violate the suggestions.

BUGS top

       On 32-bit platforms with glibc 2.8 and earlier, CPU_ALLOC() allocates twice
       as much space as is required, and CPU_ALLOC_SIZE() returns a value twice as
       large as it should.  This bug should not affect the semantics of a program,
       but does result in wasted memory and less efficient operation of the macros
       that operate on dynamically allocated CPU sets.  These bugs are fixed in
       glibc 2.9.

EXAMPLE top

       The following program demonstrates the use of some of the macros used for
       dynamically allocated CPU sets.

       #define _GNU_SOURCE
       #include <sched.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>
       #include <assert.h>

       int
       main(int argc, char *argv[])
       {
           cpu_set_t *cpusetp;
           size_t size;
           int num_cpus, cpu;

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

           num_cpus = atoi(argv[1]);

           cpusetp = CPU_ALLOC(num_cpus);
           if (cpusetp == NULL) {
               perror("CPU_ALLOC");
               exit(EXIT_FAILURE);
           }

           size = CPU_ALLOC_SIZE(num_cpus);

           CPU_ZERO_S(size, cpusetp);
           for (cpu = 0; cpu < num_cpus; cpu += 2)
               CPU_SET_S(cpu, size, cpusetp);

           printf("CPU_COUNT() of set:    %d\n", CPU_COUNT_S(size, cpusetp));

           CPU_FREE(cpusetp);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       sched_setaffinity(2), pthread_attr_setaffinity_np(3),
       pthread_setaffinity_np(3), cpuset(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-15                          CPU_SET(3)


creal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CREAL(3)                     Linux Programmer's Manual                    CREAL(3)

NAME top

       creal, crealf, creall - get real part of a complex number

SYNOPSIS top

       #include <complex.h>

       double creal(double complex z);
       float crealf(float complex z);
       long double creall(long double complex z);

       Link with -lm.

DESCRIPTION top

       The creal() function returns the real part of the complex number z.

       One has:

           z = creal(z) + I * cimag(z)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

NOTES top

       The gcc supports also __real__.  That is a GNU extension.

SEE ALSO top

       cabs(3), cimag(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CREAL(3)


open(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

OPEN(2)                      Linux Programmer's Manual                     OPEN(2)

NAME top

       open, creat - open and possibly create a file or device

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>

       int open(const char *pathname, int flags);
       int open(const char *pathname, int flags, mode_t mode);

       int creat(const char *pathname, mode_t mode);

DESCRIPTION top

       Given a pathname for a file, open() returns a file descriptor, a small,
       nonnegative integer for use in subsequent system calls (read(2), write(2),
       lseek(2), fcntl(2), etc.).  The file descriptor returned by a successful
       call will be the lowest-numbered file descriptor not currently open for the
       process.

       By default, the new file descriptor is set to remain open across an
       execve(2) (i.e., the FD_CLOEXEC file descriptor flag described in fcntl(2)
       is initially disabled; the O_CLOEXEC flag, described below, can be used to
       change this default).  The file offset is set to the beginning of the file
       (see lseek(2)).

       A call to open() creates a new open file description, an entry in the
       system-wide table of open files.  This entry records the file offset and
       the file status flags (modifiable via the fcntl(2) F_SETFL operation).  A
       file descriptor is a reference to one of these entries; this reference is
       unaffected if pathname is subsequently removed or modified to refer to a
       different file.  The new open file description is initially not shared with
       any other process, but sharing may arise via fork(2).

       The argument flags must include one of the following access modes:
       O_RDONLY, O_WRONLY, or O_RDWR.  These request opening the file read-only,
       write-only, or read/write, respectively.

       In addition, zero or more file creation flags and file status flags can be
       bitwise-or'd in flags.  The file creation flags are O_CREAT, O_EXCL,
       O_NOCTTY, and O_TRUNC.  The file status flags are all of the remaining
       flags listed below.  The distinction between these two groups of flags is
       that the file status flags can be retrieved and (in some cases) modified
       using fcntl(2).  The full list of file creation flags and file status flags
       is as follows:

       O_APPEND
              The file is opened in append mode.  Before each write(2), the file
              offset is positioned at the end of the file, as if with lseek(2).
              O_APPEND may lead to corrupted files on NFS file systems if more
              than one process appends data to a file at once.  This is because
              NFS does not support appending to a file, so the client kernel has
              to simulate it, which can't be done without a race condition.

       O_ASYNC
              Enable signal-driven I/O: generate a signal (SIGIO by default, but
              this can be changed via fcntl(2)) when input or output becomes
              possible on this file descriptor.  This feature is only available
              for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes
              and FIFOs.  See fcntl(2) for further details.

       O_CLOEXEC (Since Linux 2.6.23)
              Enable the close-on-exec flag for the new file descriptor.
              Specifying this flag permits a program to avoid additional fcntl(2)
              F_SETFD operations to set the FD_CLOEXEC flag.  Additionally, use of
              this flag is essential in some multithreaded programs since using a
              separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does
              not suffice to avoid race conditions where one thread opens a file
              descriptor at the same time as another thread does a fork(2) plus
              execve(2).

       O_CREAT
              If the file does not exist it will be created.  The owner (user ID)
              of the file is set to the effective user ID of the process.  The
              group ownership (group ID) is set either to the effective group ID
              of the process or to the group ID of the parent directory (depending
              on file system type and mount options, and the mode of the parent
              directory, see the mount options bsdgroups and sysvgroups described
              in mount(8)).

              mode specifies the permissions to use in case a new file is created.
              This argument must be supplied when O_CREAT is specified in flags;
              if O_CREAT is not specified, then mode is ignored.  The effective
              permissions are modified by the process's umask in the usual way:
              The permissions of the created file are (mode & ~umask).  Note that
              this mode only applies to future accesses of the newly created file;
              the open() call that creates a read-only file may well return a
              read/write file descriptor.

              The following symbolic constants are provided for mode:

              S_IRWXU  00700 user (file owner) has read, write and execute
                       permission

              S_IRUSR  00400 user has read permission

              S_IWUSR  00200 user has write permission

              S_IXUSR  00100 user has execute permission

              S_IRWXG  00070 group has read, write and execute permission

              S_IRGRP  00040 group has read permission

              S_IWGRP  00020 group has write permission

              S_IXGRP  00010 group has execute permission

              S_IRWXO  00007 others have read, write and execute permission

              S_IROTH  00004 others have read permission

              S_IWOTH  00002 others have write permission

              S_IXOTH  00001 others have execute permission

       O_DIRECT (Since Linux 2.4.10)
              Try to minimize cache effects of the I/O to and from this file.  In
              general this will degrade performance, but it is useful in special
              situations, such as when applications do their own caching.  File
              I/O is done directly to/from user space buffers.  The O_DIRECT flag
              on its own makes an effort to transfer data synchronously, but does
              not give the guarantees of the O_SYNC flag that data and necessary
              metadata are transferred.  To guarantee synchronous I/O, O_SYNC must
              be used in addition to O_DIRECT.  See NOTES below for further
              discussion.

              A semantically similar (but deprecated) interface for block devices
              is described in raw(8).

       O_DIRECTORY
              If pathname is not a directory, cause the open to fail.  This flag
              is Linux-specific, and was added in kernel version 2.1.126, to avoid
              denial-of-service problems if opendir(3) is called on a FIFO or tape
              device, but should not be used outside of the implementation of
              opendir(3).

       O_EXCL Ensure that this call creates the file: if this flag is specified in
              conjunction with O_CREAT, and pathname already exists, then open()
              will fail.

              When these two flags are specified, symbolic links are not followed:
              if pathname is a symbolic link, then open() fails regardless of
              where the symbolic link points to.

              In general, the behavior of O_EXCL is undefined if it is used
              without O_CREAT.  There is one exception: on Linux 2.6 and later,
              O_EXCL can be used without O_CREAT if pathname refers to a block
              device.  If the block device is in use by the system (e.g.,
              mounted), open() fails with the error EBUSY.

              On NFS, O_EXCL is only supported when using NFSv3 or later on kernel
              2.6 or later.  In NFS environments where O_EXCL support is not
              provided, programs that rely on it for performing locking tasks will
              contain a race condition.  Portable programs that want to perform
              atomic file locking using a lockfile, and need to avoid reliance on
              NFS support for O_EXCL, can create a unique file on the same file
              system (e.g., incorporating hostname and PID), and use link(2) to
              make a link to the lockfile.  If link(2) returns 0, the lock is
              successful.  Otherwise, use stat(2) on the unique file to check if
              its link count has increased to 2, in which case the lock is also
              successful.

       O_LARGEFILE
              (LFS) Allow files whose sizes cannot be represented in an off_t (but
              can be represented in an off64_t) to be opened.  The
              _LARGEFILE64_SOURCE macro must be defined (before including any
              header files) in order to obtain this definition.  Setting the
              _FILE_OFFSET_BITS feature test macro to 64 (rather than using
              O_LARGEFILE) is the preferred method of accessing large files on
              32-bit systems (see feature_test_macros(7)).

       O_NOATIME (Since Linux 2.6.8)
              Do not update the file last access time (st_atime in the inode) when
              the file is read(2).  This flag is intended for use by indexing or
              backup programs, where its use can significantly reduce the amount
              of disk activity.  This flag may not be effective on all file
              systems.  One example is NFS, where the server maintains the access
              time.

       O_NOCTTY
              If pathname refers to a terminal device--see tty(4)-- it will not
              become the process's controlling terminal even if the process does
              not have one.

       O_NOFOLLOW
              If pathname is a symbolic link, then the open fails.  This is a
              FreeBSD extension, which was added to Linux in version 2.1.126.
              Symbolic links in earlier components of the pathname will still be
              followed.

       O_NONBLOCK or O_NDELAY
              When possible, the file is opened in nonblocking mode.  Neither the
              open() nor any subsequent operations on the file descriptor which is
              returned will cause the calling process to wait.  For the handling
              of FIFOs (named pipes), see also fifo(7).  For a discussion of the
              effect of O_NONBLOCK in conjunction with mandatory file locks and
              with file leases, see fcntl(2).

       O_SYNC The file is opened for synchronous I/O.  Any write(2)s on the
              resulting file descriptor will block the calling process until the
              data has been physically written to the underlying hardware.  But
              see NOTES below.

       O_TRUNC
              If the file already exists and is a regular file and the open mode
              allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to
              length 0.  If the file is a FIFO or terminal device file, the
              O_TRUNC flag is ignored.  Otherwise the effect of O_TRUNC is
              unspecified.

       Some of these optional flags can be altered using fcntl(2) after the file
       has been opened.

       creat() is equivalent to open() with flags equal to
       O_CREAT|O_WRONLY|O_TRUNC.

RETURN VALUE top

       open() and creat() return the new file descriptor, or -1 if an error
       occurred (in which case, errno is set appropriately).

ERRORS top

       EACCES The requested access to the file is not allowed, or search
              permission is denied for one of the directories in the path prefix
              of pathname, or the file did not exist yet and write access to the
              parent directory is not allowed.  (See also path_resolution(7).)

       EEXIST pathname already exists and O_CREAT and O_EXCL were used.

       EFAULT pathname points outside your accessible address space.

       EFBIG  See EOVERFLOW.

       EINTR  While blocked waiting to complete an open of a slow device (e.g., a
              FIFO; see fifo(7)), the call was interrupted by a signal handler;
              see signal(7).

       EISDIR pathname refers to a directory and the access requested involved
              writing (that is, O_WRONLY or O_RDWR is set).

       ELOOP  Too many symbolic links were encountered in resolving pathname, or
              O_NOFOLLOW was specified but pathname was a symbolic link.

       EMFILE The process already has the maximum number of files open.

       ENAMETOOLONG
              pathname was too long.

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

       ENODEV pathname refers to a device special file and no corresponding device
              exists.  (This is a Linux kernel bug; in this situation ENXIO must
              be returned.)

       ENOENT O_CREAT is not set and the named file does not exist.  Or, a
              directory component in pathname does not exist or is a dangling
              symbolic link.

       ENOMEM Insufficient kernel memory was available.

       ENOSPC pathname was to be created but the device containing pathname has no
              room for the new file.

       ENOTDIR
              A component used as a directory in pathname is not, in fact, a
              directory, or O_DIRECTORY was specified and pathname was not a
              directory.

       ENXIO  O_NONBLOCK | O_WRONLY is set, the named file is a FIFO and no
              process has the file open for reading.  Or, the file is a device
              special file and no corresponding device exists.

       EOVERFLOW
              pathname refers to a regular file that is too large to be opened.
              The usual scenario here is that an application compiled on a 32-bit
              platform without -D_FILE_OFFSET_BITS=64 tried to open a file whose
              size exceeds (2<<31)-1 bits; see also O_LARGEFILE above.  This is
              the error specified by POSIX.1-2001; in kernels before 2.6.24, Linux
              gave the error EFBIG for this case.

       EPERM  The O_NOATIME flag was specified, but the effective user ID of the
              caller did not match the owner of the file and the caller was not
              privileged (CAP_FOWNER).

       EROFS  pathname refers to a file on a read-only file system and write
              access was requested.

       ETXTBSY
              pathname refers to an executable image which is currently being
              executed and write access was requested.

       EWOULDBLOCK
              The O_NONBLOCK flag was specified, and an incompatible lease was
              held on the file (see fcntl(2)).

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  The O_DIRECTORY, O_NOATIME, and O_NOFOLLOW
       flags are Linux-specific, and one may need to define _GNU_SOURCE (before
       including any header files) to obtain their definitions.

       The O_CLOEXEC flag is not specified in POSIX.1-2001, but is specified in
       POSIX.1-2008.

       O_DIRECT is not specified in POSIX; one has to define _GNU_SOURCE (before
       including any header files) to get its definition.

NOTES top

       Under Linux, the O_NONBLOCK flag indicates that one wants to open but does
       not necessarily have the intention to read or write.  This is typically
       used to open devices in order to get a file descriptor for use with
       ioctl(2).

       Unlike the other values that can be specified in flags, the access mode
       values O_RDONLY, O_WRONLY, and O_RDWR, do not specify individual bits.
       Rather, they define the low order two bits of flags, and are defined
       respectively as 0, 1, and 2.  In other words, the combination O_RDONLY |
       O_WRONLY is a logical error, and certainly does not have the same meaning
       as O_RDWR.  Linux reserves the special, nonstandard access mode 3 (binary
       11) in flags to mean: check for read and write permission on the file and
       return a descriptor that can't be used for reading or writing.  This
       nonstandard access mode is used by some Linux drivers to return a
       descriptor that is only to be used for device-specific ioctl(2) operations.

       The (undefined) effect of O_RDONLY | O_TRUNC varies among implementations.
       On many systems the file is actually truncated.

       There are many infelicities in the protocol underlying NFS, affecting
       amongst others O_SYNC and O_NDELAY.

       POSIX provides for three different variants of synchronized I/O,
       corresponding to the flags O_SYNC, O_DSYNC, and O_RSYNC.  Currently
       (2.6.31), Linux only implements O_SYNC, but glibc maps O_DSYNC and O_RSYNC
       to the same numerical value as O_SYNC.  Most Linux file systems don't
       actually implement the POSIX O_SYNC semantics, which require all metadata
       updates of a write to be on disk on returning to user space, but only the
       O_DSYNC semantics, which require only actual file data and metadata
       necessary to retrieve it to be on disk by the time the system call returns.

       Note that open() can open device special files, but creat() cannot create
       them; use mknod(2) instead.

       On NFS file systems with UID mapping enabled, open() may return a file
       descriptor but, for example, read(2) requests are denied with EACCES.  This
       is because the client performs open() by checking the permissions, but UID
       mapping is performed by the server upon read and write requests.

       If the file is newly created, its st_atime, st_ctime, st_mtime fields
       (respectively, time of last access, time of last status change, and time of
       last modification; see stat(2)) are set to the current time, and so are the
       st_ctime and st_mtime fields of the parent directory.  Otherwise, if the
       file is modified because of the O_TRUNC flag, its st_ctime and st_mtime
       fields are set to the current time.

O_DIRECT

       The O_DIRECT flag may impose alignment restrictions on the length and
       address of user-space buffers and the file offset of I/Os.  In Linux
       alignment restrictions vary by file system and kernel version and might be
       absent entirely.  However there is currently no file system-independent
       interface for an application to discover these restrictions for a given
       file or file system.  Some file systems provide their own interfaces for
       doing so, for example the XFS_IOC_DIOINFO operation in xfsctl(3).

       Under Linux 2.4, transfer sizes, and the alignment of the user buffer and
       the file offset must all be multiples of the logical block size of the file
       system.  Under Linux 2.6, alignment to 512-byte boundaries suffices.

       O_DIRECT I/Os should never be run concurrently with the fork(2) system
       call, if the memory buffer is a private mapping (i.e., any mapping created
       with the mmap(2) MAP_PRIVATE flag; this includes memory allocated on the
       heap and statically allocated buffers).  Any such I/Os, whether submitted
       via an asynchronous I/O interface or from another thread in the process,
       should be completed before fork(2) is called.  Failure to do so can result
       in data corruption and undefined behavior in parent and child processes.
       This restriction does not apply when the memory buffer for the O_DIRECT
       I/Os was created using shmat(2) or mmap(2) with the MAP_SHARED flag.  Nor
       does this restriction apply when the memory buffer has been advised as
       MADV_DONTFORK with madvise(2), ensuring that it will not be available to
       the child after fork(2).

       The O_DIRECT flag was introduced in SGI IRIX, where it has alignment
       restrictions similar to those of Linux 2.4.  IRIX has also a fcntl(2) call
       to query appropriate alignments, and sizes.  FreeBSD 4.x introduced a flag
       of the same name, but without alignment restrictions.

       O_DIRECT support was added under Linux in kernel version 2.4.10.  Older
       Linux kernels simply ignore this flag.  Some file systems may not implement
       the flag and open() will fail with EINVAL if it is used.

       Applications should avoid mixing O_DIRECT and normal I/O to the same file,
       and especially to overlapping byte regions in the same file.  Even when the
       file system correctly handles the coherency issues in this situation,
       overall I/O throughput is likely to be slower than using either mode alone.
       Likewise, applications should avoid mixing mmap(2) of files with direct I/O
       to the same files.

       The behaviour of O_DIRECT with NFS will differ from local file systems.
       Older kernels, or kernels configured in certain ways, may not support this
       combination.  The NFS protocol does not support passing the flag to the
       server, so O_DIRECT I/O will only bypass the page cache on the client; the
       server may still cache the I/O.  The client asks the server to make the I/O
       synchronous to preserve the synchronous semantics of O_DIRECT.  Some
       servers will perform poorly under these circumstances, especially if the
       I/O size is small.  Some servers may also be configured to lie to clients
       about the I/O having reached stable storage; this will avoid the
       performance penalty at some risk to data integrity in the event of server
       power failure.  The Linux NFS client places no alignment restrictions on
       O_DIRECT I/O.

       In summary, O_DIRECT is a potentially powerful tool that should be used
       with caution.  It is recommended that applications treat use of O_DIRECT as
       a performance option which is disabled by default.

              "The thing that has always disturbed me about O_DIRECT is that the
              whole interface is just stupid, and was probably designed by a
              deranged monkey on some serious mind-controlling substances."--Linus

BUGS top

       Currently, it is not possible to enable signal-driven I/O by specifying
       O_ASYNC when calling open(); use fcntl(2) to enable this flag.

SEE ALSO top

       chmod(2), chown(2), close(2), dup(2), fcntl(2), link(2), lseek(2),
       mknod(2), mmap(2), mount(2), openat(2), read(2), socket(2), stat(2),
       umask(2), unlink(2), write(2), fopen(3), fifo(7), path_resolution(7),
       symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-01                             OPEN(2)


create_module(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CREATE_MODULE(2)             Linux Programmer's Manual            CREATE_MODULE(2)

NAME top

       create_module - create a loadable module entry

SYNOPSIS top

       #include <linux/module.h>

       caddr_t create_module(const char *name, size_t size);

DESCRIPTION top

       Note: This system call is present only in kernels before Linux 2.6.

       create_module() attempts to create a loadable module entry and reserve the
       kernel memory that will be needed to hold the module.  This system call
       requires privilege.

RETURN VALUE top

       On success, returns the kernel address at which the module will reside.  On
       error -1 is returned and errno is set appropriately.

ERRORS top

       EEXIST A module by that name already exists.

       EFAULT name is outside the program's accessible address space.

       EINVAL The requested size is too small even for the module header
              information.

       ENOMEM The kernel could not allocate a contiguous block of memory large
              enough for the module.

       ENOSYS create_module() is not supported in this version of the kernel
              (e.g., the kernel is version 2.6 or later).

       EPERM  The caller was not privileged (did not have the CAP_SYS_MODULE
              capability).

VERSIONS top

       This system call is only present on Linux up until kernel 2.4; it was
       removed in Linux 2.6.

CONFORMING TO top

       create_module() is Linux-specific.

SEE ALSO top

       delete_module(2), init_module(2), query_module(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-18                    CREATE_MODULE(2)


credentials(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CREDENTIALS(7)               Linux Programmer's Manual              CREDENTIALS(7)

NAME top

       credentials - process identifiers

DESCRIPTION top

Process ID (PID)

       Each process has a unique nonnegative integer identifier that is assigned
       when the process is created using fork(2).  A process can obtain its PID
       using getpid(2).  A PID is represented using the type pid_t (defined in
       <sys/types.h>).

       PIDs are used in a range of system calls to identify the process affected
       by the call, for example: kill(2), ptrace(2), setpriority(2) setpgid(2),
       setsid(2), sigqueue(3), and waitpid(2).

       A process's PID is preserved across an execve(2).

Parent Process ID (PPID)

       A process's parent process ID identifies the process that created this
       process using fork(2).  A process can obtain its PPID using getppid(2).  A
       PPID is represented using the type pid_t.

       A process's PPID is preserved across an execve(2).

Process Group ID and Session ID

       Each process has a session ID and a process group ID, both represented
       using the type pid_t.  A process can obtain its session ID using getsid(2),
       and its process group ID using getpgrp(2).

       A child created by fork(2) inherits its parent's session ID and process
       group ID.  A process's session ID and process group ID are preserved across
       an execve(2).

       Sessions and process groups are abstractions devised to support shell job
       control.  A process group (sometimes called a "job") is a collection of
       processes that share the same process group ID; the shell creates a new
       process group for the process(es) used to execute single command or
       pipeline (e.g., the two processes created to execute the command "ls | wc"
       are placed in the same process group).  A process's group membership can be
       set using setpgid(2).  The process whose process ID is the same as its
       process group ID is the process group leader for that group.

       A session is a collection of processes that share the same session ID.  All
       of the members of a process group also have the same session ID (i.e., all
       of the members of a process group always belong to the same session, so
       that sessions and process groups form a strict two-level hierarchy of
       processes.)  A new session is created when a process calls setsid(2), which
       creates a new session whose session ID is the same as the PID of the
       process that called setsid(2).  The creator of the session is called the
       session leader.

User and Group Identifiers

       Each process has various associated user and groups IDs.  These IDs are
       integers, respectively represented using the types uid_t and gid_t (defined
       in <sys/types.h>).

       On Linux, each process has the following user and group identifiers:

       *  Real user ID and real group ID.  These IDs determine who owns the
          process.  A process can obtain its real user (group) ID using getuid(2)
          (getgid(2)).

       *  Effective user ID and effective group ID.  These IDs are used by the
          kernel to determine the permissions that the process will have when
          accessing shared resources such as message queues, shared memory, and
          semaphores.  On most UNIX systems, these IDs also determine the
          permissions when accessing files.  However, Linux uses the file system
          IDs described below for this task.  A process can obtain its effective
          user (group) ID using geteuid(2) (getegid(2)).

       *  Saved set-user-ID and saved set-group-ID.  These IDs are used in set-
          user-ID and set-group-ID programs to save a copy of the corresponding
          effective IDs that were set when the program was executed (see
          execve(2)).  A set-user-ID program can assume and drop privileges by
          switching its effective user ID back and forth between the values in its
          real user ID and saved set-user-ID.  This switching is done via calls to
          seteuid(2), setreuid(2), or setresuid(2).  A set-group-ID program
          performs the analogous tasks using setegid(2), setregid(2), or
          setresgid(2).  A process can obtain its saved set-user-ID (set-group-ID)
          using getresuid(2) (getresgid(2)).

       *  File system user ID and file system group ID (Linux-specific).  These
          IDs, in conjunction with the supplementary group IDs described below,
          are used to determine permissions for accessing files; see
          path_resolution(7) for details.  Whenever a process's effective user
          (group) ID is changed, the kernel also automatically changes the file
          system user (group) ID to the same value.  Consequently, the file system
          IDs normally have the same values as the corresponding effective ID, and
          the semantics for file-permission checks are thus the same on Linux as
          on other UNIX systems.  The file system IDs can be made to differ from
          the effective IDs by calling setfsuid(2) and setfsgid(2).

       *  Supplementary group IDs.  This is a set of additional group IDs that are
          used for permission checks when accessing files and other shared
          resources.  On Linux kernels before 2.6.4, a process can be a member of
          up to 32 supplementary groups; since kernel 2.6.4, a process can be a
          member of up to 65536 supplementary groups.  The call
          sysconf(_SC_NGROUPS_MAX) can be used to determine the number of
          supplementary groups of which a process may be a member.  A process can
          obtain its set of supplementary group IDs using getgroups(2), and can
          modify the set using setgroups(2).

       A child process created by fork(2) inherits copies of its parent's user and
       groups IDs.  During an execve(2), a process's real user and group ID and
       supplementary group IDs are preserved; the effective and saved set IDs may
       be changed, as described in execve(2).

       Aside from the purposes noted above, a process's user IDs are also employed
       in a number of other contexts:

       *  when determining the permissions for sending signals--see kill(2);

       *  when determining the permissions for setting process-scheduling
          parameters (nice value, real time scheduling policy and priority, CPU
          affinity, I/O priority) using setpriority(2), sched_setaffinity(2),
          sched_setscheduler(2), sched_setparam(2), and ioprio_set(2);

       *  when checking resource limits; see getrlimit(2);

       *  when checking the limit on the number of inotify instances that the
          process may create; see inotify(7).

CONFORMING TO          top
       Process IDs, parent process IDs, process group IDs, and session IDs are
       specified in POSIX.1-2001.  The real, effective, and saved set user and
       groups IDs, and the supplementary group IDs, are specified in POSIX.1-2001.
       The file system user and group IDs are a Linux extension.

NOTES          top
       The POSIX threads specification requires that credentials are shared by all
       of the threads in a process.  However, at the kernel level, Linux maintains
       separate user and group credentials for each thread.  The NPTL threading
       implementation does some work to ensure that any change to user or group
       credentials (e.g., calls to setuid(2), setresuid(2)) is carried through to
       all of the POSIX threads in a process.

SEE ALSO          top
       bash(1), csh(1), ps(1), access(2), execve(2), faccessat(2), fork(2),
       getpgrp(2), getpid(2), getppid(2), getsid(2), kill(2), killpg(2),
       setegid(2), seteuid(2), setfsgid(2), setfsuid(2), setgid(2), setgroups(2),
       setresgid(2), setresuid(2), setuid(2), waitpid(2), euidaccess(3),
       initgroups(3), tcgetpgrp(3), tcsetpgrp(3), capabilities(7),
       path_resolution(7), unix(7)

COLOPHON          top
       This page is part of release 3.45 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-06-03                      CREDENTIALS(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


crypt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

CRYPT(3)                     Linux Programmer's Manual                    CRYPT(3)

NAME top

       crypt, crypt_r - password and data encryption

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <unistd.h>

       char *crypt(const char *key, const char *salt);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <crypt.h>

       char *crypt_r(const char *key, const char *salt,
                     struct crypt_data *data);

       Link with -lcrypt.

DESCRIPTION top

       crypt() is the password encryption function.  It is based on the Data
       Encryption Standard algorithm with variations intended (among other things)
       to discourage use of hardware implementations of a key search.

       key is a user's typed password.

       salt is a two-character string chosen from the set [a-zA-Z0-9./].  This
       string is used to perturb the algorithm in one of 4096 different ways.

       By taking the lowest 7 bits of each of the first eight characters of the
       key, a 56-bit key is obtained.  This 56-bit key is used to encrypt
       repeatedly a constant string (usually a string consisting of all zeros).
       The returned value points to the encrypted password, a series of 13
       printable ASCII characters (the first two characters represent the salt
       itself).  The return value points to static data whose content is
       overwritten by each call.

       Warning: The key space consists of 2**56 equal 7.2e16 possible values.
       Exhaustive searches of this key space are possible using massively parallel
       computers.  Software, such as crack(1), is available which will search the
       portion of this key space that is generally used by humans for passwords.
       Hence, password selection should, at minimum, avoid common words and names.
       The use of a passwd(1) program that checks for crackable passwords during
       the selection process is recommended.

       The DES algorithm itself has a few quirks which make the use of the crypt()
       interface a very poor choice for anything other than password
       authentication.  If you are planning on using the crypt() interface for a
       cryptography project, don't do it: get a good book on encryption and one of
       the widely available DES libraries.

       crypt_r() is a reentrant version of crypt().  The structure pointed to by
       data is used to store result data and bookkeeping information.  Other than
       allocating it, the only thing that the caller should do with this structure
       is to set data->initialized to zero before the first call to crypt_r().

RETURN VALUE top

       On success, a pointer to the encrypted password is returned.  On error,
       NULL is returned.

ERRORS top

       ENOSYS The crypt() function was not implemented, probably because of U.S.A.
              export restrictions.

CONFORMING TO top

       crypt(): SVr4, 4.3BSD, POSIX.1-2001.  crypt_r() is a GNU extension.

NOTES top

Glibc Notes

       The glibc2 version of this function supports additional encryption
       algorithms.

       If salt is a character string starting with the characters "$id$" followed
       by a string terminated by "$":

              $id$salt$encrypted

       then instead of using the DES machine, id identifies the encryption method
       used and this then determines how the rest of the password string is
       interpreted.  The following values of id are supported:

              ID  | Method
              ---------------------------------------------------------
              1   | MD5
              2a  | Blowfish (not in mainline glibc; added in some
                  | Linux distributions)
              5   | SHA-256 (since glibc 2.7)
              6   | SHA-512 (since glibc 2.7)

       So $5$salt$encrypted is an SHA-256 encoded password and $6$salt$encrypted
       is an SHA-512 encoded one.

       "salt" stands for the up to 16 characters following "$id$" in the salt.
       The encrypted part of the password string is the actual computed password.
       The size of this string is fixed:

       MD5     | 22 characters
       SHA-256 | 43 characters
       SHA-512 | 86 characters

       The characters in "salt" and "encrypted" are drawn from the set
       [a-zA-Z0-9./].  In the MD5 and SHA implementations the entire key is
       significant (instead of only the first 8 bytes in DES).

SEE ALSO          top
       login(1), passwd(1), encrypt(3), getpass(3), passwd(5)

COLOPHON          top
       This page is part of release 3.45 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/.

                                    2011-09-15                            CRYPT(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


csin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CSIN(3)                      Linux Programmer's Manual                     CSIN(3)

NAME top

       csin, csinf, csinl - complex sine function

SYNOPSIS top

       #include <complex.h>

       double complex csin(double complex z);
       float complex csinf(float complex z);
       long double complex csinl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The complex sine function is defined as:

           csin(z) = (exp(i * z) - exp(-i * z)) / (2 * i)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), casin(3), ccos(3), ctan(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CSIN(3)


csinh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CSINH(3)                     Linux Programmer's Manual                    CSINH(3)

NAME top

       csinh, csinhf, csinhl - complex hyperbolic sine

SYNOPSIS top

       #include <complex.h>

       double complex csinh(double complex z);
       float complex csinhf(float complex z);
       long double complex csinhl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The complex hyperbolic sine function is defined as:

           csinh(z) = (exp(z)-exp(-z))/2

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), casinh(3), ccosh(3), ctanh(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CSINH(3)


csqrt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CSQRT(3)                     Linux Programmer's Manual                    CSQRT(3)

NAME top

       csqrt, csqrtf, csqrtl - complex square root

SYNOPSIS top

       #include <complex.h>

       double complex csqrt(double complex z);
       float complex csqrtf(float complex z);
       long double complex csqrtl(long double complex z);

       Link with -lm.

DESCRIPTION top

       Calculate the square root of a given complex number, with nonnegative real
       part, and with a branch cut along the negative real axis.  (That means that
       csqrt(-1+eps*I) will be close to I while csqrt(-1-eps*I) will be close to
       -I, if eps is a small positive real number.)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), cexp(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CSQRT(3)


ctan(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CTAN(3)                      Linux Programmer's Manual                     CTAN(3)

NAME top

       ctan, ctanf, ctanl - complex tangent function

SYNOPSIS top

       #include <complex.h>

       double complex ctan(double complex z);
       float complex ctanf(float complex z);
       long double complex ctanl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The complex tangent function is defined as:

           ctan(z) = csin(z) / ccos(z)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), catan(3), ccos(3), csin(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                             CTAN(3)


ctanh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

CTANH(3)                     Linux Programmer's Manual                    CTANH(3)

NAME top

       ctanh, ctanhf, ctanhl - complex hyperbolic tangent

SYNOPSIS top

       #include <complex.h>

       double complex ctanh(double complex z);
       float complex ctanhf(float complex z);
       long double complex ctanhl(long double complex z);

       Link with -lm.

DESCRIPTION top

       The complex hyperbolic tangent function is defined mathematically as:

           ctanh(z) = csinh(z) / ccosh(z)

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99.

SEE ALSO top

       cabs(3), catanh(3), ccosh(3), csinh(3), complex(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            CTANH(3)


ctermid(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

CTERMID(3)                   Linux Programmer's Manual                  CTERMID(3)

NAME top

       ctermid - get controlling terminal name

SYNOPSIS top

       #include <stdio.h>

       char *ctermid(char *s);

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

       ctermid(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       ctermid() returns a string which is the pathname for the current
       controlling terminal for this process.  If s is NULL, a static buffer is
       used, otherwise s points to a buffer used to hold the terminal pathname.
       The symbolic constant L_ctermid is the maximum number of characters in the
       returned pathname.

RETURN VALUE top

       The pointer to the pathname.

CONFORMING TO top

       Svr4, POSIX.1-2001.

BUGS top

       The path returned may not uniquely identify the controlling terminal; it
       may, for example, be /dev/tty.

       It is not assured that the program can open the terminal.

SEE ALSO top

       ttyname(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                          CTERMID(3)


getlogin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETLOGIN(3)                  Linux Programmer's Manual                 GETLOGIN(3)

NAME top

       getlogin, getlogin_r, cuserid - get username

SYNOPSIS top

       #include <unistd.h>

       char *getlogin(void);
       int getlogin_r(char *buf, size_t bufsize);

       #include <stdio.h>

       char *cuserid(char *string);

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

       getlogin_r(): _REENTRANT || _POSIX_C_SOURCE >= 199506L
       cuserid(): _XOPEN_SOURCE

DESCRIPTION top

       getlogin() returns a pointer to a string containing the name of the user
       logged in on the controlling terminal of the process, or a NULL pointer if
       this information cannot be determined.  The string is statically allocated
       and might be overwritten on subsequent calls to this function or to
       cuserid().

       getlogin_r() returns this same username in the array buf of size bufsize.

       cuserid() returns a pointer to a string containing a username associated
       with the effective user ID of the process.  If string is not a NULL
       pointer, it should be an array that can hold at least L_cuserid characters;
       the string is returned in this array.  Otherwise, a pointer to a string in
       a static area is returned.  This string is statically allocated and might
       be overwritten on subsequent calls to this function or to getlogin().

       The macro L_cuserid is an integer constant that indicates how long an array
       you might need to store a username.  L_cuserid is declared in <stdio.h>.

       These functions let your program identify positively the user who is
       running (cuserid()) or the user who logged in this session (getlogin()).
       (These can differ when set-user-ID programs are involved.)

       For most purposes, it is more useful to use the environment variable
       LOGNAME to find out who the user is.  This is more flexible precisely
       because the user can set LOGNAME arbitrarily.

RETURN VALUE top

       getlogin() returns a pointer to the username when successful, and NULL on
       failure.  getlogin_r() returns 0 when successful, and nonzero on failure.

ERRORS top

       POSIX specifies

       EMFILE The calling process already has the maximum allowed number of open
              files.

       ENFILE The system already has the maximum allowed number of open files.

       ENXIO  The calling process has no controlling tty.

       ERANGE (getlogin_r) The length of the username, including the terminating
              null byte, is larger than bufsize.

       Linux/glibc also has

       ENOENT There was no corresponding entry in the utmp-file.

       ENOMEM Insufficient memory to allocate passwd structure.

       ENOTTY Standard input didn't refer to a terminal.  (See BUGS.)

FILES top

       /etc/passwd
              password database file

       /var/run/utmp
              (traditionally /etc/utmp; some libc versions used /var/adm/utmp)

CONFORMING TO top

       getlogin() and getlogin_r() specified in POSIX.1-2001.

       System V has a cuserid() function which uses the real user ID rather than
       the effective user ID.  The cuserid() function was included in the 1988
       version of POSIX, but removed from the 1990 version.  It was present in
       SUSv2, but removed in POSIX.1-2001.

       OpenBSD has getlogin() and setlogin(), and a username associated with a
       session, even if it has no controlling tty.

BUGS top

       Unfortunately, it is often rather easy to fool getlogin().  Sometimes it
       does not work at all, because some program messed up the utmp file.  Often,
       it gives only the first 8 characters of the login name.  The user currently
       logged in on the controlling tty of our program need not be the user who
       started it.  Avoid getlogin() for security-related purposes.

       Note that glibc does not follow the POSIX specification and uses stdin
       instead of /dev/tty.  A bug.  (Other recent systems, like SunOS 5.8 and HP-
       UX 11.11 and FreeBSD 4.8 all return the login name also when stdin is
       redirected.)

       Nobody knows precisely what cuserid() does; avoid it in portable programs.
       Or avoid it altogether: use getpwuid(geteuid()) instead, if that is what
       you meant.  Do not use cuserid().

SEE ALSO top

       geteuid(2), getuid(2), utmp(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-06-29                         GETLOGIN(3)


daemon(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DAEMON(3)                    Linux Programmer's Manual                   DAEMON(3)

NAME top

       daemon - run in the background

SYNOPSIS top

       #include <unistd.h>

       int daemon(int nochdir, int noclose);

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

       daemon(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       The daemon() function is for programs wishing to detach themselves from the
       controlling terminal and run in the background as system daemons.

       If nochdir is zero, daemon() changes the calling process's current working
       directory to the root directory ("/"); otherwise, the current working
       directory is left unchanged.

       If noclose is zero, daemon() redirects standard input, standard output and
       standard error to /dev/null; otherwise, no changes are made to these file
       descriptors.

RETURN VALUE top

       (This function forks, and if the fork(2) succeeds, the parent calls
       _exit(2), so that further errors are seen by the child only.)  On success
       daemon() returns zero.  If an error occurs, daemon() returns -1 and sets
       errno to any of the errors specified for the fork(2) and setsid(2).

CONFORMING TO top

       Not in POSIX.1-2001.  A similar function appears on the BSDs.  The daemon()
       function first appeared in 4.4BSD.

NOTES top

       The glibc implementation can also return -1 when /dev/null exists but is
       not a character device with the expected major and minor numbers.  In this
       case errno need not be set.

SEE ALSO top

       fork(2), setsid(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-12-05                           DAEMON(3)


tzset(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TZSET(3)                     Linux Programmer's Manual                    TZSET(3)

NAME top

       tzset, tzname, timezone, daylight - initialize time conversion information

SYNOPSIS top

       #include <time.h>

       void tzset (void);

       extern char *tzname[2];
       extern long timezone;
       extern int daylight;

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

       tzset(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
       tzname: _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
       timezone: _SVID_SOURCE || _XOPEN_SOURCE
       daylight: _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       The tzset() function initializes the tzname variable from the TZ
       environment variable.  This function is automatically called by the other
       time conversion functions that depend on the timezone.  In a System-V-like
       environment, it will also set the variables timezone (seconds West of UTC)
       and daylight (to 0 if this timezone does not have any daylight saving time
       rules, or to nonzero if there is a time during the year when daylight
       saving time applies).

       If the TZ variable does not appear in the environment, the tzname variable
       is initialized with the best approximation of local wall clock time, as
       specified by the tzfile(5)-format file localtime found in the system
       timezone directory (see below).  (One also often sees /etc/localtime used
       here, a symlink to the right file in the system timezone directory.)

       If the TZ variable does appear in the environment but its value is empty or
       its value cannot be interpreted using any of the formats specified below,
       Coordinated Universal Time (UTC) is used.

       The value of TZ can be one of three formats.  The first format is used when
       there is no daylight saving time in the local timezone:

              std offset

       The std string specifies the name of the timezone and must be three or more
       alphabetic characters.  The offset string immediately follows std and
       specifies the time value to be added to the local time to get Coordinated
       Universal Time (UTC).  The offset is positive if the local timezone is west
       of the Prime Meridian and negative if it is east.  The hour must be between
       0 and 24, and the minutes and seconds 0 and 59.

       The second format is used when there is daylight saving time:

              std offset dst [offset],start[/time],end[/time]

       There are no spaces in the specification.  The initial std and offset
       specify the standard timezone, as described above.  The dst string and
       offset specify the name and offset for the corresponding daylight saving
       timezone.  If the offset is omitted, it default to one hour ahead of
       standard time.

       The start field specifies when daylight saving time goes into effect and
       the end field specifies when the change is made back to standard time.
       These fields may have the following formats:

       Jn     This specifies the Julian day with n between 1 and 365.  Leap days
              are not counted.  In this format, February 29 can't be represented;
              February 28 is day 59, and March 1 is always day 60.

       n      This specifies the zero-based Julian day with n between 0 and 365.
              February 29 is counted in leap years.

       Mm.w.d This specifies day d (0 <= d <= 6) of week w (1 <= w <= 5) of month
              m (1 <= m <= 12).  Week 1 is the first week in which day d occurs
              and week 5 is the last week in which day d occurs.  Day 0 is a
              Sunday.

       The time fields specify when, in the local time currently in effect, the
       change to the other time occurs.  If omitted, the default is 02:00:00.

       Here is an example for New Zealand, where the standard time (NZST) is 12
       hours ahead of UTC, and daylight saving time (NZDT), 13 hours ahead of UTC,
       runs from the first Sunday in October to the third Sunday in March, and the
       changeovers happen at the default time of 02:00:00:

           TZ="NZST-12:00:00NZDT-13:00:00,M10.1.0,M3.3.0"

       The third format specifies that the timezone information should be read
       from a file:

              :[filespec]

       If the file specification filespec is omitted, the timezone information is
       read from the file localtime in the system timezone directory, which
       nowadays usually is /usr/share/zoneinfo.  This file is in tzfile(5) format.
       If filespec is given, it specifies another tzfile(5)-format file to read
       the timezone information from.  If filespec does not begin with a '/', the
       file specification is relative to the system timezone directory.

       Here's an example, once more for New Zealand:

           TZ=":Pacific/Auckland"

FILES top

       The system timezone directory used depends on the (g)libc version.  Libc4
       and libc5 use /usr/lib/zoneinfo, and, since libc-5.4.6, when this doesn't
       work, will try /usr/share/zoneinfo.  Glibc2 will use the environment
       variable TZDIR, when that exists.  Its default depends on how it was
       installed, but normally is /usr/share/zoneinfo.

       This timezone directory contains the files
       localtime      local timezone file
       posixrules     rules for POSIX-style TZ's

       Often /etc/localtime is a symlink to the file localtime or to the correct
       timezone file in the system timezone directory.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD.

NOTES top

       Note that the variable daylight does not indicate that daylight saving time
       applies right now.  It used to give the number of some algorithm (see the
       variable tz_dsttime in gettimeofday(2)).  It has been obsolete for many
       years but is required by SUSv2.

       4.3BSD had a function char *timezone(zone, dst) that returned the name of
       the timezone corresponding to its first argument (minutes West of UTC).  If
       the second argument was 0, the standard name was used, otherwise the
       daylight saving time version.

SEE ALSO top

       date(1), gettimeofday(2), time(2), ctime(3), getenv(3), tzfile(5)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-03-25                            TZSET(3)


dbopen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

DBOPEN(3)                    Linux Programmer's Manual                   DBOPEN(3)

NAME top

       dbopen - database access methods

SYNOPSIS top

       #include <sys/types.h>
       #include <limits.h>
       #include <db.h>
       #include <fcntl.h>

       DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
                  const void *openinfo);

DESCRIPTION top

       Note well: This page documents interfaces provided in glibc up until
       version 2.1.  Since version 2.2, glibc no longer provides these interfaces.
       Probably, you are looking for the APIs provided by the libdb library
       instead.

       dbopen() is the library interface to database files.  The supported file
       formats are btree, hashed and UNIX file oriented.  The btree format is a
       representation of a sorted, balanced tree structure.  The hashed format is
       an extensible, dynamic hashing scheme.  The flat-file format is a byte
       stream file with fixed or variable length records.  The formats and file
       format specific information are described in detail in their respective
       manual pages btree(3), hash(3) and recno(3).

       dbopen() opens file for reading and/or writing.  Files never intended to be
       preserved on disk may be created by setting the file argument to NULL.

       The flags and mode arguments are as specified to the open(2) routine,
       however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR,
       O_SHLOCK, and O_TRUNC flags are meaningful.  (Note, opening a database file
       O_WRONLY is not possible.)

       The type argument is of type DBTYPE (as defined in the <db.h> include file)
       and may be set to DB_BTREE, DB_HASH, or DB_RECNO.

       The openinfo argument is a pointer to an access method specific structure
       described in the access method's manual page.  If openinfo is NULL, each
       access method will use defaults appropriate for the system and the access
       method.

       dbopen() returns a pointer to a DB structure on success and NULL on error.
       The DB structure is defined in the <db.h> include file, and contains at
       least the following fields:

           typedef struct {
               DBTYPE type;
               int (*close)(const DB *db);
               int (*del)(const DB *db, const DBT *key, unsigned int flags);
               int (*fd)(const DB *db);
               int (*get)(const DB *db, DBT *key, DBT *data,
                          unsigned int flags);
               int (*put)(const DB *db, DBT *key, const DBT *data,
                          unsigned int flags);
               int (*sync)(const DB *db, unsigned int flags);
               int (*seq)(const DB *db, DBT *key, DBT *data,
                          unsigned int flags);
           } DB;

       These elements describe a database type and a set of functions performing
       various actions.  These functions take a pointer to a structure as returned
       by dbopen(), and sometimes one or more pointers to key/data structures and
       a flag value.

       type   The type of the underlying access method (and file format).

       close  A pointer to a routine to flush any cached information to disk, free
              any allocated resources, and close the underlying file(s).  Since
              key/data pairs may be cached in memory, failing to sync the file
              with a close or sync function may result in inconsistent or lost
              information.  close routines return -1 on error (setting errno) and
              0 on success.

       del    A pointer to a routine to remove key/data pairs from the database.

              The argument flag may be set to the following value:

              R_CURSOR
                     Delete the record referenced by the cursor.  The cursor must
                     have previously been initialized.

              delete routines return -1 on error (setting errno), 0 on success,
              and 1 if the specified key was not in the file.

       fd     A pointer to a routine which returns a file descriptor
              representative of the underlying database.  A file descriptor
              referencing the same file will be returned to all processes which
              call dbopen() with the same file name.  This file descriptor may be
              safely used as an argument to the fcntl(2) and flock(2) locking
              functions.  The file descriptor is not necessarily associated with
              any of the underlying files used by the access method.  No file
              descriptor is available for in memory databases.  fd routines return
              -1 on error (setting errno), and the file descriptor on success.

       get    A pointer to a routine which is the interface for keyed retrieval
              from the database.  The address and length of the data associated
              with the specified key are returned in the structure referenced by
              data.  get routines return -1 on error (setting errno), 0 on
              success, and 1 if the key was not in the file.

       put    A pointer to a routine to store key/data pairs in the database.

              The argument flag may be set to one of the following values:

              R_CURSOR
                     Replace the key/data pair referenced by the cursor.  The
                     cursor must have previously been initialized.

              R_IAFTER
                     Append the data immediately after the data referenced by key,
                     creating a new key/data pair.  The record number of the
                     appended key/data pair is returned in the key structure.
                     (Applicable only to the DB_RECNO access method.)

              R_IBEFORE
                     Insert the data immediately before the data referenced by
                     key, creating a new key/data pair.  The record number of the
                     inserted key/data pair is returned in the key structure.
                     (Applicable only to the DB_RECNO access method.)

              R_NOOVERWRITE
                     Enter the new key/data pair only if the key does not
                     previously exist.

              R_SETCURSOR
                     Store the key/data pair, setting or initializing the position
                     of the cursor to reference it.  (Applicable only to the
                     DB_BTREE and DB_RECNO access methods.)

              R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access
              methods because it implies that the keys have an inherent order
              which does not change.

              R_IAFTER and R_IBEFORE are available only for the DB_RECNO access
              method because they each imply that the access method is able to
              create new keys.  This is only true if the keys are ordered and
              independent, record numbers for example.

              The default behavior of the put routines is to enter the new
              key/data pair, replacing any previously existing key.

              put routines return -1 on error (setting errno), 0 on success, and 1
              if the R_NOOVERWRITE flag was set and the key already exists in the
              file.

       seq    A pointer to a routine which is the interface for sequential
              retrieval from the database.  The address and length of the key are
              returned in the structure referenced by key, and the address and
              length of the data are returned in the structure referenced by data.

              Sequential key/data pair retrieval may begin at any time, and the
              position of the "cursor" is not affected by calls to the del, get,
              put, or sync routines.  Modifications to the database during a
              sequential scan will be reflected in the scan, that is, records
              inserted behind the cursor will not be returned while records
              inserted in front of the cursor will be returned.

              The flag value must be set to one of the following values:

              R_CURSOR
                     The data associated with the specified key is returned.  This
                     differs from the get routines in that it sets or initializes
                     the cursor to the location of the key as well.  (Note, for
                     the DB_BTREE access method, the returned key is not
                     necessarily an exact match for the specified key.  The
                     returned key is the smallest key greater than or equal to the
                     specified key, permitting partial key matches and range
                     searches.)

              R_FIRST
                     The first key/data pair of the database is returned, and the
                     cursor is set or initialized to reference it.

              R_LAST The last key/data pair of the database is returned, and the
                     cursor is set or initialized to reference it.  (Applicable
                     only to the DB_BTREE and DB_RECNO access methods.)

              R_NEXT Retrieve the key/data pair immediately after the cursor.  If
                     the cursor is not yet set, this is the same as the R_FIRST
                     flag.

              R_PREV Retrieve the key/data pair immediately before the cursor.  If
                     the cursor is not yet set, this is the same as the R_LAST
                     flag.  (Applicable only to the DB_BTREE and DB_RECNO access
                     methods.)

              R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO
              access methods because they each imply that the keys have an
              inherent order which does not change.

              seq routines return -1 on error (setting errno), 0 on success and 1
              if there are no key/data pairs less than or greater than the
              specified or current key.  If the DB_RECNO access method is being
              used, and if the database file is a character special file and no
              complete key/data pairs are currently available, the seq routines
              return 2.

       sync   A pointer to a routine to flush any cached information to disk.  If
              the database is in memory only, the sync routine has no effect and
              will always succeed.

              The flag value may be set to the following value:

              R_RECNOSYNC
                     If the DB_RECNO access method is being used, this flag causes
                     the sync routine to apply to the btree file which underlies
                     the recno file, not the recno file itself.  (See the bfname
                     field of the recno(3) manual page for more information.)

              sync routines return -1 on error (setting errno) and 0 on success.

Key/Data Pairs

       Access to all file types is based on key/data pairs.  Both keys and data
       are represented by the following data structure:

           typedef struct {
               void  *data;
               size_t size;
           } DBT;

       The elements of the DBT structure are defined as follows:

       data   A pointer to a byte string.

       size   The length of the byte string.

       Key and data byte strings may reference strings of essentially unlimited
       length although any two of them must fit into available memory at the same
       time.  It should be noted that the access methods provide no guarantees
       about byte string alignment.

ERRORS top

       The dbopen() routine may fail and set errno for any of the errors specified
       for the library routines open(2) and malloc(3) or the following:

       EFTYPE A file is incorrectly formatted.

       EINVAL A parameter has been specified (hash function, pad byte, etc.) that
              is incompatible with the current file specification or which is not
              meaningful for the function (for example, use of the cursor without
              prior initialization) or there is a mismatch between the version
              number of file and the software.

       The close routines may fail and set errno for any of the errors specified
       for the library routines close(2), read(2), write(2), free(3), or fsync(2).

       The del, get, put and seq routines may fail and set errno for any of the
       errors specified for the library routines read(2), write(2), free(3) or
       malloc(3).

       The fd routines will fail and set errno to ENOENT for in memory databases.

       The sync routines may fail and set errno for any of the errors specified
       for the library routine fsync(2).

BUGS top

       The typedef DBT is a mnemonic for "data base thang", and was used because
       no-one could think of a reasonable name that wasn't already used.

       The file descriptor interface is a kludge and will be deleted in a future
       version of the interface.

       None of the access methods provide any form of concurrent access, locking,
       or transactions.

SEE ALSO top

       btree(3), hash(3), mpool(3), recno(3)

       LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael
       Olson, USENIX proceedings, Winter 1992.

COLOPHON top

       This page is part of release 3.45 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/.

4.4 Berkeley Distribution           2012-05-04                           DBOPEN(3)


ddp(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

DDP(7)                       Linux Programmer's Manual                      DDP(7)

NAME top

       ddp - Linux AppleTalk protocol implementation

SYNOPSIS top

       #include <sys/socket.h>
       #include <netatalk/at.h>

       ddp_socket = socket(AF_APPLETALK, SOCK_DGRAM, 0);
       raw_socket = socket(AF_APPLETALK, SOCK_RAW, protocol);

DESCRIPTION top

       Linux implements the Appletalk protocols described in Inside Appletalk.
       Only the DDP layer and AARP are present in the kernel.  They are designed
       to be used via the netatalk protocol libraries.  This page documents the
       interface for those who wish or need to use the DDP layer directly.

       The communication between Appletalk and the user program works using a BSD-
       compatible socket interface.  For more information on sockets, see
       socket(7).

       An AppleTalk socket is created by calling the socket(2) function with a
       AF_APPLETALK socket family argument.  Valid socket types are SOCK_DGRAM to
       open a ddp socket or SOCK_RAW to open a raw socket.  protocol is the
       Appletalk protocol to be received or sent.  For SOCK_RAW you must specify
       ATPROTO_DDP.

       Raw sockets may be only opened by a process with effective user ID 0 or
       when the process has the CAP_NET_RAW capability.

Address Format

       An Appletalk socket address is defined as a combination of a network
       number, a node number, and a port number.

           struct at_addr {
               unsigned short s_net;
               unsigned char  s_node;
           };

           struct sockaddr_atalk {
               sa_family_t    sat_family;    /* address family */
               unsigned char  sat_port;      /* port */
               struct at_addr sat_addr;      /* net/node */
           };

       sat_family is always set to AF_APPLETALK.  sat_port contains the port.  The
       port numbers below 129 are known as reserved ports.  Only processes with
       the effective user ID 0 or the CAP_NET_BIND_SERVICE capability may bind(2)
       to these sockets.  sat_addr is the host address.  The net member of struct
       at_addr contains the host network in network byte order.  The value of
       AT_ANYNET is a wildcard and also implies "this network."  The node member
       of struct at_addr contains the host node number.  The value of AT_ANYNODE
       is a wildcard and also implies "this node." The value of ATADDR_BCAST is a
       link local broadcast address.

Socket Options

       No protocol-specific socket options are supported.

/proc interfaces

       IP supports a set of /proc interfaces to configure some global AppleTalk
       parameters.  The parameters can be accessed by reading or writing files in
       the directory /proc/sys/net/atalk/.

       aarp-expiry-time
              The time interval (in seconds) before an AARP cache entry expires.

       aarp-resolve-time
              The time interval (in seconds) before an AARP cache entry is
              resolved.

       aarp-retransmit-limit
              The number of retransmissions of an AARP query before the node is
              declared dead.

       aarp-tick-time
              The timer rate (in seconds) for the timer driving AARP.

       The default values match the specification and should never need to be
       changed.

Ioctls

       All ioctls described in socket(7) apply to DDP.

ERRORS top

       EACCES The user tried to execute an operation without the necessary
              permissions.  These include sending to a broadcast address without
              having the broadcast flag set, and trying to bind to a reserved port
              without effective user ID 0 or CAP_NET_BIND_SERVICE.

       EADDRINUSE
              Tried to bind to an address already in use.

       EADDRNOTAVAIL
              A nonexistent interface was requested or the requested source
              address was not local.

       EAGAIN Operation on a nonblocking socket would block.

       EALREADY
              A connection operation on a nonblocking socket is already in
              progress.

       ECONNABORTED
              A connection was closed during an accept(2).

       EHOSTUNREACH
              No routing table entry matches the destination address.

       EINVAL Invalid argument passed.

       EISCONN
              connect(2) was called on an already connected socket.

       EMSGSIZE
              Datagram is bigger than the DDP MTU.

       ENODEV Network device not available or not capable of sending IP.

       ENOENT SIOCGSTAMP was called on a socket where no packet arrived.

       ENOMEM and ENOBUFS
              Not enough memory available.

       ENOPKG A kernel subsystem was not configured.

       ENOPROTOOPT and EOPNOTSUPP
              Invalid socket option passed.

       ENOTCONN
              The operation is only defined on a connected socket, but the socket
              wasn't connected.

       EPERM  User doesn't have permission to set high priority, make a
              configuration change, or send signals to the requested process or
              group.

       EPIPE  The connection was unexpectedly closed or shut down by the other
              end.

       ESOCKTNOSUPPORT
              The socket was unconfigured, or an unknown socket type was
              requested.

VERSIONS top

       Appletalk is supported by Linux 2.0 or higher.  The /proc interfaces exist
       since Linux 2.2.

NOTES top

       Be very careful with the SO_BROADCAST option - it is not privileged in
       Linux.  It is easy to overload the network with careless sending to
       broadcast addresses.

Compatibility

       The basic AppleTalk socket interface is compatible with netatalk on BSD-
       derived systems.  Many BSD systems fail to check SO_BROADCAST when sending
       broadcast frames; this can lead to compatibility problems.

       The raw socket mode is unique to Linux and exists to support the
       alternative CAP package and AppleTalk monitoring tools more easily.

BUGS top

       There are too many inconsistent error values.

       The ioctls used to configure routing tables, devices, AARP tables and other
       devices are not yet described.

SEE ALSO top

       recvmsg(2), sendmsg(2), capabilities(7), socket(7)

COLOPHON top

       This page is part of release 3.45 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-20                              DDP(7)


delete_module(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DELETE_MODULE(2)             Linux Programmer's Manual            DELETE_MODULE(2)

NAME top

       delete_module - unload a kernel module

SYNOPSIS top

       int delete_module(const char *name, int flags);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The delete_module() system call attempts to remove the unused loadable
       module entry identified by name.  If the module has an exit function, then
       that function is executed before unloading the module.  The flags argument
       is used to modify the behavior of the system call, as described below.
       This system call requires privilege.

       Module removal is attempted according to the following rules:

       1.  If there are other loaded modules that depend on (i.e., refer to
           symbols defined in) this module, then the call fails.

       2.  Otherwise, if the reference count for the module (i.e., the  number  of
           processes currently using the module) is zero, then the module is
           immediately unloaded.

       3.  If a module has a nonzero reference count, then the behavior depends on
           the bits set in flags.  In normal usage (see NOTES), the O_NONBLOCK
           flag is always specified, and the O_TRUNC flag may additionally be
           specified.

           The various combinations for flags have the following effect:

           flags == O_NONBLOCK
                  The call returns immediately, with an error.

           flags == (O_NONBLOCK | O_TRUNC)
                  The module is unloaded immediately, regardless of whether it has
                  a nonzero reference count.

           (flags & O_NONBLOCK) == 0
                  If flags does not specify O_NONBLOCK, the following steps occur:

                  *  The module is marked so that no new references are permitted.

                  *  If the module's reference count is nonzero, the caller is
                     placed in an uninterruptible sleep state
                     (TASK_UNINTERRUPTIBLE) until the reference count is zero, at
                     which point the call unblocks.

                  *  The module is unloaded in the usual way.

       The O_TRUNC flag has one further effect on the rules described above.  By
       default, if a module has an init function but no exit function, then an
       attempt to remove the module will fail.  However, if O_TRUNC was specified,
       this requirement is bypassed.

       Using the O_TRUNC flag is dangerous!  If the kernel was not built with
       CONFIG_MODULE_FORCE_UNLOAD, this flag is silently ignored.  (Normally,
       CONFIG_MODULE_FORCE_UNLOAD is enabled.)  Using this flag taints the kernel
       (TAINT_FORCED_RMMOD).

RETURN VALUE top

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

ERRORS top

       EBUSY  The module is not "live" (i.e., it is still being initialized or is
              already marked for removal); or, the module has an init function but
              has no exit function, and O_TRUNC was not specified in flags.

       EFAULT name refers to a location outside the process's accessible address
              space.

       ENOENT No module by that name exists.

       EPERM  The caller was not privileged (did not have the CAP_SYS_MODULE
              capability), or module unloading is disabled (see
              /proc/sys/kernel/modules_disabled in proc(5)).

       EWOULDBLOCK
              Other modules depend on this module; or, O_NONBLOCK was specified in
              flags, but the reference count of this module is nonzero and O_TRUNC
              was not specified in flags.

CONFORMING TO top

       delete_module() is Linux-specific.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

       The uninterruptible sleep that may occur if O_NONBLOCK is omitted from
       flags is considered undesirable, because the sleeping process is left in an
       unkillable state.  As at Linux 3.7, specifying O_NONBLOCK is optional, but
       in future kernels it is likely to become mandatory.

Linux 2.4 and earlier

       In Linux 2.4 and earlier, the system call took only one argument:

          int delete_module(const char *name);

       If name is NULL, all unused modules marked auto-clean are removed.

       Some further details of differences in the behavior of delete_module() in
       Linux 2.4 and earlier are not currently explained in this manual page.

SEE ALSO top

       create_module(2), init_module(2), query_module(2), lsmod(8), modprobe(8),
       rmmod(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-11-08                    DELETE_MODULE(2)


difftime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DIFFTIME(3)                  Linux Programmer's Manual                 DIFFTIME(3)

NAME top

       difftime - calculate time difference

SYNOPSIS top

       #include <time.h>

       double difftime(time_t time1, time_t time0);

DESCRIPTION top

       The difftime() function returns the number of seconds elapsed between time
       time1 and time time0, represented as a double.  Each of the times is
       specified in calendar time, which means its value is a measurement (in
       seconds) relative to the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

NOTES top

       On a POSIX system, time_t is an arithmetic type, and one could just define

              #define difftime(t1,t0) (double)(t1 - t0)

       when the possible overflow in the subtraction is not a concern.  On other
       systems, the data type time_t might use some other encoding where
       subtraction doesn't work directly.

SEE ALSO top

       date(1), gettimeofday(2), time(2), ctime(3), gmtime(3), localtime(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-02-25                         DIFFTIME(3)


dirfd(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DIRFD(3)                     Linux Programmer's Manual                    DIRFD(3)

NAME top

       dirfd - get directory stream file descriptor

SYNOPSIS top

       #include <sys/types.h>
       #include <dirent.h>

       int dirfd(DIR *dirp);

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

       dirfd():
           _BSD_SOURCE || _SVID_SOURCE
           || /* Since glibc 2.10: */
               (_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)

DESCRIPTION top

       The function dirfd() returns the file descriptor associated with the
       directory stream dirp.

       This descriptor is the one used internally by the directory stream.  As a
       result, it is only useful for functions which do not depend on or alter the
       file position, such as fstat(2) and fchdir(2).  It will be automatically
       closed when closedir(3) is called.

RETURN VALUE top

       On success, a nonnegative file descriptor is returned.  On error, -1 is
       returned.

ERRORS top

       POSIX.1-2008 specifies two errors, neither of which is returned by the
       current implementation.

       EINVAL dirp does not refer to a valid directory stream.

       ENOTSUP
              The implementation does not support the association of a file
              descriptor with a directory.

CONFORMING TO top

       POSIX.1-2008.  This function was a BSD extension, present in 4.3BSD-Reno,
       not in 4.2BSD.

NOTES top

       The prototype for dirfd() is only available if _BSD_SOURCE or _SVID_SOURCE
       is defined.

SEE ALSO top

       open(2), closedir(3), opendir(3), readdir(3), rewinddir(3), scandir(3),
       seekdir(3), telldir(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                            DIRFD(3)


Linux man-pages: alphabetic list of all pages

Alphabetic list of all pages

Jump to letter: a b c d e f g h i j k l m n o p q r s t u v w x y z

top
    a64l(3) - convert between long and base-64
    abort(3) - cause abnormal process termination
    abs(3) - compute the absolute value of an integer
    accept(2) - accept a connection on a socket
    accept4(2) - accept a connection on a socket
    access(2) - check real user's permissions for a file
    acct(2) - switch process accounting on or off
    acct(5) - process accounting file
    acos(3) - arc cosine function
    acosf(3) - arc cosine function
    acosh(3) - inverse hyperbolic cosine function
    acoshf(3) - inverse hyperbolic cosine function
    acoshl(3) - inverse hyperbolic cosine function
    acosl(3) - arc cosine function
    add_key(2) - add a key to the kernel's key management facility
    addmntent(3) - get file system descriptor file entry
    addseverity(3) - introduce new severity classes
    adjtime(3) - correct the time to synchronize the system clock
    adjtimex(2) - tune kernel clock
    afs_syscall(2) - unimplemented system calls
    aio(7) - POSIX asynchronous I/O overview
    aio_cancel(3) - cancel an outstanding asynchronous I/O request
    aio_error(3) - get error status of asynchronous I/O operation
    aio_fsync(3) - asynchronous file synchronization
    aio_init(3) - asynchronous I/O initialization
    aio_read(3) - asynchronous read
    aio_return(3) - get return status of asynchronous I/O operation
    aio_suspend(3) - wait for asynchronous I/O operation or timeout
    aio_write(3) - asynchronous write
    alarm(2) - set an alarm clock for delivery of a signal
    aligned_alloc(3) - allocate aligned memory
    alloca(3) - allocate memory that is automatically freed
    alloc_hugepages(2) - allocate or free huge pages
    alphasort(3) - scan a directory for matching entries
    arch_prctl(2) - set architecture-specific thread state
    argz(3) - functions to handle an argz list
    argz_add(3) - functions to handle an argz list
    argz_add_sep(3) - functions to handle an argz list
    argz_append(3) - functions to handle an argz list
    argz_count(3) - functions to handle an argz list
    argz_create(3) - functions to handle an argz list
    argz_create_sep(3) - functions to handle an argz list
    argz_delete(3) - functions to handle an argz list
    argz_extract(3) - functions to handle an argz list
    argz_insert(3) - functions to handle an argz list
    argz_next(3) - functions to handle an argz list
    argz_replace(3) - functions to handle an argz list
    argz_stringify(3) - functions to handle an argz list
    arm_fadvise(2) - predeclare an access pattern for file data
    arm_fadvise64_64(2) - predeclare an access pattern for file data
    armscii-8(7) - Armenian character set encoded in octal, decimal, and hexadecimal
    arm_sync_file_range(2) - sync a file segment with disk
    arp(7) - Linux ARP kernel module.
    ascii(7) - ASCII character set encoded in octal, decimal, and hexadecimal
    asctime(3) - transform date and time to broken-down time or ASCII
    asctime_r(3) - transform date and time to broken-down time or ASCII
    asin(3) - arc sine function
    asinf(3) - arc sine function
    asinh(3) - inverse hyperbolic sine function
    asinhf(3) - inverse hyperbolic sine function
    asinhl(3) - inverse hyperbolic sine function
    asinl(3) - arc sine function
    asprintf(3) - print to allocated string
    assert(3) - abort the program if assertion is false
    assert_perror(3) - test errnum and abort
    atan2(3) - arc tangent function of two variables
    atan2f(3) - arc tangent function of two variables
    atan2l(3) - arc tangent function of two variables
    atan(3) - arc tangent function
    atanf(3) - arc tangent function
    atanh(3) - inverse hyperbolic tangent function
    atanhf(3) - inverse hyperbolic tangent function
    atanhl(3) - inverse hyperbolic tangent function
    atanl(3) - arc tangent function
    atexit(3) - register a function to be called at normal process termination
    atof(3) - convert a string to a double
    atoi(3) - convert a string to an integer
    atol(3) - convert a string to an integer
    atoll(3) - convert a string to an integer
    atoq(3) - convert a string to an integer
    auth_destroy(3) - library routines for remote procedure calls
    authnone_create(3) - library routines for remote procedure calls
    authunix_create(3) - library routines for remote procedure calls
    authunix_create_default(3) - library routines for remote procedure calls

top
    backtrace(3) - support for application self-debugging
    backtrace_symbols(3) - support for application self-debugging
    backtrace_symbols_fd(3) - support for application self-debugging
    basename(3) - parse pathname components
    bcmp(3) - compare byte sequences
    bcopy(3) - copy byte sequence
    bdflush(2) - start, flush, or tune buffer-dirty-flush daemon
    be16toh(3) - convert values between host and big-/little-endian byte order
    be32toh(3) - convert values between host and big-/little-endian byte order
    be64toh(3) - convert values between host and big-/little-endian byte order
    bind(2) - bind a name to a socket
    bindresvport(3) - bind a socket to a privileged IP port
    boot(7) - general description of boot sequence
    bootparam(7) - introduction to boot time parameters of the Linux kernel
    break(2) - unimplemented system calls
    brk(2) - change data segment size
    bsd_signal(3) - signal handling with BSD semantics
    bsearch(3) - binary search of a sorted array
    bstring(3) - byte string operations
    btowc(3) - convert single byte to wide character
    btree(3) - btree database access method
    byteorder(3) - convert values between host and network byte order
    bzero(3) - write zero-valued bytes

top
    cabs(3) - absolute value of a complex number
    cabsf(3) - absolute value of a complex number
    cabsl(3) - absolute value of a complex number
    cacheflush(2) - flush contents of instruction and/or data cache
    cacos(3) - complex arc cosine
    cacosf(3) - complex arc cosine
    cacosh(3) - complex arc hyperbolic cosine
    cacoshf(3) - complex arc hyperbolic cosine
    cacoshl(3) - complex arc hyperbolic cosine
    cacosl(3) - complex arc cosine
    calloc(3) - allocate and free dynamic memory
    callrpc(3) - library routines for remote procedure calls
    canonicalize_file_name(3) -  return the canonicalized filename
    capabilities(7) - overview of Linux capabilities
    capget(2) - set/get capabilities of thread(s)
    capset(2) - set/get capabilities of thread(s)
    carg(3) - calculate the complex argument
    cargf(3) - calculate the complex argument
    cargl(3) - calculate the complex argument
    casin(3) - complex arc sine
    casinf(3) - complex arc sine
    casinh(3) - complex arc sine hyperbolic
    casinhf(3) - complex arc sine hyperbolic
    casinhl(3) - complex arc sine hyperbolic
    casinl(3) - complex arc sine
    catan(3) - complex arc tangents
    catanf(3) - complex arc tangents
    catanh(3) - complex arc tangents hyperbolic
    catanhf(3) - complex arc tangents hyperbolic
    catanhl(3) - complex arc tangents hyperbolic
    catanl(3) - complex arc tangents
    catclose(3) - open/close a message catalog
    catgets(3) - get message from a message catalog
    catopen(3) - open/close a message catalog
    cbc_crypt(3) - fast DES encryption
    cbrt(3) - cube root function
    cbrtf(3) - cube root function
    cbrtl(3) - cube root function
    cciss(4) - HP Smart Array block driver
    ccos(3) - complex cosine function
    ccosf(3) - complex cosine function
    ccosh(3) - complex hyperbolic cosine
    ccoshf(3) - complex hyperbolic cosine
    ccoshl(3) - complex hyperbolic cosine
    ccosl(3) - complex cosine function
    ceil(3) - ceiling function: smallest integral value not less than argument
    ceilf(3) - ceiling function: smallest integral value not less than argument
    ceill(3) - ceiling function: smallest integral value not less than argument
    cerf(3) - complex error function
    cerfc(3) - complex error function
    cerfcf(3) - complex error function
    cerfcl(3) - complex error function
    cerff(3) - complex error function
    cerfl(3) - complex error function
    cexp2(3) - base-2 exponent of a complex number
    cexp2f(3) - base-2 exponent of a complex number
    cexp2l(3) - base-2 exponent of a complex number
    cexp(3) - complex exponential function
    cexpf(3) - complex exponential function
    cexpl(3) - complex exponential function
    cfgetispeed(3) - get and set terminal attributes, line control, get and set baud rate
    cfgetospeed(3) - get and set terminal attributes, line control, get and set baud rate
    cfmakeraw(3) - get and set terminal attributes, line control, get and set baud rate
    cfree(3) - free allocated memory
    cfsetispeed(3) - get and set terminal attributes, line control, get and set baud rate
    cfsetospeed(3) - get and set terminal attributes, line control, get and set baud rate
    cfsetspeed(3) - get and set terminal attributes, line control, get and set baud rate
    charmap(5) - character symbols to define character encodings
    charsets(7) - programmer's view of character sets and internationalization
    chdir(2) - change working directory
    chmod(2) - change permissions of a file
    chown(2) - change ownership of a file
    chown32(2) - change ownership of a file
    chroot(2) - change root directory
    cimag(3) - get imaginary part of a complex number
    cimagf(3) - get imaginary part of a complex number
    cimagl(3) - get imaginary part of a complex number
    CIRCLEQ_ENTRY(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_HEAD(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_INIT(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_INSERT_AFTER(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_INSERT_BEFORE(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_INSERT_HEAD(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_INSERT_TAIL(3) - implementations of lists, tail queues, and circular queues
    CIRCLEQ_REMOVE(3) - implementations of lists, tail queues, and circular queues
    clearenv(3) - clear the environment
    clearerr(3) - check and reset stream status
    clearerr_unlocked(3) - nonlocking stdio functions
    clnt_broadcast(3) - library routines for remote procedure calls
    clnt_call(3) - library routines for remote procedure calls
    clnt_control(3) - library routines for remote procedure calls
    clnt_create(3) - library routines for remote procedure calls
    clnt_destroy(3) - library routines for remote procedure calls
    clnt_freeres(3) - library routines for remote procedure calls
    clnt_geterr(3) - library routines for remote procedure calls
    clnt_pcreateerror(3) - library routines for remote procedure calls
    clnt_perrno(3) - library routines for remote procedure calls
    clnt_perror(3) - library routines for remote procedure calls
    clntraw_create(3) - library routines for remote procedure calls
    clnt_spcreateerror(3) - library routines for remote procedure calls
    clnt_sperrno(3) - library routines for remote procedure calls
    clnt_sperror(3) - library routines for remote procedure calls
    clnttcp_create(3) - library routines for remote procedure calls
    clntudp_bufcreate(3) - library routines for remote procedure calls
    clntudp_create(3) - library routines for remote procedure calls
    clock(3) - determine processor time
    clock_getcpuclockid(3) - obtain ID of a process CPU-time clock
    clock_getres(2) - clock and time functions
    clock_getres(3) - clock and time functions
    clock_gettime(2) - clock and time functions
    clock_gettime(3) - clock and time functions
    clock_nanosleep(2) - high-resolution sleep with specifiable clock
    clock_settime(2) - clock and time functions
    clock_settime(3) - clock and time functions
    clog10(3) - base-10 logarithm of a complex number
    clog10f(3) - base-10 logarithm of a complex number
    clog10l(3) - base-10 logarithm of a complex number
    clog2(3) - base-2 logarithm of a complex number
    clog2f(3) - base-2 logarithm of a complex number
    clog2l(3) - base-2 logarithm of a complex number
    clog(3) - natural logarithm of a complex number
    clogf(3) - natural logarithm of a complex number
    clogl(3) - natural logarithm of a complex number
    __clone2(2) - create a child process
    clone2(2) - create a child process
    clone(2) - create a child process
    close(2) - close a file descriptor
    closedir(3) - close a directory
    closelog(3) - send messages to the system logger
    cmsg(3) - access ancillary data
    CMSG_ALIGN(3) - access ancillary data
    CMSG_FIRSTHDR(3) - access ancillary data
    CMSG_NXTHDR(3) - access ancillary data
    CMSG_SPACE(3) - access ancillary data
    complex(7) - basics of complex mathematics
    confstr(3) - get configuration dependent string variables
    conj(3) - calculate the complex conjugate
    conjf(3) - calculate the complex conjugate
    conjl(3) - calculate the complex conjugate
    connect(2) - initiate a connection on a socket
    console(4) - console terminal and virtual consoles
    console_codes(4) - Linux console escape and control sequences
    console_ioctl(4) - ioctl's for console terminal and virtual consoles
    copysign(3) - copy sign of a number
    copysignf(3) - copy sign of a number
    copysignl(3) - copy sign of a number
    core(5) - core dump file
    cos(3) - cosine function
    cosf(3) - cosine function
    cosh(3) - hyperbolic cosine function
    coshf(3) - hyperbolic cosine function
    coshl(3) - hyperbolic cosine function
    cosl(3) - cosine function
    cp1251(7) - CP 1251 character set encoded in octal, decimal, and hexadecimal
    cpow(3) - complex power function
    cpowf(3) - complex power function
    cpowl(3) - complex power function
    cproj(3) - project into Riemann Sphere
    cprojf(3) - project into Riemann Sphere
    cprojl(3) - project into Riemann Sphere
    CPU_ALLOC(3) - macros for manipulating CPU sets
    CPU_ALLOC_SIZE(3) - macros for manipulating CPU sets
    CPU_AND(3) - macros for manipulating CPU sets
    CPU_AND_S(3) - macros for manipulating CPU sets
    CPU_CLR(3) - macros for manipulating CPU sets
    CPU_CLR_S(3) - macros for manipulating CPU sets
    CPU_COUNT(3) - macros for manipulating CPU sets
    CPU_COUNT_S(3) - macros for manipulating CPU sets
    CPU_EQUAL(3) - macros for manipulating CPU sets
    CPU_EQUAL_S(3) - macros for manipulating CPU sets
    CPU_FREE(3) - macros for manipulating CPU sets
    cpuid(4) - x86 CPUID access device
    CPU_ISSET(3) - macros for manipulating CPU sets
    CPU_ISSET_S(3) - macros for manipulating CPU sets
    CPU_OR(3) - macros for manipulating CPU sets
    CPU_OR_S(3) - macros for manipulating CPU sets
    CPU_SET(3) - macros for manipulating CPU sets
    cpuset(7) - confine processes to processor and memory node subsets
    CPU_SET_S(3) - macros for manipulating CPU sets
    CPU_XOR(3) - macros for manipulating CPU sets
    CPU_XOR_S(3) - macros for manipulating CPU sets
    CPU_ZERO(3) - macros for manipulating CPU sets
    CPU_ZERO_S(3) - macros for manipulating CPU sets
    creal(3) - get real part of a complex number
    crealf(3) - get real part of a complex number
    creall(3) - get real part of a complex number
    creat(2) - open and possibly create a file or device
    create_module(2) - create a loadable module entry
    credentials(7) - process identifiers
    crypt(3) - password and data encryption
    crypt_r(3) - password and data encryption
    csin(3) - complex sine function
    csinf(3) - complex sine function
    csinh(3) - complex hyperbolic sine
    csinhf(3) - complex hyperbolic sine
    csinhl(3) - complex hyperbolic sine
    csinl(3) - complex sine function
    csqrt(3) - complex square root
    csqrtf(3) - complex square root
    csqrtl(3) - complex square root
    ctan(3) - complex tangent function
    ctanf(3) - complex tangent function
    ctanh(3) - complex hyperbolic tangent
    ctanhf(3) - complex hyperbolic tangent
    ctanhl(3) - complex hyperbolic tangent
    ctanl(3) - complex tangent function
    ctermid(3) - get controlling terminal name
    ctime(3) - transform date and time to broken-down time or ASCII
    ctime_r(3) - transform date and time to broken-down time or ASCII
    cuserid(3) - get username

top
    daemon(3) - run in the background
    daylight(3) - initialize time conversion information
    db(3) - database access methods
    dbopen(3) - database access methods
    ddp(7) - Linux AppleTalk protocol implementation
    delete_module(2) - unload a kernel module
    des_crypt(3) - fast DES encryption
    DES_FAILED(3) - fast DES encryption
    des_setparity(3) - fast DES encryption
    difftime(3) - calculate time difference
    dir_colors(5) - configuration file for dircolors(1)
    dirfd(3) - get directory stream file descriptor
    dirname(3) - parse pathname components
    div(3) - compute quotient and remainder of an integer division
    dladdr(3) - programming interface to dynamic linking loader
    dlclose(3) - programming interface to dynamic linking loader
    dlerror(3) - programming interface to dynamic linking loader
    dl_iterate_phdr(3) - walk through list of shared objects
    dlopen(3) - programming interface to dynamic linking loader
    dlsym(3) - programming interface to dynamic linking loader
    dlvsym(3) - programming interface to dynamic linking loader
    dn_comp(3) - resolver routines
    dn_expand(3) - resolver routines
    dprintf(3) - print to a file descriptor
    drand48(3) - generate uniformly distributed pseudo-random numbers
    drand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    drem(3) -  floating-point remainder function
    dremf(3) -  floating-point remainder function
    dreml(3) -  floating-point remainder function
    dsp56k(4) - DSP56001 interface device
    dup2(2) - duplicate a file descriptor
    dup(2) - duplicate a file descriptor
    dup3(2) - duplicate a file descriptor
    dysize(3) - get number of days for a given year

top
    eaccess(3) - check effective user's permissions for a file
    ecb_crypt(3) - fast DES encryption
    ecvt(3) - convert a floating-point number to a string
    ecvt_r(3) - convert a floating-point number to a string
    edata(3) - end of program segments
    elf(5) - format of Executable and Linking Format (ELF) files
    encrypt(3) - encrypt 64-bit messages
    encrypt_r(3) - encrypt 64-bit messages
    end(3) - end of program segments
    endaliasent(3) - read an alias entry
    endfsent(3) - handle fstab entries
    endgrent(3) - get group file entry
    endhostent(3) - get network host entry
    endian(3) - convert values between host and big-/little-endian byte order
    endmntent(3) - get file system descriptor file entry
    endnetent(3) - get network entry
    endnetgrent(3) - handle network group entries
    endprotoent(3) - get protocol entry
    endpwent(3) - get password file entry
    endrpcent(3) - get RPC entry
    endservent(3) - get service entry
    endspent(3) - get shadow password file entry
    endttyent(3) - get ttys file entry
    endusershell(3) - get permitted user shells
    endutent(3) - access utmp file entries
    endutxent(3) - access utmp file entries
    environ(7) - user environment
    envz(3) - environment string support
    envz_add(3) - environment string support
    envz_entry(3) - environment string support
    envz_get(3) - environment string support
    envz_merge(3) - environment string support
    envz_remove(3) - environment string support
    envz_strip(3) - environment string support
    epoll(7) - I/O event notification facility
    epoll_create1(2) - open an epoll file descriptor
    epoll_create(2) - open an epoll file descriptor
    epoll_ctl(2) - control interface for an epoll descriptor
    epoll_pwait(2) - wait for an I/O event on an epoll file descriptor
    epoll_wait(2) - wait for an I/O event on an epoll file descriptor
    erand48(3) - generate uniformly distributed pseudo-random numbers
    erand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    erf(3) - error function
    erfc(3) - complementary error function
    erfcf(3) - complementary error function
    erfcl(3) - complementary error function
    erff(3) - error function
    erfl(3) - error function
    err(3) - formatted error messages
    errno(3) - number of last error
    error(3) - glibc error reporting functions
    error_at_line(3) - glibc error reporting functions
    error_message_count(3) - glibc error reporting functions
    error_one_per_line(3) - glibc error reporting functions
    error_print_progname(3) - glibc error reporting functions
    errx(3) - formatted error messages
    etext(3) - end of program segments
    ether_aton(3) - Ethernet address manipulation routines
    ether_aton_r(3) - Ethernet address manipulation routines
    ether_hostton(3) - Ethernet address manipulation routines
    ether_line(3) - Ethernet address manipulation routines
    ether_ntoa(3) - Ethernet address manipulation routines
    ether_ntoa_r(3) - Ethernet address manipulation routines
    ether_ntohost(3) - Ethernet address manipulation routines
    euidaccess(3) - check effective user's permissions for a file
    eventfd2(2) - create a file descriptor for event notification
    eventfd(2) - create a file descriptor for event notification
    eventfd_read(3) - create a file descriptor for event notification
    eventfd_write(3) - create a file descriptor for event notification
    exec(3) - execute a file
    execl(3) - execute a file
    execle(3) - execute a file
    execlp(3) - execute a file
    execv(3) - execute a file
    execve(2) - execute program
    execvp(3) - execute a file
    execvpe(3) - execute a file
    _exit(2) - terminate the calling process
    _Exit(2) - terminate the calling process
    exit(2) - terminate the calling process
    exit(3) - cause normal process termination
    exit_group(2) - exit all threads in a process
    exp10(3) - base-10 exponential function
    exp10f(3) - base-10 exponential function
    exp10l(3) - base-10 exponential function
    exp2(3) - base-2 exponential function
    exp2f(3) - base-2 exponential function
    exp2l(3) - base-2 exponential function
    exp(3) - base-e exponential function
    expf(3) - base-e exponential function
    expl(3) - base-e exponential function
    expm1(3) - exponential minus 1
    expm1f(3) - exponential minus 1
    expm1l(3) - exponential minus 1

top
    fabs(3) - absolute value of floating-point number
    fabsf(3) - absolute value of floating-point number
    fabsl(3) - absolute value of floating-point number
    faccessat(2) - check user's permissions of a file relative to a directory file descriptor
    fadvise64(2) - predeclare an access pattern for file data
    fadvise64_64(2) - predeclare an access pattern for file data
    fallocate(2) - manipulate file space
    __fbufsize(3) - interfaces to stdio FILE structure
    fchdir(2) - change working directory
    fchmod(2) - change permissions of a file
    fchmodat(2) - change permissions of a file relative to a directory file descriptor
    fchown(2) - change ownership of a file
    fchown32(2) - change ownership of a file
    fchownat(2) - change ownership of a file relative to a directory file descriptor
    fclose(3) - close a stream
    fcloseall(3) - close all open streams
    fcntl(2) - manipulate file descriptor
    fcntl64(2) - manipulate file descriptor
    fcvt(3) - convert a floating-point number to a string
    fcvt_r(3) - convert a floating-point number to a string
    fd(4) - floppy disk device
    fdatasync(2) - synchronize a file's in-core state with storage device
    FD_CLR(3) - synchronous I/O multiplexing
    fdim(3) - positive difference
    fdimf(3) - positive difference
    fdiml(3) - positive difference
    FD_ISSET(3) - synchronous I/O multiplexing
    fdopen(3) - stream open functions
    fdopendir(3) - open a directory
    FD_SET(3) - synchronous I/O multiplexing
    FD_ZERO(3) - synchronous I/O multiplexing
    feature_test_macros(7) - feature test macros
    feclearexcept(3) - floating-point rounding and exception handling
    fedisableexcept(3) - floating-point rounding and exception handling
    feenableexcept(3) - floating-point rounding and exception handling
    fegetenv(3) - floating-point rounding and exception handling
    fegetexcept(3) - floating-point rounding and exception handling
    fegetexceptflag(3) - floating-point rounding and exception handling
    fegetround(3) - floating-point rounding and exception handling
    feholdexcept(3) - floating-point rounding and exception handling
    fenv(3) - floating-point rounding and exception handling
    feof(3) - check and reset stream status
    feof_unlocked(3) - nonlocking stdio functions
    feraiseexcept(3) - floating-point rounding and exception handling
    ferror(3) - check and reset stream status
    ferror_unlocked(3) - nonlocking stdio functions
    fesetenv(3) - floating-point rounding and exception handling
    fesetexceptflag(3) - floating-point rounding and exception handling
    fesetround(3) - floating-point rounding and exception handling
    fetestexcept(3) - floating-point rounding and exception handling
    feupdateenv(3) - floating-point rounding and exception handling
    fexecve(3) - execute program specified via file descriptor
    fflush(3) - flush a stream
    fflush_unlocked(3) - nonlocking stdio functions
    ffs(3) - find first bit set in a word
    ffsl(3) - find first bit set in a word
    ffsll(3) - find first bit set in a word
    fgetc(3) - input of characters and strings
    fgetc_unlocked(3) - nonlocking stdio functions
    fgetgrent(3) - get group file entry
    fgetgrent_r(3) - get group file entry reentrantly
    fgetpos(3) - reposition a stream
    fgetpwent(3) - get password file entry
    fgetpwent_r(3) - get passwd file entry reentrantly
    fgets(3) - input of characters and strings
    fgetspent(3) - get shadow password file entry
    fgetspent_r(3) - get shadow password file entry
    fgets_unlocked(3) - nonlocking stdio functions
    fgetwc(3) - read a wide character from a FILE stream
    fgetwc_unlocked(3) - nonlocking stdio functions
    fgetws(3) - read a wide-character string from a FILE stream
    fgetws_unlocked(3) - nonlocking stdio functions
    fgetxattr(2) - retrieve an extended attribute value
    fifo(7) - first-in first-out special file, named pipe
    fileno(3) - check and reset stream status
    fileno_unlocked(3) - nonlocking stdio functions
    filesystems(5) - Linux file-system types: minix, ext, ext2, ext3, ext4, Reiserfs, XFS, JFS, xia, msdos, umsdos, vfat, ntfs, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs
    finite(3) - BSD floating-point classification functions
    finitef(3) - BSD floating-point classification functions
    finitel(3) - BSD floating-point classification functions
    __flbf(3) - interfaces to stdio FILE structure
    flistxattr(2) - list extended attribute names
    flock(2) - apply or remove an advisory lock on an open file
    flockfile(3) - lock FILE for stdio
    floor(3) - largest integral value not greater than argument
    floorf(3) - largest integral value not greater than argument
    floorl(3) - largest integral value not greater than argument
    _flushlbf(3) - interfaces to stdio FILE structure
    fma(3) - floating-point multiply and add
    fmaf(3) - floating-point multiply and add
    fmal(3) - floating-point multiply and add
    fmax(3) - determine maximum of two floating-point numbers
    fmaxf(3) - determine maximum of two floating-point numbers
    fmaxl(3) - determine maximum of two floating-point numbers
    fmemopen(3) -  open memory as stream
    fmin(3) - determine minimum of two floating-point numbers
    fminf(3) - determine minimum of two floating-point numbers
    fminl(3) - determine minimum of two floating-point numbers
    fmod(3) - floating-point remainder function
    fmodf(3) - floating-point remainder function
    fmodl(3) - floating-point remainder function
    fmtmsg(3) - print formatted error messages
    fnmatch(3) - match filename or pathname
    fopen(3) - stream open functions
    fopencookie(3) - opening a custom stream
    fork(2) - create a child process
    forkpty(3) - tty utility functions
    fpathconf(3) - get configuration values for files
    fpclassify(3) - floating-point classification macros
    __fpending(3) - interfaces to stdio FILE structure
    fprintf(3) - formatted output conversion
    __fpurge(3) - purge a stream
    fpurge(3) - purge a stream
    fputc(3) - output of characters and strings
    fputc_unlocked(3) - nonlocking stdio functions
    fputs(3) - output of characters and strings
    fputs_unlocked(3) - nonlocking stdio functions
    fputwc(3) - write a wide character to a FILE stream
    fputwc_unlocked(3) - nonlocking stdio functions
    fputws(3) - write a wide-character string to a FILE stream
    fputws_unlocked(3) - nonlocking stdio functions
    fread(3) - binary stream input/output
    __freadable(3) - interfaces to stdio FILE structure
    __freading(3) - interfaces to stdio FILE structure
    fread_unlocked(3) - nonlocking stdio functions
    free(3) - allocate and free dynamic memory
    freeaddrinfo(3) - network address and service translation
    freehostent(3) - get network hostnames and addresses
    free_hugepages(2) - allocate or free huge pages
    freeifaddrs(3) - get interface addresses
    fremovexattr(2) - remove an extended attribute
    freopen(3) - stream open functions
    frexp(3) - convert floating-point number to fractional and integral components
    frexpf(3) - convert floating-point number to fractional and integral components
    frexpl(3) - convert floating-point number to fractional and integral components
    fs(5) - Linux file-system types: minix, ext, ext2, ext3, ext4, Reiserfs, XFS, JFS, xia, msdos, umsdos, vfat, ntfs, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs
    fscanf(3) - input format conversion
    fseek(3) - reposition a stream
    fseeko(3) - seek to or report file position
    __fsetlocking(3) - interfaces to stdio FILE structure
    fsetpos(3) - reposition a stream
    fsetxattr(2) - set an extended attribute value
    fstat(2) - get file status
    fstat64(2) - get file status
    fstatat(2) - get file status relative to a directory file descriptor
    fstatat64(2) - get file status relative to a directory file descriptor
    fstatfs(2) - get file system statistics
    fstatfs64(2) - get file system statistics
    fstatvfs(2) - get file system statistics
    fstatvfs(3) - get file system statistics
    fsync(2) - synchronize a file's in-core state with storage device
    ftell(3) - reposition a stream
    ftello(3) - seek to or report file position
    ftime(3) - return date and time
    ftok(3) - convert a pathname and a project identifier to a System V IPC key
    ftpusers(5) - list of users that may not log in via the FTP daemon
    ftruncate(2) - truncate a file to a specified length
    ftruncate64(2) - truncate a file to a specified length
    ftrylockfile(3) - lock FILE for stdio
    fts(3) -  traverse a file hierarchy
    fts_children(3) -  traverse a file hierarchy
    fts_close(3) -  traverse a file hierarchy
    fts_open(3) -  traverse a file hierarchy
    fts_read(3) -  traverse a file hierarchy
    fts_set(3) -  traverse a file hierarchy
    ftw(3) - file tree walk
    full(4) - always full device
    funlockfile(3) - lock FILE for stdio
    futex(2) - fast user-space locking
    futex(7) - fast user-space locking
    futimens(3) - change file timestamps with nanosecond precision
    futimes(3) - change file timestamps
    futimesat(2) - change timestamps of a file relative to a directory file descriptor
    fwide(3) - set and determine the orientation of a FILE stream
    fwprintf(3) - formatted wide-character output conversion
    __fwritable(3) - interfaces to stdio FILE structure
    fwrite(3) - binary stream input/output
    fwrite_unlocked(3) - nonlocking stdio functions
    __fwriting(3) - interfaces to stdio FILE structure

top
    gai_cancel(3) - asynchronous network address and service translation
    gai_error(3) - asynchronous network address and service translation
    gai_strerror(3) - network address and service translation
    gai_suspend(3) - asynchronous network address and service translation
    gamma(3) - (logarithm of the) gamma function
    gammaf(3) - (logarithm of the) gamma function
    gammal(3) - (logarithm of the) gamma function
    gcvt(3) - convert a floating-point number to a string
    getaddrinfo(3) - network address and service translation
    getaddrinfo_a(3) - asynchronous network address and service translation
    getaliasbyname(3) - read an alias entry
    getaliasbyname_r(3) - read an alias entry
    getaliasent(3) - read an alias entry
    getaliasent_r(3) - read an alias entry
    getauxval(3) - retrieve a value from the auxiliary vector
    getc(3) - input of characters and strings
    getchar(3) - input of characters and strings
    getchar_unlocked(3) - nonlocking stdio functions
    getcontext(2) - get or set the user context
    getcpu(2) - determine CPU and NUMA node on which the calling thread is running
    getc_unlocked(3) - nonlocking stdio functions
    get_current_dir_name(3) - get current working directory
    getcwd(2) - get current working directory
    getcwd(3) - get current working directory
    getdate(3) - convert a date-plus-time string to broken-down time
    getdate_err(3) - convert a date-plus-time string to broken-down time
    getdate_r(3) - convert a date-plus-time string to broken-down time
    getdelim(3) - delimited string input
    getdents(2) - get directory entries
    getdents64(2) - get directory entries
    getdirentries(3) - get directory entries in a file system-independent format
    getdomainname(2) - get/set NIS domain name
    getdtablesize(2) - get descriptor table size
    getegid(2) - get group identity
    getegid32(2) - get group identity
    getent(1) - get entries from Name Service Switch libraries
    getenv(3) - get an environment variable
    geteuid(2) - get user identity
    geteuid32(2) - get user identity
    getfsent(3) - handle fstab entries
    getfsfile(3) - handle fstab entries
    getfsspec(3) - handle fstab entries
    getgid(2) - get group identity
    getgid32(2) - get group identity
    getgrent(3) - get group file entry
    getgrent_r(3) - get group file entry reentrantly
    getgrgid(3) - get group file entry
    getgrgid_r(3) - get group file entry
    getgrnam(3) - get group file entry
    getgrnam_r(3) - get group file entry
    getgrouplist(3) - get list of groups to which a user belongs
    getgroups(2) - get/set list of supplementary group IDs
    getgroups32(2) - get/set list of supplementary group IDs
    gethostbyaddr(3) - get network host entry
    gethostbyaddr_r(3) - get network host entry
    gethostbyname2(3) - get network host entry
    gethostbyname2_r(3) - get network host entry
    gethostbyname(3) - get network host entry
    gethostbyname_r(3) - get network host entry
    gethostent(3) - get network host entry
    gethostent_r(3) - get network host entry
    gethostid(2) - get or set the unique identifier of the current host
    gethostid(3) - get or set the unique identifier of the current host
    gethostname(2) - get/set hostname
    getifaddrs(3) - get interface addresses
    getipnodebyaddr(3) - get network hostnames and addresses
    getipnodebyname(3) - get network hostnames and addresses
    getitimer(2) - get or set value of an interval timer
    get_kernel_syms(2) - retrieve exported kernel and module symbols
    getline(3) - delimited string input
    getloadavg(3) - get system load averages
    getlogin(3) - get username
    getlogin_r(3) - get username
    get_mempolicy(2) - retrieve NUMA memory policy for a process
    getmntent(3) - get file system descriptor file entry
    getmntent_r(3) - get file system descriptor file entry
    get_myaddress(3) - library routines for remote procedure calls
    getnameinfo(3) - address-to-name translation in protocol-independent manner
    getnetbyaddr(3) - get network entry
    getnetbyaddr_r(3) - get network entry (reentrant)
    getnetbyname(3) - get network entry
    getnetbyname_r(3) - get network entry (reentrant)
    getnetent(3) - get network entry
    getnetent_r(3) - get network entry (reentrant)
    getnetgrent(3) - handle network group entries
    getnetgrent_r(3) - handle network group entries
    get_nprocs(3) - get number of processors
    get_nprocs_conf(3) - get number of processors
    getopt(3) - Parse command-line options
    getopt_long(3) - Parse command-line options
    getopt_long_only(3) - Parse command-line options
    getpagesize(2) - get memory page size
    getpass(3) - get a password
    getpeername(2) - get name of connected peer socket
    getpgid(2) - set/get process group
    getpgrp(2) - set/get process group
    getpid(2) - get process identification
    getpmsg(2) - unimplemented system calls
    getppid(2) - get process identification
    getpriority(2) - get/set program scheduling priority
    getprotobyname(3) - get protocol entry
    getprotobyname_r(3) - get protocol entry (reentrant)
    getprotobynumber(3) - get protocol entry
    getprotobynumber_r(3) - get protocol entry (reentrant)
    getprotoent(3) - get protocol entry
    getprotoent_r(3) - get protocol entry (reentrant)
    getpt(3) - open the pseudoterminal master (PTM)
    getpw(3) - reconstruct password line entry
    getpwent(3) - get password file entry
    getpwent_r(3) - get passwd file entry reentrantly
    getpwnam(3) - get password file entry
    getpwnam_r(3) - get password file entry
    getpwuid(3) - get password file entry
    getpwuid_r(3) - get password file entry
    getresgid(2) - get real, effective and saved user/group IDs
    getresgid32(2) - get real, effective and saved user/group IDs
    getresuid(2) - get real, effective and saved user/group IDs
    getresuid32(2) - get real, effective and saved user/group IDs
    getrlimit(2) - get/set resource limits
    get_robust_list(2) - get/set list of robust futexes
    getrpcbyname(3) - get RPC entry
    getrpcbyname_r(3) - get RPC entry (reentrant)
    getrpcbynumber(3) - get RPC entry
    getrpcbynumber_r(3) - get RPC entry (reentrant)
    getrpcent(3) - get RPC entry
    getrpcent_r(3) - get RPC entry (reentrant)
    getrpcport(3) - get RPC port number
    getrusage(2) - get resource usage
    gets(3) - input of characters and strings
    getservbyname(3) - get service entry
    getservbyname_r(3) - get service entry (reentrant)
    getservbyport(3) - get service entry
    getservbyport_r(3) - get service entry (reentrant)
    getservent(3) - get service entry
    getservent_r(3) - get service entry (reentrant)
    getsid(2) - get session ID
    getsockname(2) - get socket name
    getsockopt(2) - get and set options on sockets
    getspent(3) - get shadow password file entry
    getspent_r(3) - get shadow password file entry
    getspnam(3) - get shadow password file entry
    getspnam_r(3) - get shadow password file entry
    getsubopt(3) - parse suboption arguments from a string
    get_thread_area(2) - get a thread-local storage (TLS) area
    gettid(2) - get thread identification
    gettimeofday(2) - get / set time
    getttyent(3) - get ttys file entry
    getttynam(3) - get ttys file entry
    getuid(2) - get user identity
    getuid32(2) - get user identity
    getumask(3) - get file creation mask
    getusershell(3) - get permitted user shells
    getutent(3) - access utmp file entries
    getutent_r(3) - access utmp file entries
    getutid(3) - access utmp file entries
    getutid_r(3) - access utmp file entries
    getutline(3) - access utmp file entries
    getutline_r(3) - access utmp file entries
    getutmp(3) - copy utmp structure to utmpx, and vice versa
    getutmpx(3) - copy utmp structure to utmpx, and vice versa
    getutxent(3) - access utmp file entries
    getutxid(3) - access utmp file entries
    getutxline(3) - access utmp file entries
    getw(3) - input and output of words (ints)
    getwc(3) - read a wide character from a FILE stream
    getwchar(3) - read a wide character from standard input
    getwchar_unlocked(3) - nonlocking stdio functions
    getwc_unlocked(3) - nonlocking stdio functions
    getwd(3) - get current working directory
    getxattr(2) - retrieve an extended attribute value
    glibc(7) - overview of standard C libraries on Linux
    glob(3) - find pathnames matching a pattern, free memory from glob()
    glob(7) - globbing pathnames
    globfree(3) - find pathnames matching a pattern, free memory from glob()
    gmtime(3) - transform date and time to broken-down time or ASCII
    gmtime_r(3) - transform date and time to broken-down time or ASCII
    gnu_dev_major(3) - manage a device number
    gnu_dev_makedev(3) - manage a device number
    gnu_dev_minor(3) - manage a device number
    gnu_get_libc_release(3) - get glibc version and release
    gnu_get_libc_version(3) - get glibc version and release
    grantpt(3) - grant access to the slave pseudoterminal
    group(5) - user group file
    gsignal(3) - software signal facility
    gtty(2) - unimplemented system calls

top
    hash(3) - hash database access method
    hasmntopt(3) - get file system descriptor file entry
    hcreate(3) - hash table management
    hcreate_r(3) - hash table management
    hd(4) - MFM/IDE hard disk devices
    hdestroy(3) - hash table management
    hdestroy_r(3) - hash table management
    h_errno(3) - get network host entry
    herror(3) - get network host entry
    hier(7) - description of the file system hierarchy
    host.conf(5) - resolver configuration file
    hostname(7) - hostname resolution description
    hosts(5) - static table lookup for hostnames
    hosts.equiv(5) - list of hosts and users that are granted "trusted" fBrfP command access to your system
    hpsa(4) - HP Smart Array SCSI driver
    hsearch(3) - hash table management
    hsearch_r(3) - hash table management
    hstrerror(3) - get network host entry
    htobe16(3) - convert values between host and big-/little-endian byte order
    htobe32(3) - convert values between host and big-/little-endian byte order
    htobe64(3) - convert values between host and big-/little-endian byte order
    htole16(3) - convert values between host and big-/little-endian byte order
    htole32(3) - convert values between host and big-/little-endian byte order
    htole64(3) - convert values between host and big-/little-endian byte order
    htonl(3) - convert values between host and network byte order
    htons(3) - convert values between host and network byte order
    HUGE_VAL(3) - floating-point constants
    HUGE_VALF(3) - floating-point constants
    HUGE_VALL(3) - floating-point constants
    hypot(3) - Euclidean distance function
    hypotf(3) - Euclidean distance function
    hypotl(3) - Euclidean distance function

top
    icmp(7) - Linux IPv4 ICMP kernel module.
    iconv(3) - perform character set conversion
    iconv_close(3) - deallocate descriptor for character set conversion
    iconv_open(3) - allocate descriptor for character set conversion
    idle(2) - make process 0 idle
    if_freenameindex(3) - get network interface names and indexes
    if_indextoname(3) - mappings between network interface names and indexes
    if_nameindex(3) - get network interface names and indexes
    if_nametoindex(3) - mappings between network interface names and indexes
    ilogb(3) - get integer exponent of a floating-point value
    ilogbf(3) - get integer exponent of a floating-point value
    ilogbl(3) - get integer exponent of a floating-point value
    imaxabs(3) - compute the absolute value of an integer
    imaxdiv(3) - compute quotient and remainder of an integer division
    inb(2) - port I/O
    inb_p(2) - port I/O
    index(3) - locate character in string
    inet(3) - Internet address manipulation routines
    inet_addr(3) - Internet address manipulation routines
    inet_aton(3) - Internet address manipulation routines
    inet_lnaof(3) - Internet address manipulation routines
    inet_makeaddr(3) - Internet address manipulation routines
    inet_netof(3) - Internet address manipulation routines
    inet_network(3) - Internet address manipulation routines
    inet_ntoa(3) - Internet address manipulation routines
    inet_ntop(3) - convert IPv4 and IPv6 addresses from binary to text form
    inet_pton(3) - convert IPv4 and IPv6 addresses from text to binary form
    INFINITY(3) - floating-point constants
    infnan(3) - deal with infinite or not-a-number (NaN) result
    initgroups(3) - initialize the supplementary group access list
    init_module(2) - load a kernel module
    initrd(4) - boot loader initialized RAM disk
    initstate(3) - random number generator
    initstate_r(3) - reentrant random number generator
    inl(2) - port I/O
    inl_p(2) - port I/O
    innetgr(3) - handle network group entries
    inotify(7) - monitoring file system events
    inotify_add_watch(2) - add a watch to an initialized inotify instance
    inotify_init1(2) - initialize an inotify instance
    inotify_init(2) - initialize an inotify instance
    inotify_rm_watch(2) - remove an existing watch from an inotify instance
    insb(2) - port I/O
    insl(2) - port I/O
    insque(3) - insert/remove an item from a queue
    insw(2) - port I/O
    intro(1) - introduction to user commands
    intro(2) - introduction to system calls
    intro(3) - introduction to library functions
    intro(4) - introduction to special files
    intro(5) - introduction to file formats
    intro(6) - introduction to games
    intro(7) - introduction to overview, conventions, and miscellany section
    intro(8) - introduction to administration and privileged commands
    inw(2) - port I/O
    inw_p(2) - port I/O
    io_cancel(2) - cancel an outstanding asynchronous I/O operation
    ioctl(2) - control device
    ioctl_list(2) - list of ioctl calls in Linux/i386 kernel
    io_destroy(2) - destroy an asynchronous I/O context
    io_getevents(2) - read asynchronous I/O events from the completion queue
    ioperm(2) - set port input/output permissions
    iopl(2) - change I/O privilege level
    ioprio_get(2) - get/set I/O scheduling class and priority
    ioprio_set(2) - get/set I/O scheduling class and priority
    io_setup(2) - create an asynchronous I/O context
    io_submit(2) - submit asynchronous I/O blocks for processing
    ip(7) - Linux IPv4 protocol implementation
    ipc(2) - System V IPC system calls
    ipc(5) - System V interprocess communication mechanisms
    ipv6(7) - Linux IPv6 protocol implementation
    iruserok(3) - routines for returning a stream to a remote command
    iruserok_af(3) - routines for returning a stream to a remote command
    isalnum(3) - character classification routines
    isalpha(3) - character classification routines
    isascii(3) - character classification routines
    isatty(3) - test whether a file descriptor refers to a terminal
    isblank(3) - character classification routines
    iscntrl(3) - character classification routines
    isdigit(3) - character classification routines
    isfinite(3) - floating-point classification macros
    isgraph(3) - character classification routines
    isgreater(3) - floating-point relational tests without exception for NaN
    isgreaterequal(3) - floating-point relational tests without exception for NaN
    isinf(3) - floating-point classification macros
    isinff(3) - BSD floating-point classification functions
    isinfl(3) - BSD floating-point classification functions
    isless(3) - floating-point relational tests without exception for NaN
    islessequal(3) - floating-point relational tests without exception for NaN
    islessgreater(3) - floating-point relational tests without exception for NaN
    islower(3) - character classification routines
    isnan(3) - floating-point classification macros
    isnanf(3) - BSD floating-point classification functions
    isnanl(3) - BSD floating-point classification functions
    isnormal(3) - floating-point classification macros
    iso-8859-10(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
    iso_8859-10(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
    iso_8859_10(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
    iso-8859-11(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
    iso_8859-11(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
    iso_8859_11(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
    iso-8859-13(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
    iso_8859-13(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
    iso_8859_13(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
    iso-8859-14(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
    iso_8859-14(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
    iso_8859_14(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
    iso-8859-15(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
    iso_8859-15(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
    iso_8859_15(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
    iso-8859-16(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
    iso_8859-16(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
    iso_8859_16(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
    iso-8859-1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
    iso_8859-1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
    iso_8859_1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
    iso-8859-2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
    iso_8859-2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
    iso_8859_2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
    iso-8859-3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
    iso_8859-3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
    iso_8859_3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
    iso-8859-4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
    iso_8859-4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
    iso_8859_4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
    iso-8859-5(7) - ISO 8859-5 character set encoded in octal, decimal, and hexadecimal
    iso_8859-5(7) - ISO 8859-5 character set encoded in octal, decimal, and hexadecimal
    iso_8859_5(7) - ISO 8859-5 character set encoded in octal, decimal, and hexadecimal
    iso-8859-6(7) - ISO 8859-6 character set encoded in octal, decimal, and hexadecimal
    iso_8859-6(7) - ISO 8859-6 character set encoded in octal, decimal, and hexadecimal
    iso_8859_6(7) - ISO 8859-6 character set encoded in octal, decimal, and hexadecimal
    iso-8859-7(7) - ISO 8859-7 character set encoded in octal, decimal, and hexadecimal
    iso_8859-7(7) - ISO 8859-7 character set encoded in octal, decimal, and hexadecimal
    iso_8859_7(7) - ISO 8859-7 character set encoded in octal, decimal, and hexadecimal
    iso-8859-8(7) - ISO 8859-8 character set encoded in octal, decimal, and hexadecimal
    iso_8859-8(7) - ISO 8859-8 character set encoded in octal, decimal, and hexadecimal
    iso_8859_8(7) - ISO 8859-8 character set encoded in octal, decimal, and hexadecimal
    iso-8859-9(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
    iso_8859-9(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
    iso_8859_9(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
    isprint(3) - character classification routines
    ispunct(3) - character classification routines
    isspace(3) - character classification routines
    issue(5) - prelogin message and identification file
    isunordered(3) - floating-point relational tests without exception for NaN
    isupper(3) - character classification routines
    iswalnum(3) - test for alphanumeric wide character
    iswalpha(3) - test for alphabetic wide character
    iswblank(3) - test for whitespace wide character
    iswcntrl(3) - test for control wide character
    iswctype(3) - wide-character classification
    iswdigit(3) - test for decimal digit wide character
    iswgraph(3) - test for graphic wide character
    iswlower(3) - test for lowercase wide character
    iswprint(3) - test for printing wide character
    iswpunct(3) - test for punctuation or symbolic wide character
    iswspace(3) - test for whitespace wide character
    iswupper(3) - test for uppercase wide character
    iswxdigit(3) - test for hexadecimal digit wide character
    isxdigit(3) - character classification routines

top
    j0(3) - Bessel functions of the first kind
    j0f(3) - Bessel functions of the first kind
    j0l(3) - Bessel functions of the first kind
    j1(3) - Bessel functions of the first kind
    j1f(3) - Bessel functions of the first kind
    j1l(3) - Bessel functions of the first kind
    jn(3) - Bessel functions of the first kind
    jnf(3) - Bessel functions of the first kind
    jnl(3) - Bessel functions of the first kind
    jrand48(3) - generate uniformly distributed pseudo-random numbers
    jrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly

top
    kexec_load(2) - load a new kernel for later execution
    keyctl(2) - manipulate the kernel's key management facility
    key_decryptsession(3) - interfaces to rpc keyserver daemon
    key_encryptsession(3) - interfaces to rpc keyserver daemon
    key_gendes(3) - interfaces to rpc keyserver daemon
    key_secretkey_is_set(3) - interfaces to rpc keyserver daemon
    key_setsecret(3) - interfaces to rpc keyserver daemon
    kill(2) - send signal to a process
    killpg(2) - send signal to a process group
    klogctl(3) - read and/or clear kernel message ring buffer; set console_loglevel
    kmem(4) - system memory, kernel memory and system ports
    koi8-r(7) - Russian character set encoded in octal, decimal, and hexadecimal
    koi8-u(7) - Ukrainian character set encoded in octal, decimal, and hexadecimal

top
    l64a(3) - convert between long and base-64
    labs(3) - compute the absolute value of an integer
    latin10(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
    latin1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
    latin2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
    latin3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
    latin4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
    latin5(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
    latin6(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
    latin7(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
    latin8(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
    latin9(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
    lchown(2) - change ownership of a file
    lchown32(2) - change ownership of a file
    lckpwdf(3) - get shadow password file entry
    lcong48(3) - generate uniformly distributed pseudo-random numbers
    lcong48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    ldconfig(8) - configure dynamic linker run-time bindings
    ldd(1) - print shared library dependencies
    ldexp(3) - multiply floating-point number by integral power of 2
    ldexpf(3) - multiply floating-point number by integral power of 2
    ldexpl(3) - multiply floating-point number by integral power of 2
    ldiv(3) - compute quotient and remainder of an integer division
    ld-linux(8) - dynamic linker/loader
    ld-linux.so(8) - dynamic linker/loader
    ld.so(8) - dynamic linker/loader
    le16toh(3) - convert values between host and big-/little-endian byte order
    le32toh(3) - convert values between host and big-/little-endian byte order
    le64toh(3) - convert values between host and big-/little-endian byte order
    lfind(3) - linear search of an array
    lgamma(3) - log gamma function
    lgammaf(3) - log gamma function
    lgammaf_r(3) - log gamma function
    lgammal(3) - log gamma function
    lgammal_r(3) - log gamma function
    lgamma_r(3) - log gamma function
    lgetxattr(2) - retrieve an extended attribute value
    libc(7) - overview of standard C libraries on Linux
    link(2) - make a new name for a file
    linkat(2) - create a file link relative to directory file descriptors
    lio_listio(3) - initiate a list of I/O requests
    listen(2) - listen for connections on a socket
    LIST_ENTRY(3) - implementations of lists, tail queues, and circular queues
    LIST_HEAD(3) - implementations of lists, tail queues, and circular queues
    LIST_INIT(3) - implementations of lists, tail queues, and circular queues
    LIST_INSERT_AFTER(3) - implementations of lists, tail queues, and circular queues
    LIST_INSERT_HEAD(3) - implementations of lists, tail queues, and circular queues
    LIST_REMOVE(3) - implementations of lists, tail queues, and circular queues
    listxattr(2) - list extended attribute names
    llabs(3) - compute the absolute value of an integer
    lldiv(3) - compute quotient and remainder of an integer division
    llistxattr(2) - list extended attribute names
    llrint(3) - round to nearest integer
    llrintf(3) - round to nearest integer
    llrintl(3) - round to nearest integer
    llround(3) - round to nearest integer, away from zero
    llroundf(3) - round to nearest integer, away from zero
    llroundl(3) - round to nearest integer, away from zero
    _llseek(2) - reposition read/write file offset
    llseek(2) - reposition read/write file offset
    locale(5) - describes a locale definition file
    locale(7) - description of multilanguage support
    localeconv(3) - get numeric formatting information
    localtime(3) - transform date and time to broken-down time or ASCII
    localtime_r(3) - transform date and time to broken-down time or ASCII
    lock(2) - unimplemented system calls
    lockf(3) - apply, test or remove a POSIX lock on an open file
    log10(3) -  base-10 logarithmic function
    log10f(3) -  base-10 logarithmic function
    log10l(3) -  base-10 logarithmic function
    log1p(3) -  logarithm of 1 plus argument
    log1pf(3) -  logarithm of 1 plus argument
    log1pl(3) -  logarithm of 1 plus argument
    log2(3) - base-2 logarithmic function
    log2f(3) - base-2 logarithmic function
    log2l(3) - base-2 logarithmic function
    log(3) - natural logarithmic function
    logb(3) - get exponent of a floating-point value
    logbf(3) - get exponent of a floating-point value
    logbl(3) - get exponent of a floating-point value
    logf(3) - natural logarithmic function
    login(3) - write utmp and wtmp entries
    login_tty(3) - tty utility functions
    logl(3) - natural logarithmic function
    logout(3) - write utmp and wtmp entries
    logwtmp(3) - append an entry to the wtmp file
    longjmp(3) - nonlocal jump to a saved stack context
    lookup_dcookie(2) - return a directory entry's path
    lp(4) - line printer devices
    lrand48(3) - generate uniformly distributed pseudo-random numbers
    lrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    lremovexattr(2) - remove an extended attribute
    lrint(3) - round to nearest integer
    lrintf(3) - round to nearest integer
    lrintl(3) - round to nearest integer
    lround(3) - round to nearest integer, away from zero
    lroundf(3) - round to nearest integer, away from zero
    lroundl(3) - round to nearest integer, away from zero
    lsearch(3) - linear search of an array
    lseek(2) - reposition read/write file offset
    lseek64(3) - reposition 64-bit read/write file offset
    lsetxattr(2) - set an extended attribute value
    lstat(2) - get file status
    lstat64(2) - get file status
    lutimes(3) - change file timestamps

top
    madvise1(2) - unimplemented system calls
    madvise(2) - give advice about use of memory
    mailaddr(7) - mail addressing description
    major(3) - manage a device number
    makecontext(3) - manipulate user context
    makedev(3) - manage a device number
    mallinfo(3) - obtain memory allocation information
    malloc(3) - allocate and free dynamic memory
    malloc_get_state(3) - record and restore state of malloc implementation
    __malloc_hook(3) - malloc debugging variables
    malloc_hook(3) - malloc debugging variables
    malloc_info(3) - export malloc state to a stream
    malloc_set_state(3) - record and restore state of malloc implementation
    malloc_stats(3) - print memory allocation statistics
    malloc_trim(3) - release free memory from the top of the heap
    malloc_usable_size(3) - obtain size of block of memory allocated from heap
    mallopt(3) - set memory allocation parameters
    man(7) - macros to format man pages
    man-pages(7) - conventions for writing Linux man pages
    matherr(3) - SVID math library exception handling
    math_error(7) - detecting errors from mathematical functions
    MB_CUR_MAX(3) - maximum length of a multibyte character in the current locale
    mbind(2) - set memory policy for a memory range
    mblen(3) - determine number of bytes in next multibyte character
    MB_LEN_MAX(3) - maximum multibyte length of a character across all locales
    mbrlen(3) - determine number of bytes in next multibyte character
    mbrtowc(3) - convert a multibyte sequence to a wide character
    mbsinit(3) - test for initial shift state
    mbsnrtowcs(3) - convert a multibyte string to a wide-character string
    mbsrtowcs(3) - convert a multibyte string to a wide-character string
    mbstowcs(3) - convert a multibyte string to a wide-character string
    mbtowc(3) - convert a multibyte sequence to a wide character
    mcheck(3) - heap consistency checking
    mcheck_check_all(3) - heap consistency checking
    mcheck_pedantic(3) - heap consistency checking
    mdoc(7) - quick reference guide for the .Nm -mdoc macro package
    mdoc.samples(7) - tutorial sampler for writing .Bx manuals with .Nm -mdoc
    mem(4) - system memory, kernel memory and system ports
    memalign(3) - allocate aligned memory
    memccpy(3) - copy memory area
    memchr(3) - scan memory for a character
    memcmp(3) - compare memory areas
    memcpy(3) - copy memory area
    memfrob(3) - frobnicate (encrypt) a memory area
    memmem(3) - locate a substring
    memmove(3) - copy memory area
    mempcpy(3) - copy memory area
    memrchr(3) - scan memory for a character
    memset(3) - fill memory with a constant byte
    migrate_pages(2) - move all pages in a process to another set of nodes
    mincore(2) - determine whether pages are resident in memory
    minor(3) - manage a device number
    mkdir(2) - create a directory
    mkdirat(2) - create a directory relative to a directory file descriptor
    mkdtemp(3) - create a unique temporary directory
    mkfifo(3) - make a FIFO special file (a named pipe)
    mkfifoat(3) - make a FIFO (named pipe) relative to a directory file descriptor
    mknod(2) - create a special or ordinary file
    mknodat(2) - create a special or ordinary file relative to a directory file descriptor
    mkostemp(3) - create a unique temporary file
    mkostemps(3) - create a unique temporary file
    mkstemp(3) - create a unique temporary file
    mkstemps(3) - create a unique temporary file
    mktemp(3) - make a unique temporary filename
    mktime(3) - transform date and time to broken-down time or ASCII
    mlock(2) - lock and unlock memory
    mlockall(2) - lock and unlock memory
    mmap2(2) - map files or devices into memory
    mmap(2) - map or unmap files or devices into memory
    mmap64(3) - map or unmap files or devices into memory
    modf(3) - extract signed integral and fractional values from floating-point number
    modff(3) - extract signed integral and fractional values from floating-point number
    modfl(3) - extract signed integral and fractional values from floating-point number
    modify_ldt(2) - get or set ldt
    motd(5) - message of the day
    mount(2) - mount file system
    mouse(4) - serial mouse interface
    move_pages(2) - move individual pages of a process to another node
    mpool(3) - shared memory buffer pool
    mprobe(3) - heap consistency checking
    mprotect(2) - set protection on a region of memory
    mpx(2) - unimplemented system calls
    mq_close(3) - close a message queue descriptor
    mq_getattr(3) - get/set message queue attributes
    mq_getsetattr(2) - get/set message queue attributes
    mq_notify(2) - register for notification when a message is available
    mq_notify(3) - register for notification when a message is available
    mq_open(2) - open a message queue
    mq_open(3) - open a message queue
    mq_overview(7) - overview of POSIX message queues
    mq_receive(3) - receive a message from a message queue
    mq_send(3) - send a message to a message queue
    mq_setattr(3) - get/set message queue attributes
    mq_timedreceive(2) - receive a message from a message queue
    mq_timedreceive(3) - receive a message from a message queue
    mq_timedsend(2) - send a message to a message queue
    mq_timedsend(3) - send a message to a message queue
    mq_unlink(2) - remove a message queue
    mq_unlink(3) - remove a message queue
    mrand48(3) - generate uniformly distributed pseudo-random numbers
    mrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    mremap(2) - remap a virtual memory address
    msgctl(2) - message control operations
    msgget(2) - get a message queue identifier
    msgop(2) - message operations
    msgrcv(2) - message operations
    msgsnd(2) - message operations
    msr(4) - x86 CPU MSR access device
    msync(2) - synchronize a file with a memory map
    mtrace(3) - malloc tracing
    munlock(2) - lock and unlock memory
    munlockall(2) - lock and unlock memory
    munmap(2) - map or unmap files or devices into memory
    muntrace(3) - malloc tracing

top
    nan(3) - return 'Not a Number'
    NAN(3) - floating-point constants
    nanf(3) - return 'Not a Number'
    nanl(3) - return 'Not a Number'
    nanosleep(2) - high-resolution sleep
    nearbyint(3) - round to nearest integer
    nearbyintf(3) - round to nearest integer
    nearbyintl(3) - round to nearest integer
    netdevice(7) - low-level access to Linux network devices
    netlink(3) - Netlink macros
    netlink(7) - communication between kernel and user space (AF_NETLINK)
    networks(5) - network name information
    _newselect(2) - synchronous I/O multiplexing
    nextafter(3) - floating-point number manipulation
    nextafterf(3) - floating-point number manipulation
    nextafterl(3) - floating-point number manipulation
    nexttoward(3) - floating-point number manipulation
    nexttowardf(3) - floating-point number manipulation
    nexttowardl(3) - floating-point number manipulation
    nfsservctl(2) - syscall interface to kernel nfs daemon
    nftw(3) - file tree walk
    nice(2) - change process priority
    nl_langinfo(3) - query language and locale information
    nologin(5) - prevent unprivileged users from logging into the system
    nrand48(3) - generate uniformly distributed pseudo-random numbers
    nrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    nscd(8) - name service cache daemon
    nscd.conf(5) - name service cache daemon configuration file
    nsswitch.conf(5) - Name Service Switch configuration file
    ntohl(3) - convert values between host and network byte order
    ntohs(3) - convert values between host and network byte order
    null(4) - data sink
    numa(7) - overview of Non-Uniform Memory Architecture
    numa_maps(5) - overview of Non-Uniform Memory Architecture

top
    offsetof(3) - offset of a structure member
    oldfstat(2) - get file status
    oldlstat(2) - get file status
    oldolduname(2) - get name and information about current kernel
    oldstat(2) - get file status
    olduname(2) - get name and information about current kernel
    on_exit(3) - register a function to be called at normal process termination
    open(2) - open and possibly create a file or device
    openat(2) - open a file relative to a directory file descriptor
    opendir(3) - open a directory
    openlog(3) - send messages to the system logger
    open_memstream(3) -  open memory as stream
    openpty(3) - tty utility functions
    open_wmemstream(3) -  open memory as stream
    operator(7) - C operator precedence and order of evaluation
    optarg(3) - Parse command-line options
    opterr(3) - Parse command-line options
    optind(3) - Parse command-line options
    optopt(3) - Parse command-line options
    outb(2) - port I/O
    outb_p(2) - port I/O
    outl(2) - port I/O
    outl_p(2) - port I/O
    outsb(2) - port I/O
    outsl(2) - port I/O
    outsw(2) - port I/O
    outw(2) - port I/O
    outw_p(2) - port I/O

top
    packet(7) - packet interface on device level.
    passwd2des(3) - RFS password encryption
    passwd(5) - password file
    pathconf(3) - get configuration values for files
    path_resolution(7) - how a pathname is resolved to a file
    pause(2) - wait for signal
    pciconfig_iobase(2) - pci device information handling
    pciconfig_read(2) - pci device information handling
    pciconfig_write(2) - pci device information handling
    pclose(3) - pipe stream to or from a process
    perror(3) - print a system error message
    personality(2) - set the process execution domain
    phys(2) - unimplemented system calls
    pipe2(2) - create pipe
    pipe(2) - create pipe
    pipe(7) - overview of pipes and FIFOs
    pivot_root(2) - change the root file system
    pmap_getmaps(3) - library routines for remote procedure calls
    pmap_getport(3) - library routines for remote procedure calls
    pmap_rmtcall(3) - library routines for remote procedure calls
    pmap_set(3) - library routines for remote procedure calls
    pmap_unset(3) - library routines for remote procedure calls
    poll(2) - wait for some event on a file descriptor
    popen(3) - pipe stream to or from a process
    port(4) - system memory, kernel memory and system ports
    posix_fadvise(2) - predeclare an access pattern for file data
    posix_fallocate(3) - allocate file space
    posix_memalign(3) - allocate aligned memory
    posix_openpt(3) - open a pseudoterminal device
    posixoptions(7) - optional parts of the POSIX standard
    pow10(3) - base-10 power functions
    pow10f(3) - base-10 power functions
    pow10l(3) - base-10 power functions
    pow(3) - power functions
    powf(3) - power functions
    powl(3) - power functions
    ppoll(2) - wait for some event on a file descriptor
    prctl(2) - operations on a process
    pread(2) - read from or write to a file descriptor at a given offset
    pread64(2) - read from or write to a file descriptor at a given offset
    preadv(2) - read or write data into multiple buffers
    printf(3) - formatted output conversion
    prlimit(2) - get/set resource limits
    proc(5) - process information pseudo-file system
    process_vm_readv(2) - transfer data between process address spaces
    process_vm_writev(2) - transfer data between process address spaces
    prof(2) - unimplemented system calls
    profil(3) - execution time profile
    program_invocation_name(3) -  obtain name used to invoke calling program
    program_invocation_short_name(3) -  obtain name used to invoke calling program
    protocols(5) - protocols definition file
    pselect(2) - synchronous I/O multiplexing
    pselect6(2) - synchronous I/O multiplexing
    psiginfo(3) - print signal message
    psignal(3) - print signal message
    pthread_attr_destroy(3) - initialize and destroy thread attributes object
    pthread_attr_getaffinity_np(3) - set/get CPU affinity attribute in thread attributes object
    pthread_attr_getdetachstate(3) - set/get detach state attribute in thread attributes object
    pthread_attr_getguardsize(3) - set/get guard size attribute in thread attributes object
    pthread_attr_getinheritsched(3) - set/get inherit scheduler attribute in thread attributes object
    pthread_attr_getschedparam(3) - set/get scheduling parameter attributes in thread attributes object
    pthread_attr_getschedpolicy(3) - set/get scheduling policy attribute in thread attributes object
    pthread_attr_getscope(3) - set/get contention scope attribute in thread attributes object
    pthread_attr_getstack(3) - set/get stack attributes in thread attributes object
    pthread_attr_getstackaddr(3) - set/get stack address attribute in thread attributes object
    pthread_attr_getstacksize(3) - set/get stack size attribute in thread attributes object
    pthread_attr_init(3) - initialize and destroy thread attributes object
    pthread_attr_setaffinity_np(3) - set/get CPU affinity attribute in thread attributes object
    pthread_attr_setdetachstate(3) - set/get detach state attribute in thread attributes object
    pthread_attr_setguardsize(3) - set/get guard size attribute in thread attributes object
    pthread_attr_setinheritsched(3) - set/get inherit scheduler attribute in thread attributes object
    pthread_attr_setschedparam(3) - set/get scheduling parameter attributes in thread attributes object
    pthread_attr_setschedpolicy(3) - set/get scheduling policy attribute in thread attributes object
    pthread_attr_setscope(3) - set/get contention scope attribute in thread attributes object
    pthread_attr_setstack(3) - set/get stack attributes in thread attributes object
    pthread_attr_setstackaddr(3) - set/get stack address attribute in thread attributes object
    pthread_attr_setstacksize(3) - set/get stack size attribute in thread attributes object
    pthread_cancel(3) - send a cancellation request to a thread
    pthread_cleanup_pop(3) - push and pop thread cancellation clean-up handlers
    pthread_cleanup_pop_restore_np(3) - push and pop thread cancellation clean-up handlers while saving cancelability type
    pthread_cleanup_push(3) - push and pop thread cancellation clean-up handlers
    pthread_cleanup_push_defer_np(3) - push and pop thread cancellation clean-up handlers while saving cancelability type
    pthread_create(3) - create a new thread
    pthread_detach(3) - detach a thread
    pthread_equal(3) - compare thread IDs
    pthread_exit(3) - terminate calling thread
    pthread_getaffinity_np(3) - set/get CPU affinity of a thread
    pthread_getattr_np(3) - get attributes of created thread
    pthread_getconcurrency(3) - set/get the concurrency level
    pthread_getcpuclockid(3) - retrieve ID of a thread's CPU time clock
    pthread_getschedparam(3) - set/get scheduling policy and parameters of a thread
    pthread_join(3) - join with a terminated thread
    pthread_kill(3) - send a signal to a thread
    pthread_kill_other_threads_np(3) - terminate all other threads in process
    pthreads(7) - POSIX threads
    pthread_self(3) - obtain ID of the calling thread
    pthread_setaffinity_np(3) - set/get CPU affinity of a thread
    pthread_setcancelstate(3) - set cancelability state and type
    pthread_setcanceltype(3) - set cancelability state and type
    pthread_setconcurrency(3) - set/get the concurrency level
    pthread_setschedparam(3) - set/get scheduling policy and parameters of a thread
    pthread_setschedprio(3) - set scheduling priority of a thread
    pthread_sigmask(3) - examine and change mask of blocked signals
    pthread_sigqueue(3) - queue a signal and data to a thread
    pthread_testcancel(3) - request delivery of any pending cancellation request
    pthread_timedjoin_np(3) - try to join with a terminated thread
    pthread_tryjoin_np(3) - try to join with a terminated thread
    pthread_yield(3) - yield the processor
    ptmx(4) - pseudoterminal master and slave
    ptrace(2) - process trace
    pts(4) - pseudoterminal master and slave
    ptsname(3) - get the name of the slave pseudoterminal
    ptsname_r(3) - get the name of the slave pseudoterminal
    pty(7) - pseudoterminal interfaces
    putc(3) - output of characters and strings
    putchar(3) - output of characters and strings
    putchar_unlocked(3) - nonlocking stdio functions
    putc_unlocked(3) - nonlocking stdio functions
    putenv(3) - change or add an environment variable
    putgrent(3) - write a group database entry to a file
    putpmsg(2) - unimplemented system calls
    putpwent(3) - write a password file entry
    puts(3) - output of characters and strings
    putspent(3) - get shadow password file entry
    pututline(3) - access utmp file entries
    pututxline(3) - access utmp file entries
    putw(3) - input and output of words (ints)
    putwc(3) - write a wide character to a FILE stream
    putwchar(3) - write a wide character to standard output
    putwchar_unlocked(3) - nonlocking stdio functions
    putwc_unlocked(3) - nonlocking stdio functions
    pvalloc(3) - allocate aligned memory
    pwrite(2) - read from or write to a file descriptor at a given offset
    pwrite64(2) - read from or write to a file descriptor at a given offset
    pwritev(2) - read or write data into multiple buffers

top
    qecvt(3) - convert a floating-point number to a string
    qecvt_r(3) - convert a floating-point number to a string
    qfcvt(3) - convert a floating-point number to a string
    qfcvt_r(3) - convert a floating-point number to a string
    qgcvt(3) - convert a floating-point number to a string
    qsort(3) - sort an array
    qsort_r(3) - sort an array
    query_module(2) - query the kernel for various bits pertaining to modules
    queue(3) - implementations of lists, tail queues, and circular queues
    quotactl(2) - manipulate disk quotas

top
    raise(3) - send a signal to the caller
    ram(4) - ram disk device
    rand(3) - pseudo-random number generator
    random(3) - random number generator
    random(4) - kernel random number source devices
    random_r(3) - reentrant random number generator
    rand_r(3) - pseudo-random number generator
    raw(7) - Linux IPv4 raw sockets
    rawmemchr(3) - scan memory for a character
    rcmd(3) - routines for returning a stream to a remote command
    rcmd_af(3) - routines for returning a stream to a remote command
    read(2) - read from a file descriptor
    readahead(2) - perform file readahead into page cache
    readdir(2) - read directory entry
    readdir(3) - read a directory
    readdir_r(3) - read a directory
    readlink(2) - read value of a symbolic link
    readlinkat(2) - read value of a symbolic link relative to a directory file descriptor
    readv(2) - read or write data into multiple buffers
    realloc(3) - allocate and free dynamic memory
    realpath(3) - return the canonicalized absolute pathname
    reboot(2) - reboot or enable/disable Ctrl-Alt-Del
    recno(3) - record number database access method
    re_comp(3) - BSD regex functions
    recv(2) - receive a message from a socket
    recvfrom(2) - receive a message from a socket
    recvmmsg(2) - receive multiple messages on a socket
    recvmsg(2) - receive a message from a socket
    re_exec(3) - BSD regex functions
    regcomp(3) - POSIX regex functions
    regerror(3) - POSIX regex functions
    regex(3) - POSIX regex functions
    regex(7) - POSIX.2 regular expressions
    regexec(3) - POSIX regex functions
    regfree(3) - POSIX regex functions
    registerrpc(3) - library routines for remote procedure calls
    remainder(3) -  floating-point remainder function
    remainderf(3) -  floating-point remainder function
    remainderl(3) -  floating-point remainder function
    remap_file_pages(2) - create a nonlinear file mapping
    remove(3) - remove a file or directory
    removexattr(2) - remove an extended attribute
    remque(3) - insert/remove an item from a queue
    remquo(3) - remainder and part of quotient
    remquof(3) - remainder and part of quotient
    remquol(3) - remainder and part of quotient
    rename(2) - change the name or location of a file
    renameat(2) - rename a file relative to directory file descriptors
    request_key(2) - request a key from the kernel's key management facility
    res_init(3) - resolver routines
    res_mkquery(3) - resolver routines
    resolv.conf(5) - resolver configuration file
    resolver(3) - resolver routines
    resolver(5) - resolver configuration file
    res_query(3) - resolver routines
    res_querydomain(3) - resolver routines
    res_search(3) - resolver routines
    res_send(3) - resolver routines
    rewind(3) - reposition a stream
    rewinddir(3) - reset directory stream
    rexec(3) - return stream to a remote command
    rexec_af(3) - return stream to a remote command
    rindex(3) - locate character in string
    rint(3) - round to nearest integer
    rintf(3) - round to nearest integer
    rintl(3) - round to nearest integer
    rmdir(2) - delete a directory
    round(3) - round to nearest integer, away from zero
    roundf(3) - round to nearest integer, away from zero
    roundl(3) - round to nearest integer, away from zero
    rpc(3) - library routines for remote procedure calls
    rpc(5) - RPC program number data base
    rpmatch(3) - determine if the answer to a question is affirmative or negative
    rresvport(3) - routines for returning a stream to a remote command
    rresvport_af(3) - routines for returning a stream to a remote command
    rtc(4) - real-time clock
    rtime(3) - get time from a remote machine
    rtld-audit(7) - auditing API for the dynamic linker
    rtnetlink(3) - macros to manipulate rtnetlink messages
    rtnetlink(7) - Linux IPv4 routing socket
    rt_sigaction(2) - examine and change a signal action
    rt_sigpending(2) - examine pending signals
    rt_sigprocmask(2) - examine and change blocked signals
    rt_sigqueueinfo(2) - queue a signal and data
    rt_sigreturn(2) - return from signal handler and cleanup stack frame
    rt_sigsuspend(2) - wait for a signal
    rt_sigtimedwait(2) - synchronously wait for queued signals
    rt_tgsigqueueinfo(2) - queue a signal and data
    ruserok(3) - routines for returning a stream to a remote command
    ruserok_af(3) - routines for returning a stream to a remote command

top
    s390_runtime_instr(2) - enable/disable s390 CPU run-time instrumentation
    sbrk(2) - change data segment size
    scalb(3) - multiply floating-point number by integral power of radix (OBSOLETE)
    scalbf(3) - multiply floating-point number by integral power of radix (OBSOLETE)
    scalbl(3) - multiply floating-point number by integral power of radix (OBSOLETE)
    scalbln(3) - multiply floating-point number by integral power of radix
    scalblnf(3) - multiply floating-point number by integral power of radix
    scalblnl(3) - multiply floating-point number by integral power of radix
    scalbn(3) - multiply floating-point number by integral power of radix
    scalbnf(3) - multiply floating-point number by integral power of radix
    scalbnl(3) - multiply floating-point number by integral power of radix
    scandir(3) - scan a directory for matching entries
    scandirat(3) - scan a directory relative to a directory file descriptor
    scanf(3) - input format conversion
    sched_getaffinity(2) -  set and get a process's CPU affinity mask
    sched_getcpu(3) - determine CPU on which the calling thread is running
    sched_getparam(2) - set and get scheduling parameters
    sched_get_priority_max(2) - get static priority range
    sched_get_priority_min(2) - get static priority range
    sched_getscheduler(2) - set and get scheduling policy/parameters
    sched_rr_get_interval(2) - get the SCHED_RR interval for the named process
    sched_setaffinity(2) -  set and get a process's CPU affinity mask
    sched_setparam(2) - set and get scheduling parameters
    sched_setscheduler(2) - set and get scheduling policy/parameters
    sched_yield(2) - yield the processor
    sd(4) - driver for SCSI disk drives
    secure_getenv(3) - get an environment variable
    securetty(5) - file which lists ttys from which root can log in
    security(2) - unimplemented system calls
    seed48(3) - generate uniformly distributed pseudo-random numbers
    seed48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    seekdir(3) - set the position of the next readdir() call in the directory stream.
    select(2) - synchronous I/O multiplexing
    select_tut(2) - synchronous I/O multiplexing
    sem_close(3) - close a named semaphore
    semctl(2) - semaphore control operations
    sem_destroy(3) - destroy an unnamed semaphore
    semget(2) - get a semaphore set identifier
    sem_getvalue(3) - get the value of a semaphore
    sem_init(3) - initialize an unnamed semaphore
    semop(2) - semaphore operations
    sem_open(3) - initialize and open a named semaphore
    sem_overview(7) - overview of POSIX semaphores
    sem_post(3) - unlock a semaphore
    semtimedop(2) - semaphore operations
    sem_timedwait(3) - lock a semaphore
    sem_trywait(3) - lock a semaphore
    sem_unlink(3) - remove a named semaphore
    sem_wait(3) - lock a semaphore
    send(2) - send a message on a socket
    sendfile(2) - transfer data between file descriptors
    sendfile64(2) - transfer data between file descriptors
    sendmmsg(2) - send multiple messages on a socket
    sendmsg(2) - send a message on a socket
    sendto(2) - send a message on a socket
    services(5) - Internet network services list
    setaliasent(3) - read an alias entry
    setbuf(3) - stream buffering operations
    setbuffer(3) - stream buffering operations
    setcontext(2) - get or set the user context
    setdomainname(2) - get/set NIS domain name
    setegid(2) - set effective user or group ID
    setenv(3) - change or add an environment variable
    seteuid(2) - set effective user or group ID
    __setfpucw(3) - set FPU control word on i386 architecture (obsolete)
    setfsent(3) - handle fstab entries
    setfsgid(2) - set group identity used for file system checks
    setfsgid32(2) - set group identity used for file system checks
    setfsuid(2) - set user identity used for file system checks
    setfsuid32(2) - set user identity used for file system checks
    setgid(2) - set group identity
    setgid32(2) - set group identity
    setgrent(3) - get group file entry
    setgroups(2) - get/set list of supplementary group IDs
    setgroups32(2) - get/set list of supplementary group IDs
    sethostent(3) - get network host entry
    sethostid(2) - get or set the unique identifier of the current host
    sethostid(3) - get or set the unique identifier of the current host
    sethostname(2) - get/set hostname
    setitimer(2) - get or set value of an interval timer
    setjmp(3) - save stack context for nonlocal goto
    setkey(3) - encrypt 64-bit messages
    setkey_r(3) - encrypt 64-bit messages
    setlinebuf(3) - stream buffering operations
    setlocale(3) - set the current locale
    setlogmask(3) - set log priority mask
    set_mempolicy(2) - set default NUMA memory policy for a process and its children
    setmntent(3) - get file system descriptor file entry
    setnetent(3) - get network entry
    setnetgrent(3) - handle network group entries
    setns(2) - reassociate thread with a namespace
    setpgid(2) - set/get process group
    setpgrp(2) - set/get process group
    setpriority(2) - get/set program scheduling priority
    setprotoent(3) - get protocol entry
    setpwent(3) - get password file entry
    setregid(2) - set real and/or effective user or group ID
    setregid32(2) - set real and/or effective user or group ID
    setresgid(2) - set real, effective and saved user or group ID
    setresgid32(2) - set real, effective and saved user or group ID
    setresuid(2) - set real, effective and saved user or group ID
    setresuid32(2) - set real, effective and saved user or group ID
    setreuid(2) - set real and/or effective user or group ID
    setreuid32(2) - set real and/or effective user or group ID
    setrlimit(2) - get/set resource limits
    set_robust_list(2) - get/set list of robust futexes
    setrpcent(3) - get RPC entry
    setservent(3) - get service entry
    setsid(2) - creates a session and sets the process group ID
    setsockopt(2) - get and set options on sockets
    setspent(3) - get shadow password file entry
    setstate(3) - random number generator
    setstate_r(3) - reentrant random number generator
    set_thread_area(2) - set a thread local storage (TLS) area
    set_tid_address(2) - set pointer to thread ID
    settimeofday(2) - get / set time
    setttyent(3) - get ttys file entry
    setuid(2) - set user identity
    setuid32(2) - set user identity
    setup(2) - setup devices and file systems, mount root file system
    setusershell(3) - get permitted user shells
    setutent(3) - access utmp file entries
    setutxent(3) - access utmp file entries
    setvbuf(3) - stream buffering operations
    setxattr(2) - set an extended attribute value
    sgetmask(2) - manipulation of signal mask (obsolete)
    sgetspent(3) - get shadow password file entry
    sgetspent_r(3) - get shadow password file entry
    shells(5) - pathnames of valid login shells
    shmat(2) - shared memory operations
    shmctl(2) - shared memory control
    shmdt(2) - shared memory operations
    shmget(2) - allocates a shared memory segment
    shmop(2) - shared memory operations
    shm_open(3) - create/open or unlink POSIX shared memory objects
    shm_overview(7) - overview of POSIX shared memory
    shm_unlink(3) - create/open or unlink POSIX shared memory objects
    shutdown(2) - shut down part of a full-duplex connection
    sigaction(2) - examine and change a signal action
    sigaddset(3) - POSIX signal set operations.
    sigaltstack(2) - set and/or get signal stack context
    sigandset(3) - POSIX signal set operations.
    sigblock(3) - BSD signal API
    sigdelset(3) - POSIX signal set operations.
    sigemptyset(3) - POSIX signal set operations.
    sigevent(7) - structure for notification from asynchronous routines
    sigfillset(3) - POSIX signal set operations.
    siggetmask(3) - BSD signal API
    sighold(3) - System V signal API
    sigignore(3) - System V signal API
    siginterrupt(3) - allow signals to interrupt system calls
    sigisemptyset(3) - POSIX signal set operations.
    sigismember(3) - POSIX signal set operations.
    siglongjmp(3) - nonlocal jump to a saved stack context
    sigmask(3) - BSD signal API
    signal(2) - ANSI C signal handling
    signal(7) - overview of signals
    signalfd(2) - create a file descriptor for accepting signals
    signalfd4(2) - create a file descriptor for accepting signals
    signbit(3) - test sign of a real floating-point number
    signgam(3) - log gamma function
    significand(3) - get mantissa of floating-point number
    significandf(3) - get mantissa of floating-point number
    significandl(3) - get mantissa of floating-point number
    sigorset(3) - POSIX signal set operations.
    sigpause(3) - atomically release blocked signals and wait for interrupt
    sigpending(2) - examine pending signals
    sigprocmask(2) - examine and change blocked signals
    sigqueue(2) - queue a signal and data to a process
    sigqueue(3) - queue a signal and data to a process
    sigrelse(3) - System V signal API
    sigreturn(2) - return from signal handler and cleanup stack frame
    sigset(3) - System V signal API
    sigsetjmp(3) - save stack context for nonlocal goto
    sigsetmask(3) - BSD signal API
    sigsetops(3) - POSIX signal set operations.
    sigstack(3) - set and/or get signal stack context
    sigsuspend(2) - wait for a signal
    sigtimedwait(2) - synchronously wait for queued signals
    sigvec(3) - BSD signal API
    sigwait(3) - wait for a signal
    sigwaitinfo(2) - synchronously wait for queued signals
    sin(3) - sine function
    sincos(3) - calculate sin and cos simultaneously
    sincosf(3) - calculate sin and cos simultaneously
    sincosl(3) - calculate sin and cos simultaneously
    sinf(3) - sine function
    sinh(3) - hyperbolic sine function
    sinhf(3) - hyperbolic sine function
    sinhl(3) - hyperbolic sine function
    sinl(3) - sine function
    sk98lin(4) - Marvell/SysKonnect Gigabit Ethernet driver v6.21
    slabinfo(5) - kernel slab allocator statistics
    sleep(3) - sleep for the specified number of seconds
    snprintf(3) - formatted output conversion
    sockatmark(3) - determine whether socket is at out-of-band mark
    socket(2) - create an endpoint for communication
    socket(7) - Linux socket interface
    socketcall(2) - socket system calls
    socketpair(2) - create a pair of connected sockets
    splice(2) - splice data to/from a pipe
    sprintf(3) - formatted output conversion
    spu_create(2) - create a new spu context
    spufs(7) - SPU file system
    spu_run(2) - execute an SPU context
    sqrt(3) - square root function
    sqrtf(3) - square root function
    sqrtl(3) - square root function
    srand(3) - pseudo-random number generator
    srand48(3) - generate uniformly distributed pseudo-random numbers
    srand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
    srandom(3) - random number generator
    srandom_r(3) - reentrant random number generator
    sscanf(3) - input format conversion
    ssetmask(2) - manipulation of signal mask (obsolete)
    ssignal(3) - software signal facility
    st(4) - SCSI tape device
    standards(7) - C and UNIX Standards
    stat(2) - get file status
    stat64(2) - get file status
    statfs(2) - get file system statistics
    statfs64(2) - get file system statistics
    statvfs(2) - get file system statistics
    statvfs(3) - get file system statistics
    stdarg(3) - variable argument lists
    stderr(3) - standard I/O streams
    stdin(3) - standard I/O streams
    stdio(3) - standard input/output library functions
    stdio_ext(3) - interfaces to stdio FILE structure
    stdout(3) - standard I/O streams
    stime(2) - set time
    stpcpy(3) - copy a string returning a pointer to its end
    stpncpy(3) - copy a fixed-size string, returning a pointer to its end
    strcasecmp(3) - compare two strings ignoring case
    strcasestr(3) - locate a substring
    strcat(3) - concatenate two strings
    strchr(3) - locate character in string
    strchrnul(3) - locate character in string
    strcmp(3) - compare two strings
    strcoll(3) - compare two strings using the current locale
    strcpy(3) - copy a string
    strcspn(3) - search a string for a set of bytes
    strdup(3) - duplicate a string
    strdupa(3) - duplicate a string
    strerror(3) - return string describing error number
    strerror_r(3) - return string describing error number
    strfmon(3) - convert monetary value to a string
    strfry(3) - randomize a string
    strftime(3) - format date and time
    string(3) - string operations
    strlen(3) - calculate the length of a string
    strncasecmp(3) - compare two strings ignoring case
    strncat(3) - concatenate two strings
    strncmp(3) - compare two strings
    strncpy(3) - copy a string
    strndup(3) - duplicate a string
    strndupa(3) - duplicate a string
    strnlen(3) - determine the length of a fixed-size string
    strpbrk(3) - search a string for any of a set of bytes
    strptime(3) - convert a string representation of time to a time tm structure
    strrchr(3) - locate character in string
    strsep(3) - extract token from string
    strsignal(3) - return string describing signal
    strspn(3) - search a string for a set of bytes
    strstr(3) - locate a substring
    strtod(3) - convert ASCII string to floating-point number
    strtof(3) - convert ASCII string to floating-point number
    strtoimax(3) - convert string to integer
    strtok(3) - extract tokens from strings
    strtok_r(3) - extract tokens from strings
    strtol(3) - convert a string to a long integer
    strtold(3) - convert ASCII string to floating-point number
    strtoll(3) - convert a string to a long integer
    strtoq(3) - convert a string to a long integer
    strtoul(3) - convert a string to an unsigned long integer
    strtoull(3) - convert a string to an unsigned long integer
    strtoumax(3) - convert string to integer
    strtouq(3) - convert a string to an unsigned long integer
    strverscmp(3) - compare two version strings
    strxfrm(3) - string transformation
    stty(2) - unimplemented system calls
    subpage_prot(2) - define a subpage protection for an address range
    suffixes(7) - list of file suffixes
    svc_destroy(3) - library routines for remote procedure calls
    svcerr_auth(3) - library routines for remote procedure calls
    svcerr_decode(3) - library routines for remote procedure calls
    svcerr_noproc(3) - library routines for remote procedure calls
    svcerr_noprog(3) - library routines for remote procedure calls
    svcerr_progvers(3) - library routines for remote procedure calls
    svcerr_systemerr(3) - library routines for remote procedure calls
    svcerr_weakauth(3) - library routines for remote procedure calls
    svcfd_create(3) - library routines for remote procedure calls
    svc_freeargs(3) - library routines for remote procedure calls
    svc_getargs(3) - library routines for remote procedure calls
    svc_getcaller(3) - library routines for remote procedure calls
    svc_getreq(3) - library routines for remote procedure calls
    svc_getreqset(3) - library routines for remote procedure calls
    svcraw_create(3) - library routines for remote procedure calls
    svc_register(3) - library routines for remote procedure calls
    svc_run(3) - library routines for remote procedure calls
    svc_sendreply(3) - library routines for remote procedure calls
    svctcp_create(3) - library routines for remote procedure calls
    svcudp_bufcreate(3) - library routines for remote procedure calls
    svcudp_create(3) - library routines for remote procedure calls
    svc_unregister(3) - library routines for remote procedure calls
    svipc(7) - System V interprocess communication mechanisms
    swab(3) - swap adjacent bytes
    swapcontext(3) - manipulate user context
    swapoff(2) - start/stop swapping to file/device
    swapon(2) - start/stop swapping to file/device
    swprintf(3) - formatted wide-character output conversion
    symlink(2) - make a new name for a file
    symlink(7) - symbolic link handling
    symlinkat(2) - create a symbolic link relative to a directory file descriptor
    sync(2) - commit buffer cache to disk
    sync(8) - synchronize data on disk with memory
    sync_file_range2(2) - sync a file segment with disk
    sync_file_range(2) - sync a file segment with disk
    syncfs(2) - commit buffer cache to disk
    _syscall(2) - invoking a system call without library support (OBSOLETE)
    syscall(2) - indirect system call
    syscalls(2) - Linux system calls
    sysconf(3) - get configuration information at run time
    _sysctl(2) - read/write system parameters
    sysctl(2) - read/write system parameters
    sys_errlist(3) - print a system error message
    sysfs(2) - get file system type information
    sysinfo(2) - returns information on overall system statistics
    syslog(2) - read and/or clear kernel message ring buffer; set console_loglevel
    syslog(3) - send messages to the system logger
    sys_nerr(3) - print a system error message
    system(3) - execute a shell command
    sysv_signal(3) - signal handling with System V semantics

top
    TAILQ_ENTRY(3) - implementations of lists, tail queues, and circular queues
    TAILQ_HEAD(3) - implementations of lists, tail queues, and circular queues
    TAILQ_INIT(3) - implementations of lists, tail queues, and circular queues
    TAILQ_INSERT_AFTER(3) - implementations of lists, tail queues, and circular queues
    TAILQ_INSERT_HEAD(3) - implementations of lists, tail queues, and circular queues
    TAILQ_INSERT_TAIL(3) - implementations of lists, tail queues, and circular queues
    TAILQ_REMOVE(3) - implementations of lists, tail queues, and circular queues
    tan(3) - tangent function
    tanf(3) - tangent function
    tanh(3) - hyperbolic tangent function
    tanhf(3) - hyperbolic tangent function
    tanhl(3) - hyperbolic tangent function
    tanl(3) - tangent function
    tcdrain(3) - get and set terminal attributes, line control, get and set baud rate
    tcflow(3) - get and set terminal attributes, line control, get and set baud rate
    tcflush(3) - get and set terminal attributes, line control, get and set baud rate
    tcgetattr(3) - get and set terminal attributes, line control, get and set baud rate
    tcgetpgrp(3) - get and set terminal foreground process group
    tcgetsid(3) - get session ID
    tcp(7) - TCP protocol
    tcsendbreak(3) - get and set terminal attributes, line control, get and set baud rate
    tcsetattr(3) - get and set terminal attributes, line control, get and set baud rate
    tcsetpgrp(3) - get and set terminal foreground process group
    tdelete(3) - manage a binary tree
    tdestroy(3) - manage a binary tree
    tee(2) - duplicating pipe content
    telldir(3) - return current location in directory stream
    tempnam(3) - create a name for a temporary file
    termcap(5) - terminal capability database
    termio(7) - System V terminal driver interface
    termios(3) - get and set terminal attributes, line control, get and set baud rate
    tfind(3) - manage a binary tree
    tgamma(3) - true gamma function
    tgammaf(3) - true gamma function
    tgammal(3) - true gamma function
    tgkill(2) - send a signal to a thread
    time(1) - time a simple command or give resource usage
    time(2) - get time in seconds
    time(7) - overview of time and timers
    timegm(3) - inverses of gmtime and localtime
    timelocal(3) - inverses of gmtime and localtime
    timeradd(3) - timeval operations
    timerclear(3) - timeval operations
    timercmp(3) - timeval operations
    timer_create(2) - create a POSIX per-process timer
    timer_delete(2) - delete a POSIX per-process timer
    timerfd_create(2) - timers that notify via file descriptors
    timerfd_gettime(2) - timers that notify via file descriptors
    timerfd_settime(2) - timers that notify via file descriptors
    timer_getoverrun(2) - get overrun count for a POSIX per-process timer
    timer_gettime(2) - arm/disarm and fetch state of POSIX per-process timer
    timerisset(3) - timeval operations
    timer_settime(2) - arm/disarm and fetch state of POSIX per-process timer
    timersub(3) - timeval operations
    times(2) - get process times
    timezone(3) - initialize time conversion information
    tis-620(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
    tkill(2) - send a signal to a thread
    tmpfile(3) - create a temporary file
    tmpnam(3) - create a name for a temporary file
    tmpnam_r(3) - create a name for a temporary file
    toascii(3) - convert character to ASCII
    tolower(3) - convert letter to upper or lower case
    toupper(3) - convert letter to upper or lower case
    towctrans(3) - wide-character transliteration
    towlower(3) - convert a wide character to lowercase
    towupper(3) - convert a wide character to uppercase
    trunc(3) - round to integer, toward zero
    truncate(2) - truncate a file to a specified length
    truncate64(2) - truncate a file to a specified length
    truncf(3) - round to integer, toward zero
    truncl(3) - round to integer, toward zero
    tsearch(3) - manage a binary tree
    tty(4) - controlling terminal
    tty_ioctl(4) - ioctls for terminals and serial lines
    ttyname(3) - return name of a terminal
    ttyname_r(3) - return name of a terminal
    ttyS(4) - serial terminal lines
    ttyslot(3) - find the slot of the current user's terminal in some file
    ttytype(5) - terminal device to default terminal type mapping
    tuxcall(2) - unimplemented system calls
    twalk(3) - manage a binary tree
    tzfile(5) - timezone information
    tzname(3) - initialize time conversion information
    tzselect(8) - select a timezone
    tzset(3) - initialize time conversion information

top
    ualarm(3) - schedule signal after given number of microseconds
    udp(7) - User Datagram Protocol for IPv4
    udplite(7) - Lightweight User Datagram Protocol
    ugetrlimit(2) - get/set resource limits
    ulckpwdf(3) - get shadow password file entry
    ulimit(3) - get and set user limits
    umask(2) - set file mode creation mask
    umount2(2) - unmount file system
    umount(2) - unmount file system
    uname(2) - get name and information about current kernel
    undocumented(3) - undocumented library functions
    ungetc(3) - input of characters and strings
    ungetwc(3) - push back a wide character onto a FILE stream
    unicode(7) - universal character set
    unimplemented(2) - unimplemented system calls
    units(7) - decimal and binary prefixes
    unix(7) - sockets for local interprocess communication
    unlink(2) - delete a name and possibly the file it refers to
    unlinkat(2) - remove a directory entry relative to a directory file descriptor
    unlocked_stdio(3) - nonlocking stdio functions
    unlockpt(3) - unlock a pseudoterminal master/slave pair
    unsetenv(3) - change or add an environment variable
    unshare(2) - disassociate parts of the process execution context
    updwtmp(3) - append an entry to the wtmp file
    updwtmpx(3) - append an entry to the wtmp file
    urandom(4) - kernel random number source devices
    uri(7) - uniform resource identifier (URI), including a URL or URN
    url(7) - uniform resource identifier (URI), including a URL or URN
    urn(7) - uniform resource identifier (URI), including a URL or URN
    uselib(2) - load shared library
    usleep(3) - suspend execution for microsecond intervals
    ustat(2) - get file system statistics
    utf-8(7) - an ASCII compatible multibyte Unicode encoding
    utf8(7) - an ASCII compatible multibyte Unicode encoding
    utime(2) - change file last access and modification times
    utimensat(2) - change file timestamps with nanosecond precision
    utimes(2) - change file last access and modification times
    utmp(5) - login records
    utmpname(3) - access utmp file entries
    utmpx(5) - login records
    utmpxname(3) - access utmp file entries

top
    va_arg(3) - variable argument lists
    va_copy(3) - variable argument lists
    va_end(3) - variable argument lists
    valloc(3) - allocate aligned memory
    vasprintf(3) - print to allocated string
    va_start(3) - variable argument lists
    vcs(4) - virtual console memory
    vcsa(4) - virtual console memory
    vdprintf(3) - print to a file descriptor
    verr(3) - formatted error messages
    verrx(3) - formatted error messages
    versionsort(3) - scan a directory for matching entries
    vfork(2) - create a child process and block parent
    vfprintf(3) - formatted output conversion
    vfscanf(3) - input format conversion
    vfwprintf(3) - formatted wide-character output conversion
    vhangup(2) - virtually hangup the current tty
    vlimit(3) - get/set resource limits
    vm86(2) - enter virtual 8086 mode
    vm86old(2) - enter virtual 8086 mode
    vmsplice(2) - splice user pages into a pipe
    vprintf(3) - formatted output conversion
    vscanf(3) - input format conversion
    vserver(2) - unimplemented system calls
    vsnprintf(3) - formatted output conversion
    vsprintf(3) - formatted output conversion
    vsscanf(3) - input format conversion
    vswprintf(3) - formatted wide-character output conversion
    vsyslog(3) - send messages to the system logger
    vtimes(3) - get resource usage
    vwarn(3) - formatted error messages
    vwarnx(3) - formatted error messages
    vwprintf(3) - formatted wide-character output conversion

top
    wait(2) - wait for process to change state
    wait3(2) - wait for process to change state, BSD style
    wait4(2) - wait for process to change state, BSD style
    waitid(2) - wait for process to change state
    waitpid(2) - wait for process to change state
    warn(3) - formatted error messages
    warnx(3) - formatted error messages
    wavelan(4) - AT&T GIS WaveLAN ISA device driver
    wcpcpy(3) - copy a wide-character string, returning a pointer to its end
    wcpncpy(3) - copy a fixed-size string of wide characters, returning a pointer to its end
    wcrtomb(3) - convert a wide character to a multibyte sequence
    wcscasecmp(3) - compare two wide-character strings, ignoring case
    wcscat(3) - concatenate two wide-character strings
    wcschr(3) - search a wide character in a wide-character string
    wcscmp(3) - compare two wide-character strings
    wcscpy(3) - copy a wide-character string
    wcscspn(3) - search a wide-character string for any of a set of wide characters
    wcsdup(3) - duplicate a wide-character string
    wcslen(3) - determine the length of a wide-character string
    wcsncasecmp(3) - compare two fixed-size wide-character strings, ignoring case
    wcsncat(3) - concatenate two wide-character strings
    wcsncmp(3) - compare two fixed-size wide-character strings
    wcsncpy(3) - copy a fixed-size string of wide characters
    wcsnlen(3) - determine the length of a fixed-size wide-character string
    wcsnrtombs(3) - convert a wide-character string to a multibyte string
    wcspbrk(3) - search a wide-character string for any of a set of wide characters
    wcsrchr(3) - search a wide character in a wide-character string
    wcsrtombs(3) - convert a wide-character string to a multibyte string
    wcsspn(3) - advance in a wide-character string, skipping any of a set of wide characters
    wcsstr(3) - locate a substring in a wide-character string
    wcstoimax(3) - convert wide-character string to integer
    wcstok(3) - split wide-character string into tokens
    wcstombs(3) - convert a wide-character string to a multibyte string
    wcstoumax(3) - convert wide-character string to integer
    wcswidth(3) - determine columns needed for a fixed-size wide-character string
    wctob(3) - try to represent a wide character as a single byte
    wctomb(3) - convert a wide character to a multibyte sequence
    wctrans(3) - wide-character translation mapping
    wctype(3) - wide-character classification
    wcwidth(3) - determine columns needed for a wide character
    wmemchr(3) - search a wide character in a wide-character array
    wmemcmp(3) - compare two arrays of wide-characters
    wmemcpy(3) - copy an array of wide-characters
    wmemmove(3) - copy an array of wide-characters
    wmempcpy(3) - copy memory area
    wmemset(3) - fill an array of wide-characters with a constant wide character
    wordexp(3) - perform word expansion like a posix-shell
    wordfree(3) - perform word expansion like a posix-shell
    wprintf(3) - formatted wide-character output conversion
    write(2) - write to a file descriptor
    writev(2) - read or write data into multiple buffers
    wtmp(5) - login records

top
    x25(7) - ITU-T X.25 / ISO-8208 protocol interface.
    xcrypt(3) - RFS password encryption
    xdecrypt(3) - RFS password encryption
    xdr(3) - library routines for external data representation
    xdr_accepted_reply(3) - library routines for remote procedure calls
    xdr_array(3) - library routines for external data representation
    xdr_authunix_parms(3) - library routines for remote procedure calls
    xdr_bool(3) - library routines for external data representation
    xdr_bytes(3) - library routines for external data representation
    xdr_callhdr(3) - library routines for remote procedure calls
    xdr_callmsg(3) - library routines for remote procedure calls
    xdr_char(3) - library routines for external data representation
    xdr_destroy(3) - library routines for external data representation
    xdr_double(3) - library routines for external data representation
    xdr_enum(3) - library routines for external data representation
    xdr_float(3) - library routines for external data representation
    xdr_free(3) - library routines for external data representation
    xdr_getpos(3) - library routines for external data representation
    xdr_inline(3) - library routines for external data representation
    xdr_int(3) - library routines for external data representation
    xdr_long(3) - library routines for external data representation
    xdrmem_create(3) - library routines for external data representation
    xdr_opaque(3) - library routines for external data representation
    xdr_opaque_auth(3) - library routines for remote procedure calls
    xdr_pmap(3) - library routines for remote procedure calls
    xdr_pmaplist(3) - library routines for remote procedure calls
    xdr_pointer(3) - library routines for external data representation
    xdrrec_create(3) - library routines for external data representation
    xdrrec_endofrecord(3) - library routines for external data representation
    xdrrec_eof(3) - library routines for external data representation
    xdrrec_skiprecord(3) - library routines for external data representation
    xdr_reference(3) - library routines for external data representation
    xdr_rejected_reply(3) - library routines for remote procedure calls
    xdr_replymsg(3) - library routines for remote procedure calls
    xdr_setpos(3) - library routines for external data representation
    xdr_short(3) - library routines for external data representation
    xdrstdio_create(3) - library routines for external data representation
    xdr_string(3) - library routines for external data representation
    xdr_u_char(3) - library routines for external data representation
    xdr_u_int(3) - library routines for external data representation
    xdr_u_long(3) - library routines for external data representation
    xdr_union(3) - library routines for external data representation
    xdr_u_short(3) - library routines for external data representation
    xdr_vector(3) - library routines for external data representation
    xdr_void(3) - library routines for external data representation
    xdr_wrapstring(3) - library routines for external data representation
    xencrypt(3) - RFS password encryption
    xprt_register(3) - library routines for remote procedure calls
    xprt_unregister(3) - library routines for remote procedure calls

top
    y0(3) - Bessel functions of the second kind
    y0f(3) - Bessel functions of the second kind
    y0l(3) - Bessel functions of the second kind
    y1(3) - Bessel functions of the second kind
    y1f(3) - Bessel functions of the second kind
    y1l(3) - Bessel functions of the second kind
    yn(3) - Bessel functions of the second kind
    ynf(3) - Bessel functions of the second kind
    ynl(3) - Bessel functions of the second kind

top
    zdump(8) - timezone dumper
    zero(4) - data sink
    zic(8) - timezone compiler


Linux man-pages: list of all pages, by section

All pages, by section

Jump to section: 1 2 3 4 5 6 7 8

Section 1

 top
getent(1) - get entries from Name Service Switch libraries
intro(1) - introduction to user commands
ldd(1) - print shared library dependencies
time(1) - time a simple command or give resource usage

Section 2

 top
accept(2) - accept a connection on a socket
accept4(2) - accept a connection on a socket
access(2) - check real user's permissions for a file
acct(2) - switch process accounting on or off
add_key(2) - add a key to the kernel's key management facility
adjtimex(2) - tune kernel clock
afs_syscall(2) - unimplemented system calls
alarm(2) - set an alarm clock for delivery of a signal
alloc_hugepages(2) - allocate or free huge pages
arch_prctl(2) - set architecture-specific thread state
arm_fadvise(2) - predeclare an access pattern for file data
arm_fadvise64_64(2) - predeclare an access pattern for file data
arm_sync_file_range(2) - sync a file segment with disk
bdflush(2) - start, flush, or tune buffer-dirty-flush daemon
bind(2) - bind a name to a socket
break(2) - unimplemented system calls
brk(2) - change data segment size
cacheflush(2) - flush contents of instruction and/or data cache
capget(2) - set/get capabilities of thread(s)
capset(2) - set/get capabilities of thread(s)
chdir(2) - change working directory
chmod(2) - change permissions of a file
chown(2) - change ownership of a file
chown32(2) - change ownership of a file
chroot(2) - change root directory
clock_getres(2) - clock and time functions
clock_gettime(2) - clock and time functions
clock_nanosleep(2) - high-resolution sleep with specifiable clock
clock_settime(2) - clock and time functions
__clone2(2) - create a child process
clone2(2) - create a child process
clone(2) - create a child process
close(2) - close a file descriptor
connect(2) - initiate a connection on a socket
creat(2) - open and possibly create a file or device
create_module(2) - create a loadable module entry
delete_module(2) - unload a kernel module
dup2(2) - duplicate a file descriptor
dup(2) - duplicate a file descriptor
dup3(2) - duplicate a file descriptor
epoll_create1(2) - open an epoll file descriptor
epoll_create(2) - open an epoll file descriptor
epoll_ctl(2) - control interface for an epoll descriptor
epoll_pwait(2) - wait for an I/O event on an epoll file descriptor
epoll_wait(2) - wait for an I/O event on an epoll file descriptor
eventfd2(2) - create a file descriptor for event notification
eventfd(2) - create a file descriptor for event notification
execve(2) - execute program
_exit(2) - terminate the calling process
_Exit(2) - terminate the calling process
exit(2) - terminate the calling process
exit_group(2) - exit all threads in a process
faccessat(2) - check user's permissions of a file relative to a directory file descriptor
fadvise64(2) - predeclare an access pattern for file data
fadvise64_64(2) - predeclare an access pattern for file data
fallocate(2) - manipulate file space
fchdir(2) - change working directory
fchmod(2) - change permissions of a file
fchmodat(2) - change permissions of a file relative to a directory file descriptor
fchown(2) - change ownership of a file
fchown32(2) - change ownership of a file
fchownat(2) - change ownership of a file relative to a directory file descriptor
fcntl(2) - manipulate file descriptor
fcntl64(2) - manipulate file descriptor
fdatasync(2) - synchronize a file's in-core state with storage device
fgetxattr(2) - retrieve an extended attribute value
flistxattr(2) - list extended attribute names
flock(2) - apply or remove an advisory lock on an open file
fork(2) - create a child process
free_hugepages(2) - allocate or free huge pages
fremovexattr(2) - remove an extended attribute
fsetxattr(2) - set an extended attribute value
fstat(2) - get file status
fstat64(2) - get file status
fstatat(2) - get file status relative to a directory file descriptor
fstatat64(2) - get file status relative to a directory file descriptor
fstatfs(2) - get file system statistics
fstatfs64(2) - get file system statistics
fstatvfs(2) - get file system statistics
fsync(2) - synchronize a file's in-core state with storage device
ftruncate(2) - truncate a file to a specified length
ftruncate64(2) - truncate a file to a specified length
futex(2) - fast user-space locking
futimesat(2) - change timestamps of a file relative to a directory file descriptor
getcontext(2) - get or set the user context
getcpu(2) - determine CPU and NUMA node on which the calling thread is running
getcwd(2) - get current working directory
getdents(2) - get directory entries
getdents64(2) - get directory entries
getdomainname(2) - get/set NIS domain name
getdtablesize(2) - get descriptor table size
getegid(2) - get group identity
getegid32(2) - get group identity
geteuid(2) - get user identity
geteuid32(2) - get user identity
getgid(2) - get group identity
getgid32(2) - get group identity
getgroups(2) - get/set list of supplementary group IDs
getgroups32(2) - get/set list of supplementary group IDs
gethostid(2) - get or set the unique identifier of the current host
gethostname(2) - get/set hostname
getitimer(2) - get or set value of an interval timer
get_kernel_syms(2) - retrieve exported kernel and module symbols
get_mempolicy(2) - retrieve NUMA memory policy for a process
getpagesize(2) - get memory page size
getpeername(2) - get name of connected peer socket
getpgid(2) - set/get process group
getpgrp(2) - set/get process group
getpid(2) - get process identification
getpmsg(2) - unimplemented system calls
getppid(2) - get process identification
getpriority(2) - get/set program scheduling priority
getresgid(2) - get real, effective and saved user/group IDs
getresgid32(2) - get real, effective and saved user/group IDs
getresuid(2) - get real, effective and saved user/group IDs
getresuid32(2) - get real, effective and saved user/group IDs
getrlimit(2) - get/set resource limits
get_robust_list(2) - get/set list of robust futexes
getrusage(2) - get resource usage
getsid(2) - get session ID
getsockname(2) - get socket name
getsockopt(2) - get and set options on sockets
get_thread_area(2) - get a thread-local storage (TLS) area
gettid(2) - get thread identification
gettimeofday(2) - get / set time
getuid(2) - get user identity
getuid32(2) - get user identity
getxattr(2) - retrieve an extended attribute value
gtty(2) - unimplemented system calls
idle(2) - make process 0 idle
inb(2) - port I/O
inb_p(2) - port I/O
init_module(2) - load a kernel module
inl(2) - port I/O
inl_p(2) - port I/O
inotify_add_watch(2) - add a watch to an initialized inotify instance
inotify_init1(2) - initialize an inotify instance
inotify_init(2) - initialize an inotify instance
inotify_rm_watch(2) - remove an existing watch from an inotify instance
insb(2) - port I/O
insl(2) - port I/O
insw(2) - port I/O
intro(2) - introduction to system calls
inw(2) - port I/O
inw_p(2) - port I/O
io_cancel(2) - cancel an outstanding asynchronous I/O operation
ioctl(2) - control device
ioctl_list(2) - list of ioctl calls in Linux/i386 kernel
io_destroy(2) - destroy an asynchronous I/O context
io_getevents(2) - read asynchronous I/O events from the completion queue
ioperm(2) - set port input/output permissions
iopl(2) - change I/O privilege level
ioprio_get(2) - get/set I/O scheduling class and priority
ioprio_set(2) - get/set I/O scheduling class and priority
io_setup(2) - create an asynchronous I/O context
io_submit(2) - submit asynchronous I/O blocks for processing
ipc(2) - System V IPC system calls
kexec_load(2) - load a new kernel for later execution
keyctl(2) - manipulate the kernel's key management facility
kill(2) - send signal to a process
killpg(2) - send signal to a process group
lchown(2) - change ownership of a file
lchown32(2) - change ownership of a file
lgetxattr(2) - retrieve an extended attribute value
link(2) - make a new name for a file
linkat(2) - create a file link relative to directory file descriptors
listen(2) - listen for connections on a socket
listxattr(2) - list extended attribute names
llistxattr(2) - list extended attribute names
_llseek(2) - reposition read/write file offset
llseek(2) - reposition read/write file offset
lock(2) - unimplemented system calls
lookup_dcookie(2) - return a directory entry's path
lremovexattr(2) - remove an extended attribute
lseek(2) - reposition read/write file offset
lsetxattr(2) - set an extended attribute value
lstat(2) - get file status
lstat64(2) - get file status
madvise1(2) - unimplemented system calls
madvise(2) - give advice about use of memory
mbind(2) - set memory policy for a memory range
migrate_pages(2) - move all pages in a process to another set of nodes
mincore(2) - determine whether pages are resident in memory
mkdir(2) - create a directory
mkdirat(2) - create a directory relative to a directory file descriptor
mknod(2) - create a special or ordinary file
mknodat(2) - create a special or ordinary file relative to a directory file descriptor
mlock(2) - lock and unlock memory
mlockall(2) - lock and unlock memory
mmap2(2) - map files or devices into memory
mmap(2) - map or unmap files or devices into memory
modify_ldt(2) - get or set ldt
mount(2) - mount file system
move_pages(2) - move individual pages of a process to another node
mprotect(2) - set protection on a region of memory
mpx(2) - unimplemented system calls
mq_getsetattr(2) - get/set message queue attributes
mq_notify(2) - register for notification when a message is available
mq_open(2) - open a message queue
mq_timedreceive(2) - receive a message from a message queue
mq_timedsend(2) - send a message to a message queue
mq_unlink(2) - remove a message queue
mremap(2) - remap a virtual memory address
msgctl(2) - message control operations
msgget(2) - get a message queue identifier
msgop(2) - message operations
msgrcv(2) - message operations
msgsnd(2) - message operations
msync(2) - synchronize a file with a memory map
munlock(2) - lock and unlock memory
munlockall(2) - lock and unlock memory
munmap(2) - map or unmap files or devices into memory
nanosleep(2) - high-resolution sleep
_newselect(2) - synchronous I/O multiplexing
nfsservctl(2) - syscall interface to kernel nfs daemon
nice(2) - change process priority
oldfstat(2) - get file status
oldlstat(2) - get file status
oldolduname(2) - get name and information about current kernel
oldstat(2) - get file status
olduname(2) - get name and information about current kernel
open(2) - open and possibly create a file or device
openat(2) - open a file relative to a directory file descriptor
outb(2) - port I/O
outb_p(2) - port I/O
outl(2) - port I/O
outl_p(2) - port I/O
outsb(2) - port I/O
outsl(2) - port I/O
outsw(2) - port I/O
outw(2) - port I/O
outw_p(2) - port I/O
pause(2) - wait for signal
pciconfig_iobase(2) - pci device information handling
pciconfig_read(2) - pci device information handling
pciconfig_write(2) - pci device information handling
personality(2) - set the process execution domain
phys(2) - unimplemented system calls
pipe2(2) - create pipe
pipe(2) - create pipe
pivot_root(2) - change the root file system
poll(2) - wait for some event on a file descriptor
posix_fadvise(2) - predeclare an access pattern for file data
ppoll(2) - wait for some event on a file descriptor
prctl(2) - operations on a process
pread(2) - read from or write to a file descriptor at a given offset
pread64(2) - read from or write to a file descriptor at a given offset
preadv(2) - read or write data into multiple buffers
prlimit(2) - get/set resource limits
process_vm_readv(2) - transfer data between process address spaces
process_vm_writev(2) - transfer data between process address spaces
prof(2) - unimplemented system calls
pselect(2) - synchronous I/O multiplexing
pselect6(2) - synchronous I/O multiplexing
ptrace(2) - process trace
putpmsg(2) - unimplemented system calls
pwrite(2) - read from or write to a file descriptor at a given offset
pwrite64(2) - read from or write to a file descriptor at a given offset
pwritev(2) - read or write data into multiple buffers
query_module(2) - query the kernel for various bits pertaining to modules
quotactl(2) - manipulate disk quotas
read(2) - read from a file descriptor
readahead(2) - perform file readahead into page cache
readdir(2) - read directory entry
readlink(2) - read value of a symbolic link
readlinkat(2) - read value of a symbolic link relative to a directory file descriptor
readv(2) - read or write data into multiple buffers
reboot(2) - reboot or enable/disable Ctrl-Alt-Del
recv(2) - receive a message from a socket
recvfrom(2) - receive a message from a socket
recvmmsg(2) - receive multiple messages on a socket
recvmsg(2) - receive a message from a socket
remap_file_pages(2) - create a nonlinear file mapping
removexattr(2) - remove an extended attribute
rename(2) - change the name or location of a file
renameat(2) - rename a file relative to directory file descriptors
request_key(2) - request a key from the kernel's key management facility
rmdir(2) - delete a directory
rt_sigaction(2) - examine and change a signal action
rt_sigpending(2) - examine pending signals
rt_sigprocmask(2) - examine and change blocked signals
rt_sigqueueinfo(2) - queue a signal and data
rt_sigreturn(2) - return from signal handler and cleanup stack frame
rt_sigsuspend(2) - wait for a signal
rt_sigtimedwait(2) - synchronously wait for queued signals
rt_tgsigqueueinfo(2) - queue a signal and data
s390_runtime_instr(2) - enable/disable s390 CPU run-time instrumentation
sbrk(2) - change data segment size
sched_getaffinity(2) -  set and get a process's CPU affinity mask
sched_getparam(2) - set and get scheduling parameters
sched_get_priority_max(2) - get static priority range
sched_get_priority_min(2) - get static priority range
sched_getscheduler(2) - set and get scheduling policy/parameters
sched_rr_get_interval(2) - get the SCHED_RR interval for the named process
sched_setaffinity(2) -  set and get a process's CPU affinity mask
sched_setparam(2) - set and get scheduling parameters
sched_setscheduler(2) - set and get scheduling policy/parameters
sched_yield(2) - yield the processor
security(2) - unimplemented system calls
select(2) - synchronous I/O multiplexing
select_tut(2) - synchronous I/O multiplexing
semctl(2) - semaphore control operations
semget(2) - get a semaphore set identifier
semop(2) - semaphore operations
semtimedop(2) - semaphore operations
send(2) - send a message on a socket
sendfile(2) - transfer data between file descriptors
sendfile64(2) - transfer data between file descriptors
sendmmsg(2) - send multiple messages on a socket
sendmsg(2) - send a message on a socket
sendto(2) - send a message on a socket
setcontext(2) - get or set the user context
setdomainname(2) - get/set NIS domain name
setegid(2) - set effective user or group ID
seteuid(2) - set effective user or group ID
setfsgid(2) - set group identity used for file system checks
setfsgid32(2) - set group identity used for file system checks
setfsuid(2) - set user identity used for file system checks
setfsuid32(2) - set user identity used for file system checks
setgid(2) - set group identity
setgid32(2) - set group identity
setgroups(2) - get/set list of supplementary group IDs
setgroups32(2) - get/set list of supplementary group IDs
sethostid(2) - get or set the unique identifier of the current host
sethostname(2) - get/set hostname
setitimer(2) - get or set value of an interval timer
set_mempolicy(2) - set default NUMA memory policy for a process and its children
setns(2) - reassociate thread with a namespace
setpgid(2) - set/get process group
setpgrp(2) - set/get process group
setpriority(2) - get/set program scheduling priority
setregid(2) - set real and/or effective user or group ID
setregid32(2) - set real and/or effective user or group ID
setresgid(2) - set real, effective and saved user or group ID
setresgid32(2) - set real, effective and saved user or group ID
setresuid(2) - set real, effective and saved user or group ID
setresuid32(2) - set real, effective and saved user or group ID
setreuid(2) - set real and/or effective user or group ID
setreuid32(2) - set real and/or effective user or group ID
setrlimit(2) - get/set resource limits
set_robust_list(2) - get/set list of robust futexes
setsid(2) - creates a session and sets the process group ID
setsockopt(2) - get and set options on sockets
set_thread_area(2) - set a thread local storage (TLS) area
set_tid_address(2) - set pointer to thread ID
settimeofday(2) - get / set time
setuid(2) - set user identity
setuid32(2) - set user identity
setup(2) - setup devices and file systems, mount root file system
setxattr(2) - set an extended attribute value
sgetmask(2) - manipulation of signal mask (obsolete)
shmat(2) - shared memory operations
shmctl(2) - shared memory control
shmdt(2) - shared memory operations
shmget(2) - allocates a shared memory segment
shmop(2) - shared memory operations
shutdown(2) - shut down part of a full-duplex connection
sigaction(2) - examine and change a signal action
sigaltstack(2) - set and/or get signal stack context
signal(2) - ANSI C signal handling
signalfd(2) - create a file descriptor for accepting signals
signalfd4(2) - create a file descriptor for accepting signals
sigpending(2) - examine pending signals
sigprocmask(2) - examine and change blocked signals
sigqueue(2) - queue a signal and data to a process
sigreturn(2) - return from signal handler and cleanup stack frame
sigsuspend(2) - wait for a signal
sigtimedwait(2) - synchronously wait for queued signals
sigwaitinfo(2) - synchronously wait for queued signals
socket(2) - create an endpoint for communication
socketcall(2) - socket system calls
socketpair(2) - create a pair of connected sockets
splice(2) - splice data to/from a pipe
spu_create(2) - create a new spu context
spu_run(2) - execute an SPU context
ssetmask(2) - manipulation of signal mask (obsolete)
stat(2) - get file status
stat64(2) - get file status
statfs(2) - get file system statistics
statfs64(2) - get file system statistics
statvfs(2) - get file system statistics
stime(2) - set time
stty(2) - unimplemented system calls
subpage_prot(2) - define a subpage protection for an address range
swapoff(2) - start/stop swapping to file/device
swapon(2) - start/stop swapping to file/device
symlink(2) - make a new name for a file
symlinkat(2) - create a symbolic link relative to a directory file descriptor
sync(2) - commit buffer cache to disk
sync_file_range2(2) - sync a file segment with disk
sync_file_range(2) - sync a file segment with disk
syncfs(2) - commit buffer cache to disk
_syscall(2) - invoking a system call without library support (OBSOLETE)
syscall(2) - indirect system call
syscalls(2) - Linux system calls
_sysctl(2) - read/write system parameters
sysctl(2) - read/write system parameters
sysfs(2) - get file system type information
sysinfo(2) - returns information on overall system statistics
syslog(2) - read and/or clear kernel message ring buffer; set console_loglevel
tee(2) - duplicating pipe content
tgkill(2) - send a signal to a thread
time(2) - get time in seconds
timer_create(2) - create a POSIX per-process timer
timer_delete(2) - delete a POSIX per-process timer
timerfd_create(2) - timers that notify via file descriptors
timerfd_gettime(2) - timers that notify via file descriptors
timerfd_settime(2) - timers that notify via file descriptors
timer_getoverrun(2) - get overrun count for a POSIX per-process timer
timer_gettime(2) - arm/disarm and fetch state of POSIX per-process timer
timer_settime(2) - arm/disarm and fetch state of POSIX per-process timer
times(2) - get process times
tkill(2) - send a signal to a thread
truncate(2) - truncate a file to a specified length
truncate64(2) - truncate a file to a specified length
tuxcall(2) - unimplemented system calls
ugetrlimit(2) - get/set resource limits
umask(2) - set file mode creation mask
umount2(2) - unmount file system
umount(2) - unmount file system
uname(2) - get name and information about current kernel
unimplemented(2) - unimplemented system calls
unlink(2) - delete a name and possibly the file it refers to
unlinkat(2) - remove a directory entry relative to a directory file descriptor
unshare(2) - disassociate parts of the process execution context
uselib(2) - load shared library
ustat(2) - get file system statistics
utime(2) - change file last access and modification times
utimensat(2) - change file timestamps with nanosecond precision
utimes(2) - change file last access and modification times
vfork(2) - create a child process and block parent
vhangup(2) - virtually hangup the current tty
vm86(2) - enter virtual 8086 mode
vm86old(2) - enter virtual 8086 mode
vmsplice(2) - splice user pages into a pipe
vserver(2) - unimplemented system calls
wait(2) - wait for process to change state
wait3(2) - wait for process to change state, BSD style
wait4(2) - wait for process to change state, BSD style
waitid(2) - wait for process to change state
waitpid(2) - wait for process to change state
write(2) - write to a file descriptor
writev(2) - read or write data into multiple buffers

Section 3

 top
a64l(3) - convert between long and base-64
abort(3) - cause abnormal process termination
abs(3) - compute the absolute value of an integer
acos(3) - arc cosine function
acosf(3) - arc cosine function
acosh(3) - inverse hyperbolic cosine function
acoshf(3) - inverse hyperbolic cosine function
acoshl(3) - inverse hyperbolic cosine function
acosl(3) - arc cosine function
addmntent(3) - get file system descriptor file entry
addseverity(3) - introduce new severity classes
adjtime(3) - correct the time to synchronize the system clock
aio_cancel(3) - cancel an outstanding asynchronous I/O request
aio_error(3) - get error status of asynchronous I/O operation
aio_fsync(3) - asynchronous file synchronization
aio_init(3) - asynchronous I/O initialization
aio_read(3) - asynchronous read
aio_return(3) - get return status of asynchronous I/O operation
aio_suspend(3) - wait for asynchronous I/O operation or timeout
aio_write(3) - asynchronous write
aligned_alloc(3) - allocate aligned memory
alloca(3) - allocate memory that is automatically freed
alphasort(3) - scan a directory for matching entries
argz(3) - functions to handle an argz list
argz_add(3) - functions to handle an argz list
argz_add_sep(3) - functions to handle an argz list
argz_append(3) - functions to handle an argz list
argz_count(3) - functions to handle an argz list
argz_create(3) - functions to handle an argz list
argz_create_sep(3) - functions to handle an argz list
argz_delete(3) - functions to handle an argz list
argz_extract(3) - functions to handle an argz list
argz_insert(3) - functions to handle an argz list
argz_next(3) - functions to handle an argz list
argz_replace(3) - functions to handle an argz list
argz_stringify(3) - functions to handle an argz list
asctime(3) - transform date and time to broken-down time or ASCII
asctime_r(3) - transform date and time to broken-down time or ASCII
asin(3) - arc sine function
asinf(3) - arc sine function
asinh(3) - inverse hyperbolic sine function
asinhf(3) - inverse hyperbolic sine function
asinhl(3) - inverse hyperbolic sine function
asinl(3) - arc sine function
asprintf(3) - print to allocated string
assert(3) - abort the program if assertion is false
assert_perror(3) - test errnum and abort
atan2(3) - arc tangent function of two variables
atan2f(3) - arc tangent function of two variables
atan2l(3) - arc tangent function of two variables
atan(3) - arc tangent function
atanf(3) - arc tangent function
atanh(3) - inverse hyperbolic tangent function
atanhf(3) - inverse hyperbolic tangent function
atanhl(3) - inverse hyperbolic tangent function
atanl(3) - arc tangent function
atexit(3) - register a function to be called at normal process termination
atof(3) - convert a string to a double
atoi(3) - convert a string to an integer
atol(3) - convert a string to an integer
atoll(3) - convert a string to an integer
atoq(3) - convert a string to an integer
auth_destroy(3) - library routines for remote procedure calls
authnone_create(3) - library routines for remote procedure calls
authunix_create(3) - library routines for remote procedure calls
authunix_create_default(3) - library routines for remote procedure calls
backtrace(3) - support for application self-debugging
backtrace_symbols(3) - support for application self-debugging
backtrace_symbols_fd(3) - support for application self-debugging
basename(3) - parse pathname components
bcmp(3) - compare byte sequences
bcopy(3) - copy byte sequence
be16toh(3) - convert values between host and big-/little-endian byte order
be32toh(3) - convert values between host and big-/little-endian byte order
be64toh(3) - convert values between host and big-/little-endian byte order
bindresvport(3) - bind a socket to a privileged IP port
bsd_signal(3) - signal handling with BSD semantics
bsearch(3) - binary search of a sorted array
bstring(3) - byte string operations
btowc(3) - convert single byte to wide character
btree(3) - btree database access method
byteorder(3) - convert values between host and network byte order
bzero(3) - write zero-valued bytes
cabs(3) - absolute value of a complex number
cabsf(3) - absolute value of a complex number
cabsl(3) - absolute value of a complex number
cacos(3) - complex arc cosine
cacosf(3) - complex arc cosine
cacosh(3) - complex arc hyperbolic cosine
cacoshf(3) - complex arc hyperbolic cosine
cacoshl(3) - complex arc hyperbolic cosine
cacosl(3) - complex arc cosine
calloc(3) - allocate and free dynamic memory
callrpc(3) - library routines for remote procedure calls
canonicalize_file_name(3) -  return the canonicalized filename
carg(3) - calculate the complex argument
cargf(3) - calculate the complex argument
cargl(3) - calculate the complex argument
casin(3) - complex arc sine
casinf(3) - complex arc sine
casinh(3) - complex arc sine hyperbolic
casinhf(3) - complex arc sine hyperbolic
casinhl(3) - complex arc sine hyperbolic
casinl(3) - complex arc sine
catan(3) - complex arc tangents
catanf(3) - complex arc tangents
catanh(3) - complex arc tangents hyperbolic
catanhf(3) - complex arc tangents hyperbolic
catanhl(3) - complex arc tangents hyperbolic
catanl(3) - complex arc tangents
catclose(3) - open/close a message catalog
catgets(3) - get message from a message catalog
catopen(3) - open/close a message catalog
cbc_crypt(3) - fast DES encryption
cbrt(3) - cube root function
cbrtf(3) - cube root function
cbrtl(3) - cube root function
ccos(3) - complex cosine function
ccosf(3) - complex cosine function
ccosh(3) - complex hyperbolic cosine
ccoshf(3) - complex hyperbolic cosine
ccoshl(3) - complex hyperbolic cosine
ccosl(3) - complex cosine function
ceil(3) - ceiling function: smallest integral value not less than argument
ceilf(3) - ceiling function: smallest integral value not less than argument
ceill(3) - ceiling function: smallest integral value not less than argument
cerf(3) - complex error function
cerfc(3) - complex error function
cerfcf(3) - complex error function
cerfcl(3) - complex error function
cerff(3) - complex error function
cerfl(3) - complex error function
cexp2(3) - base-2 exponent of a complex number
cexp2f(3) - base-2 exponent of a complex number
cexp2l(3) - base-2 exponent of a complex number
cexp(3) - complex exponential function
cexpf(3) - complex exponential function
cexpl(3) - complex exponential function
cfgetispeed(3) - get and set terminal attributes, line control, get and set baud rate
cfgetospeed(3) - get and set terminal attributes, line control, get and set baud rate
cfmakeraw(3) - get and set terminal attributes, line control, get and set baud rate
cfree(3) - free allocated memory
cfsetispeed(3) - get and set terminal attributes, line control, get and set baud rate
cfsetospeed(3) - get and set terminal attributes, line control, get and set baud rate
cfsetspeed(3) - get and set terminal attributes, line control, get and set baud rate
cimag(3) - get imaginary part of a complex number
cimagf(3) - get imaginary part of a complex number
cimagl(3) - get imaginary part of a complex number
CIRCLEQ_ENTRY(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_HEAD(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_INIT(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_INSERT_AFTER(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_INSERT_BEFORE(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_INSERT_HEAD(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_INSERT_TAIL(3) - implementations of lists, tail queues, and circular queues
CIRCLEQ_REMOVE(3) - implementations of lists, tail queues, and circular queues
clearenv(3) - clear the environment
clearerr(3) - check and reset stream status
clearerr_unlocked(3) - nonlocking stdio functions
clnt_broadcast(3) - library routines for remote procedure calls
clnt_call(3) - library routines for remote procedure calls
clnt_control(3) - library routines for remote procedure calls
clnt_create(3) - library routines for remote procedure calls
clnt_destroy(3) - library routines for remote procedure calls
clnt_freeres(3) - library routines for remote procedure calls
clnt_geterr(3) - library routines for remote procedure calls
clnt_pcreateerror(3) - library routines for remote procedure calls
clnt_perrno(3) - library routines for remote procedure calls
clnt_perror(3) - library routines for remote procedure calls
clntraw_create(3) - library routines for remote procedure calls
clnt_spcreateerror(3) - library routines for remote procedure calls
clnt_sperrno(3) - library routines for remote procedure calls
clnt_sperror(3) - library routines for remote procedure calls
clnttcp_create(3) - library routines for remote procedure calls
clntudp_bufcreate(3) - library routines for remote procedure calls
clntudp_create(3) - library routines for remote procedure calls
clock(3) - determine processor time
clock_getcpuclockid(3) - obtain ID of a process CPU-time clock
clock_getres(3) - clock and time functions
clock_gettime(3) - clock and time functions
clock_settime(3) - clock and time functions
clog10(3) - base-10 logarithm of a complex number
clog10f(3) - base-10 logarithm of a complex number
clog10l(3) - base-10 logarithm of a complex number
clog2(3) - base-2 logarithm of a complex number
clog2f(3) - base-2 logarithm of a complex number
clog2l(3) - base-2 logarithm of a complex number
clog(3) - natural logarithm of a complex number
clogf(3) - natural logarithm of a complex number
clogl(3) - natural logarithm of a complex number
closedir(3) - close a directory
closelog(3) - send messages to the system logger
cmsg(3) - access ancillary data
CMSG_ALIGN(3) - access ancillary data
CMSG_FIRSTHDR(3) - access ancillary data
CMSG_NXTHDR(3) - access ancillary data
CMSG_SPACE(3) - access ancillary data
confstr(3) - get configuration dependent string variables
conj(3) - calculate the complex conjugate
conjf(3) - calculate the complex conjugate
conjl(3) - calculate the complex conjugate
copysign(3) - copy sign of a number
copysignf(3) - copy sign of a number
copysignl(3) - copy sign of a number
cos(3) - cosine function
cosf(3) - cosine function
cosh(3) - hyperbolic cosine function
coshf(3) - hyperbolic cosine function
coshl(3) - hyperbolic cosine function
cosl(3) - cosine function
cpow(3) - complex power function
cpowf(3) - complex power function
cpowl(3) - complex power function
cproj(3) - project into Riemann Sphere
cprojf(3) - project into Riemann Sphere
cprojl(3) - project into Riemann Sphere
CPU_ALLOC(3) - macros for manipulating CPU sets
CPU_ALLOC_SIZE(3) - macros for manipulating CPU sets
CPU_AND(3) - macros for manipulating CPU sets
CPU_AND_S(3) - macros for manipulating CPU sets
CPU_CLR(3) - macros for manipulating CPU sets
CPU_CLR_S(3) - macros for manipulating CPU sets
CPU_COUNT(3) - macros for manipulating CPU sets
CPU_COUNT_S(3) - macros for manipulating CPU sets
CPU_EQUAL(3) - macros for manipulating CPU sets
CPU_EQUAL_S(3) - macros for manipulating CPU sets
CPU_FREE(3) - macros for manipulating CPU sets
CPU_ISSET(3) - macros for manipulating CPU sets
CPU_ISSET_S(3) - macros for manipulating CPU sets
CPU_OR(3) - macros for manipulating CPU sets
CPU_OR_S(3) - macros for manipulating CPU sets
CPU_SET(3) - macros for manipulating CPU sets
CPU_SET_S(3) - macros for manipulating CPU sets
CPU_XOR(3) - macros for manipulating CPU sets
CPU_XOR_S(3) - macros for manipulating CPU sets
CPU_ZERO(3) - macros for manipulating CPU sets
CPU_ZERO_S(3) - macros for manipulating CPU sets
creal(3) - get real part of a complex number
crealf(3) - get real part of a complex number
creall(3) - get real part of a complex number
crypt(3) - password and data encryption
crypt_r(3) - password and data encryption
csin(3) - complex sine function
csinf(3) - complex sine function
csinh(3) - complex hyperbolic sine
csinhf(3) - complex hyperbolic sine
csinhl(3) - complex hyperbolic sine
csinl(3) - complex sine function
csqrt(3) - complex square root
csqrtf(3) - complex square root
csqrtl(3) - complex square root
ctan(3) - complex tangent function
ctanf(3) - complex tangent function
ctanh(3) - complex hyperbolic tangent
ctanhf(3) - complex hyperbolic tangent
ctanhl(3) - complex hyperbolic tangent
ctanl(3) - complex tangent function
ctermid(3) - get controlling terminal name
ctime(3) - transform date and time to broken-down time or ASCII
ctime_r(3) - transform date and time to broken-down time or ASCII
cuserid(3) - get username
daemon(3) - run in the background
daylight(3) - initialize time conversion information
db(3) - database access methods
dbopen(3) - database access methods
des_crypt(3) - fast DES encryption
DES_FAILED(3) - fast DES encryption
des_setparity(3) - fast DES encryption
difftime(3) - calculate time difference
dirfd(3) - get directory stream file descriptor
dirname(3) - parse pathname components
div(3) - compute quotient and remainder of an integer division
dladdr(3) - programming interface to dynamic linking loader
dlclose(3) - programming interface to dynamic linking loader
dlerror(3) - programming interface to dynamic linking loader
dl_iterate_phdr(3) - walk through list of shared objects
dlopen(3) - programming interface to dynamic linking loader
dlsym(3) - programming interface to dynamic linking loader
dlvsym(3) - programming interface to dynamic linking loader
dn_comp(3) - resolver routines
dn_expand(3) - resolver routines
dprintf(3) - print to a file descriptor
drand48(3) - generate uniformly distributed pseudo-random numbers
drand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
drem(3) -  floating-point remainder function
dremf(3) -  floating-point remainder function
dreml(3) -  floating-point remainder function
dysize(3) - get number of days for a given year
eaccess(3) - check effective user's permissions for a file
ecb_crypt(3) - fast DES encryption
ecvt(3) - convert a floating-point number to a string
ecvt_r(3) - convert a floating-point number to a string
edata(3) - end of program segments
encrypt(3) - encrypt 64-bit messages
encrypt_r(3) - encrypt 64-bit messages
end(3) - end of program segments
endaliasent(3) - read an alias entry
endfsent(3) - handle fstab entries
endgrent(3) - get group file entry
endhostent(3) - get network host entry
endian(3) - convert values between host and big-/little-endian byte order
endmntent(3) - get file system descriptor file entry
endnetent(3) - get network entry
endnetgrent(3) - handle network group entries
endprotoent(3) - get protocol entry
endpwent(3) - get password file entry
endrpcent(3) - get RPC entry
endservent(3) - get service entry
endspent(3) - get shadow password file entry
endttyent(3) - get ttys file entry
endusershell(3) - get permitted user shells
endutent(3) - access utmp file entries
endutxent(3) - access utmp file entries
envz(3) - environment string support
envz_add(3) - environment string support
envz_entry(3) - environment string support
envz_get(3) - environment string support
envz_merge(3) - environment string support
envz_remove(3) - environment string support
envz_strip(3) - environment string support
erand48(3) - generate uniformly distributed pseudo-random numbers
erand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
erf(3) - error function
erfc(3) - complementary error function
erfcf(3) - complementary error function
erfcl(3) - complementary error function
erff(3) - error function
erfl(3) - error function
err(3) - formatted error messages
errno(3) - number of last error
error(3) - glibc error reporting functions
error_at_line(3) - glibc error reporting functions
error_message_count(3) - glibc error reporting functions
error_one_per_line(3) - glibc error reporting functions
error_print_progname(3) - glibc error reporting functions
errx(3) - formatted error messages
etext(3) - end of program segments
ether_aton(3) - Ethernet address manipulation routines
ether_aton_r(3) - Ethernet address manipulation routines
ether_hostton(3) - Ethernet address manipulation routines
ether_line(3) - Ethernet address manipulation routines
ether_ntoa(3) - Ethernet address manipulation routines
ether_ntoa_r(3) - Ethernet address manipulation routines
ether_ntohost(3) - Ethernet address manipulation routines
euidaccess(3) - check effective user's permissions for a file
eventfd_read(3) - create a file descriptor for event notification
eventfd_write(3) - create a file descriptor for event notification
exec(3) - execute a file
execl(3) - execute a file
execle(3) - execute a file
execlp(3) - execute a file
execv(3) - execute a file
execvp(3) - execute a file
execvpe(3) - execute a file
exit(3) - cause normal process termination
exp10(3) - base-10 exponential function
exp10f(3) - base-10 exponential function
exp10l(3) - base-10 exponential function
exp2(3) - base-2 exponential function
exp2f(3) - base-2 exponential function
exp2l(3) - base-2 exponential function
exp(3) - base-e exponential function
expf(3) - base-e exponential function
expl(3) - base-e exponential function
expm1(3) - exponential minus 1
expm1f(3) - exponential minus 1
expm1l(3) - exponential minus 1
fabs(3) - absolute value of floating-point number
fabsf(3) - absolute value of floating-point number
fabsl(3) - absolute value of floating-point number
__fbufsize(3) - interfaces to stdio FILE structure
fclose(3) - close a stream
fcloseall(3) - close all open streams
fcvt(3) - convert a floating-point number to a string
fcvt_r(3) - convert a floating-point number to a string
FD_CLR(3) - synchronous I/O multiplexing
fdim(3) - positive difference
fdimf(3) - positive difference
fdiml(3) - positive difference
FD_ISSET(3) - synchronous I/O multiplexing
fdopen(3) - stream open functions
fdopendir(3) - open a directory
FD_SET(3) - synchronous I/O multiplexing
FD_ZERO(3) - synchronous I/O multiplexing
feclearexcept(3) - floating-point rounding and exception handling
fedisableexcept(3) - floating-point rounding and exception handling
feenableexcept(3) - floating-point rounding and exception handling
fegetenv(3) - floating-point rounding and exception handling
fegetexcept(3) - floating-point rounding and exception handling
fegetexceptflag(3) - floating-point rounding and exception handling
fegetround(3) - floating-point rounding and exception handling
feholdexcept(3) - floating-point rounding and exception handling
fenv(3) - floating-point rounding and exception handling
feof(3) - check and reset stream status
feof_unlocked(3) - nonlocking stdio functions
feraiseexcept(3) - floating-point rounding and exception handling
ferror(3) - check and reset stream status
ferror_unlocked(3) - nonlocking stdio functions
fesetenv(3) - floating-point rounding and exception handling
fesetexceptflag(3) - floating-point rounding and exception handling
fesetround(3) - floating-point rounding and exception handling
fetestexcept(3) - floating-point rounding and exception handling
feupdateenv(3) - floating-point rounding and exception handling
fexecve(3) - execute program specified via file descriptor
fflush(3) - flush a stream
fflush_unlocked(3) - nonlocking stdio functions
ffs(3) - find first bit set in a word
ffsl(3) - find first bit set in a word
ffsll(3) - find first bit set in a word
fgetc(3) - input of characters and strings
fgetc_unlocked(3) - nonlocking stdio functions
fgetgrent(3) - get group file entry
fgetgrent_r(3) - get group file entry reentrantly
fgetpos(3) - reposition a stream
fgetpwent(3) - get password file entry
fgetpwent_r(3) - get passwd file entry reentrantly
fgets(3) - input of characters and strings
fgetspent(3) - get shadow password file entry
fgetspent_r(3) - get shadow password file entry
fgets_unlocked(3) - nonlocking stdio functions
fgetwc(3) - read a wide character from a FILE stream
fgetwc_unlocked(3) - nonlocking stdio functions
fgetws(3) - read a wide-character string from a FILE stream
fgetws_unlocked(3) - nonlocking stdio functions
fileno(3) - check and reset stream status
fileno_unlocked(3) - nonlocking stdio functions
finite(3) - BSD floating-point classification functions
finitef(3) - BSD floating-point classification functions
finitel(3) - BSD floating-point classification functions
__flbf(3) - interfaces to stdio FILE structure
flockfile(3) - lock FILE for stdio
floor(3) - largest integral value not greater than argument
floorf(3) - largest integral value not greater than argument
floorl(3) - largest integral value not greater than argument
_flushlbf(3) - interfaces to stdio FILE structure
fma(3) - floating-point multiply and add
fmaf(3) - floating-point multiply and add
fmal(3) - floating-point multiply and add
fmax(3) - determine maximum of two floating-point numbers
fmaxf(3) - determine maximum of two floating-point numbers
fmaxl(3) - determine maximum of two floating-point numbers
fmemopen(3) -  open memory as stream
fmin(3) - determine minimum of two floating-point numbers
fminf(3) - determine minimum of two floating-point numbers
fminl(3) - determine minimum of two floating-point numbers
fmod(3) - floating-point remainder function
fmodf(3) - floating-point remainder function
fmodl(3) - floating-point remainder function
fmtmsg(3) - print formatted error messages
fnmatch(3) - match filename or pathname
fopen(3) - stream open functions
fopencookie(3) - opening a custom stream
forkpty(3) - tty utility functions
fpathconf(3) - get configuration values for files
fpclassify(3) - floating-point classification macros
__fpending(3) - interfaces to stdio FILE structure
fprintf(3) - formatted output conversion
__fpurge(3) - purge a stream
fpurge(3) - purge a stream
fputc(3) - output of characters and strings
fputc_unlocked(3) - nonlocking stdio functions
fputs(3) - output of characters and strings
fputs_unlocked(3) - nonlocking stdio functions
fputwc(3) - write a wide character to a FILE stream
fputwc_unlocked(3) - nonlocking stdio functions
fputws(3) - write a wide-character string to a FILE stream
fputws_unlocked(3) - nonlocking stdio functions
fread(3) - binary stream input/output
__freadable(3) - interfaces to stdio FILE structure
__freading(3) - interfaces to stdio FILE structure
fread_unlocked(3) - nonlocking stdio functions
free(3) - allocate and free dynamic memory
freeaddrinfo(3) - network address and service translation
freehostent(3) - get network hostnames and addresses
freeifaddrs(3) - get interface addresses
freopen(3) - stream open functions
frexp(3) - convert floating-point number to fractional and integral components
frexpf(3) - convert floating-point number to fractional and integral components
frexpl(3) - convert floating-point number to fractional and integral components
fscanf(3) - input format conversion
fseek(3) - reposition a stream
fseeko(3) - seek to or report file position
__fsetlocking(3) - interfaces to stdio FILE structure
fsetpos(3) - reposition a stream
fstatvfs(3) - get file system statistics
ftell(3) - reposition a stream
ftello(3) - seek to or report file position
ftime(3) - return date and time
ftok(3) - convert a pathname and a project identifier to a System V IPC key
ftrylockfile(3) - lock FILE for stdio
fts(3) -  traverse a file hierarchy
fts_children(3) -  traverse a file hierarchy
fts_close(3) -  traverse a file hierarchy
fts_open(3) -  traverse a file hierarchy
fts_read(3) -  traverse a file hierarchy
fts_set(3) -  traverse a file hierarchy
ftw(3) - file tree walk
funlockfile(3) - lock FILE for stdio
futimens(3) - change file timestamps with nanosecond precision
futimes(3) - change file timestamps
fwide(3) - set and determine the orientation of a FILE stream
fwprintf(3) - formatted wide-character output conversion
__fwritable(3) - interfaces to stdio FILE structure
fwrite(3) - binary stream input/output
fwrite_unlocked(3) - nonlocking stdio functions
__fwriting(3) - interfaces to stdio FILE structure
gai_cancel(3) - asynchronous network address and service translation
gai_error(3) - asynchronous network address and service translation
gai_strerror(3) - network address and service translation
gai_suspend(3) - asynchronous network address and service translation
gamma(3) - (logarithm of the) gamma function
gammaf(3) - (logarithm of the) gamma function
gammal(3) - (logarithm of the) gamma function
gcvt(3) - convert a floating-point number to a string
getaddrinfo(3) - network address and service translation
getaddrinfo_a(3) - asynchronous network address and service translation
getaliasbyname(3) - read an alias entry
getaliasbyname_r(3) - read an alias entry
getaliasent(3) - read an alias entry
getaliasent_r(3) - read an alias entry
getauxval(3) - retrieve a value from the auxiliary vector
getc(3) - input of characters and strings
getchar(3) - input of characters and strings
getchar_unlocked(3) - nonlocking stdio functions
getc_unlocked(3) - nonlocking stdio functions
get_current_dir_name(3) - get current working directory
getcwd(3) - get current working directory
getdate(3) - convert a date-plus-time string to broken-down time
getdate_err(3) - convert a date-plus-time string to broken-down time
getdate_r(3) - convert a date-plus-time string to broken-down time
getdelim(3) - delimited string input
getdirentries(3) - get directory entries in a file system-independent format
getenv(3) - get an environment variable
getfsent(3) - handle fstab entries
getfsfile(3) - handle fstab entries
getfsspec(3) - handle fstab entries
getgrent(3) - get group file entry
getgrent_r(3) - get group file entry reentrantly
getgrgid(3) - get group file entry
getgrgid_r(3) - get group file entry
getgrnam(3) - get group file entry
getgrnam_r(3) - get group file entry
getgrouplist(3) - get list of groups to which a user belongs
gethostbyaddr(3) - get network host entry
gethostbyaddr_r(3) - get network host entry
gethostbyname2(3) - get network host entry
gethostbyname2_r(3) - get network host entry
gethostbyname(3) - get network host entry
gethostbyname_r(3) - get network host entry
gethostent(3) - get network host entry
gethostent_r(3) - get network host entry
gethostid(3) - get or set the unique identifier of the current host
getifaddrs(3) - get interface addresses
getipnodebyaddr(3) - get network hostnames and addresses
getipnodebyname(3) - get network hostnames and addresses
getline(3) - delimited string input
getloadavg(3) - get system load averages
getlogin(3) - get username
getlogin_r(3) - get username
getmntent(3) - get file system descriptor file entry
getmntent_r(3) - get file system descriptor file entry
get_myaddress(3) - library routines for remote procedure calls
getnameinfo(3) - address-to-name translation in protocol-independent manner
getnetbyaddr(3) - get network entry
getnetbyaddr_r(3) - get network entry (reentrant)
getnetbyname(3) - get network entry
getnetbyname_r(3) - get network entry (reentrant)
getnetent(3) - get network entry
getnetent_r(3) - get network entry (reentrant)
getnetgrent(3) - handle network group entries
getnetgrent_r(3) - handle network group entries
get_nprocs(3) - get number of processors
get_nprocs_conf(3) - get number of processors
getopt(3) - Parse command-line options
getopt_long(3) - Parse command-line options
getopt_long_only(3) - Parse command-line options
getpass(3) - get a password
getprotobyname(3) - get protocol entry
getprotobyname_r(3) - get protocol entry (reentrant)
getprotobynumber(3) - get protocol entry
getprotobynumber_r(3) - get protocol entry (reentrant)
getprotoent(3) - get protocol entry
getprotoent_r(3) - get protocol entry (reentrant)
getpt(3) - open the pseudoterminal master (PTM)
getpw(3) - reconstruct password line entry
getpwent(3) - get password file entry
getpwent_r(3) - get passwd file entry reentrantly
getpwnam(3) - get password file entry
getpwnam_r(3) - get password file entry
getpwuid(3) - get password file entry
getpwuid_r(3) - get password file entry
getrpcbyname(3) - get RPC entry
getrpcbyname_r(3) - get RPC entry (reentrant)
getrpcbynumber(3) - get RPC entry
getrpcbynumber_r(3) - get RPC entry (reentrant)
getrpcent(3) - get RPC entry
getrpcent_r(3) - get RPC entry (reentrant)
getrpcport(3) - get RPC port number
gets(3) - input of characters and strings
getservbyname(3) - get service entry
getservbyname_r(3) - get service entry (reentrant)
getservbyport(3) - get service entry
getservbyport_r(3) - get service entry (reentrant)
getservent(3) - get service entry
getservent_r(3) - get service entry (reentrant)
getspent(3) - get shadow password file entry
getspent_r(3) - get shadow password file entry
getspnam(3) - get shadow password file entry
getspnam_r(3) - get shadow password file entry
getsubopt(3) - parse suboption arguments from a string
getttyent(3) - get ttys file entry
getttynam(3) - get ttys file entry
getumask(3) - get file creation mask
getusershell(3) - get permitted user shells
getutent(3) - access utmp file entries
getutent_r(3) - access utmp file entries
getutid(3) - access utmp file entries
getutid_r(3) - access utmp file entries
getutline(3) - access utmp file entries
getutline_r(3) - access utmp file entries
getutmp(3) - copy utmp structure to utmpx, and vice versa
getutmpx(3) - copy utmp structure to utmpx, and vice versa
getutxent(3) - access utmp file entries
getutxid(3) - access utmp file entries
getutxline(3) - access utmp file entries
getw(3) - input and output of words (ints)
getwc(3) - read a wide character from a FILE stream
getwchar(3) - read a wide character from standard input
getwchar_unlocked(3) - nonlocking stdio functions
getwc_unlocked(3) - nonlocking stdio functions
getwd(3) - get current working directory
glob(3) - find pathnames matching a pattern, free memory from glob()
globfree(3) - find pathnames matching a pattern, free memory from glob()
gmtime(3) - transform date and time to broken-down time or ASCII
gmtime_r(3) - transform date and time to broken-down time or ASCII
gnu_dev_major(3) - manage a device number
gnu_dev_makedev(3) - manage a device number
gnu_dev_minor(3) - manage a device number
gnu_get_libc_release(3) - get glibc version and release
gnu_get_libc_version(3) - get glibc version and release
grantpt(3) - grant access to the slave pseudoterminal
gsignal(3) - software signal facility
hash(3) - hash database access method
hasmntopt(3) - get file system descriptor file entry
hcreate(3) - hash table management
hcreate_r(3) - hash table management
hdestroy(3) - hash table management
hdestroy_r(3) - hash table management
h_errno(3) - get network host entry
herror(3) - get network host entry
hsearch(3) - hash table management
hsearch_r(3) - hash table management
hstrerror(3) - get network host entry
htobe16(3) - convert values between host and big-/little-endian byte order
htobe32(3) - convert values between host and big-/little-endian byte order
htobe64(3) - convert values between host and big-/little-endian byte order
htole16(3) - convert values between host and big-/little-endian byte order
htole32(3) - convert values between host and big-/little-endian byte order
htole64(3) - convert values between host and big-/little-endian byte order
htonl(3) - convert values between host and network byte order
htons(3) - convert values between host and network byte order
HUGE_VAL(3) - floating-point constants
HUGE_VALF(3) - floating-point constants
HUGE_VALL(3) - floating-point constants
hypot(3) - Euclidean distance function
hypotf(3) - Euclidean distance function
hypotl(3) - Euclidean distance function
iconv(3) - perform character set conversion
iconv_close(3) - deallocate descriptor for character set conversion
iconv_open(3) - allocate descriptor for character set conversion
if_freenameindex(3) - get network interface names and indexes
if_indextoname(3) - mappings between network interface names and indexes
if_nameindex(3) - get network interface names and indexes
if_nametoindex(3) - mappings between network interface names and indexes
ilogb(3) - get integer exponent of a floating-point value
ilogbf(3) - get integer exponent of a floating-point value
ilogbl(3) - get integer exponent of a floating-point value
imaxabs(3) - compute the absolute value of an integer
imaxdiv(3) - compute quotient and remainder of an integer division
index(3) - locate character in string
inet(3) - Internet address manipulation routines
inet_addr(3) - Internet address manipulation routines
inet_aton(3) - Internet address manipulation routines
inet_lnaof(3) - Internet address manipulation routines
inet_makeaddr(3) - Internet address manipulation routines
inet_netof(3) - Internet address manipulation routines
inet_network(3) - Internet address manipulation routines
inet_ntoa(3) - Internet address manipulation routines
inet_ntop(3) - convert IPv4 and IPv6 addresses from binary to text form
inet_pton(3) - convert IPv4 and IPv6 addresses from text to binary form
INFINITY(3) - floating-point constants
infnan(3) - deal with infinite or not-a-number (NaN) result
initgroups(3) - initialize the supplementary group access list
initstate(3) - random number generator
initstate_r(3) - reentrant random number generator
innetgr(3) - handle network group entries
insque(3) - insert/remove an item from a queue
intro(3) - introduction to library functions
iruserok(3) - routines for returning a stream to a remote command
iruserok_af(3) - routines for returning a stream to a remote command
isalnum(3) - character classification routines
isalpha(3) - character classification routines
isascii(3) - character classification routines
isatty(3) - test whether a file descriptor refers to a terminal
isblank(3) - character classification routines
iscntrl(3) - character classification routines
isdigit(3) - character classification routines
isfinite(3) - floating-point classification macros
isgraph(3) - character classification routines
isgreater(3) - floating-point relational tests without exception for NaN
isgreaterequal(3) - floating-point relational tests without exception for NaN
isinf(3) - floating-point classification macros
isinff(3) - BSD floating-point classification functions
isinfl(3) - BSD floating-point classification functions
isless(3) - floating-point relational tests without exception for NaN
islessequal(3) - floating-point relational tests without exception for NaN
islessgreater(3) - floating-point relational tests without exception for NaN
islower(3) - character classification routines
isnan(3) - floating-point classification macros
isnanf(3) - BSD floating-point classification functions
isnanl(3) - BSD floating-point classification functions
isnormal(3) - floating-point classification macros
isprint(3) - character classification routines
ispunct(3) - character classification routines
isspace(3) - character classification routines
isunordered(3) - floating-point relational tests without exception for NaN
isupper(3) - character classification routines
iswalnum(3) - test for alphanumeric wide character
iswalpha(3) - test for alphabetic wide character
iswblank(3) - test for whitespace wide character
iswcntrl(3) - test for control wide character
iswctype(3) - wide-character classification
iswdigit(3) - test for decimal digit wide character
iswgraph(3) - test for graphic wide character
iswlower(3) - test for lowercase wide character
iswprint(3) - test for printing wide character
iswpunct(3) - test for punctuation or symbolic wide character
iswspace(3) - test for whitespace wide character
iswupper(3) - test for uppercase wide character
iswxdigit(3) - test for hexadecimal digit wide character
isxdigit(3) - character classification routines
j0(3) - Bessel functions of the first kind
j0f(3) - Bessel functions of the first kind
j0l(3) - Bessel functions of the first kind
j1(3) - Bessel functions of the first kind
j1f(3) - Bessel functions of the first kind
j1l(3) - Bessel functions of the first kind
jn(3) - Bessel functions of the first kind
jnf(3) - Bessel functions of the first kind
jnl(3) - Bessel functions of the first kind
jrand48(3) - generate uniformly distributed pseudo-random numbers
jrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
key_decryptsession(3) - interfaces to rpc keyserver daemon
key_encryptsession(3) - interfaces to rpc keyserver daemon
key_gendes(3) - interfaces to rpc keyserver daemon
key_secretkey_is_set(3) - interfaces to rpc keyserver daemon
key_setsecret(3) - interfaces to rpc keyserver daemon
klogctl(3) - read and/or clear kernel message ring buffer; set console_loglevel
l64a(3) - convert between long and base-64
labs(3) - compute the absolute value of an integer
lckpwdf(3) - get shadow password file entry
lcong48(3) - generate uniformly distributed pseudo-random numbers
lcong48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
ldexp(3) - multiply floating-point number by integral power of 2
ldexpf(3) - multiply floating-point number by integral power of 2
ldexpl(3) - multiply floating-point number by integral power of 2
ldiv(3) - compute quotient and remainder of an integer division
le16toh(3) - convert values between host and big-/little-endian byte order
le32toh(3) - convert values between host and big-/little-endian byte order
le64toh(3) - convert values between host and big-/little-endian byte order
lfind(3) - linear search of an array
lgamma(3) - log gamma function
lgammaf(3) - log gamma function
lgammaf_r(3) - log gamma function
lgammal(3) - log gamma function
lgammal_r(3) - log gamma function
lgamma_r(3) - log gamma function
lio_listio(3) - initiate a list of I/O requests
LIST_ENTRY(3) - implementations of lists, tail queues, and circular queues
LIST_HEAD(3) - implementations of lists, tail queues, and circular queues
LIST_INIT(3) - implementations of lists, tail queues, and circular queues
LIST_INSERT_AFTER(3) - implementations of lists, tail queues, and circular queues
LIST_INSERT_HEAD(3) - implementations of lists, tail queues, and circular queues
LIST_REMOVE(3) - implementations of lists, tail queues, and circular queues
llabs(3) - compute the absolute value of an integer
lldiv(3) - compute quotient and remainder of an integer division
llrint(3) - round to nearest integer
llrintf(3) - round to nearest integer
llrintl(3) - round to nearest integer
llround(3) - round to nearest integer, away from zero
llroundf(3) - round to nearest integer, away from zero
llroundl(3) - round to nearest integer, away from zero
localeconv(3) - get numeric formatting information
localtime(3) - transform date and time to broken-down time or ASCII
localtime_r(3) - transform date and time to broken-down time or ASCII
lockf(3) - apply, test or remove a POSIX lock on an open file
log10(3) -  base-10 logarithmic function
log10f(3) -  base-10 logarithmic function
log10l(3) -  base-10 logarithmic function
log1p(3) -  logarithm of 1 plus argument
log1pf(3) -  logarithm of 1 plus argument
log1pl(3) -  logarithm of 1 plus argument
log2(3) - base-2 logarithmic function
log2f(3) - base-2 logarithmic function
log2l(3) - base-2 logarithmic function
log(3) - natural logarithmic function
logb(3) - get exponent of a floating-point value
logbf(3) - get exponent of a floating-point value
logbl(3) - get exponent of a floating-point value
logf(3) - natural logarithmic function
login(3) - write utmp and wtmp entries
login_tty(3) - tty utility functions
logl(3) - natural logarithmic function
logout(3) - write utmp and wtmp entries
logwtmp(3) - append an entry to the wtmp file
longjmp(3) - nonlocal jump to a saved stack context
lrand48(3) - generate uniformly distributed pseudo-random numbers
lrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
lrint(3) - round to nearest integer
lrintf(3) - round to nearest integer
lrintl(3) - round to nearest integer
lround(3) - round to nearest integer, away from zero
lroundf(3) - round to nearest integer, away from zero
lroundl(3) - round to nearest integer, away from zero
lsearch(3) - linear search of an array
lseek64(3) - reposition 64-bit read/write file offset
lutimes(3) - change file timestamps
major(3) - manage a device number
makecontext(3) - manipulate user context
makedev(3) - manage a device number
mallinfo(3) - obtain memory allocation information
malloc(3) - allocate and free dynamic memory
malloc_get_state(3) - record and restore state of malloc implementation
__malloc_hook(3) - malloc debugging variables
malloc_hook(3) - malloc debugging variables
malloc_info(3) - export malloc state to a stream
malloc_set_state(3) - record and restore state of malloc implementation
malloc_stats(3) - print memory allocation statistics
malloc_trim(3) - release free memory from the top of the heap
malloc_usable_size(3) - obtain size of block of memory allocated from heap
mallopt(3) - set memory allocation parameters
matherr(3) - SVID math library exception handling
MB_CUR_MAX(3) - maximum length of a multibyte character in the current locale
mblen(3) - determine number of bytes in next multibyte character
MB_LEN_MAX(3) - maximum multibyte length of a character across all locales
mbrlen(3) - determine number of bytes in next multibyte character
mbrtowc(3) - convert a multibyte sequence to a wide character
mbsinit(3) - test for initial shift state
mbsnrtowcs(3) - convert a multibyte string to a wide-character string
mbsrtowcs(3) - convert a multibyte string to a wide-character string
mbstowcs(3) - convert a multibyte string to a wide-character string
mbtowc(3) - convert a multibyte sequence to a wide character
mcheck(3) - heap consistency checking
mcheck_check_all(3) - heap consistency checking
mcheck_pedantic(3) - heap consistency checking
memalign(3) - allocate aligned memory
memccpy(3) - copy memory area
memchr(3) - scan memory for a character
memcmp(3) - compare memory areas
memcpy(3) - copy memory area
memfrob(3) - frobnicate (encrypt) a memory area
memmem(3) - locate a substring
memmove(3) - copy memory area
mempcpy(3) - copy memory area
memrchr(3) - scan memory for a character
memset(3) - fill memory with a constant byte
minor(3) - manage a device number
mkdtemp(3) - create a unique temporary directory
mkfifo(3) - make a FIFO special file (a named pipe)
mkfifoat(3) - make a FIFO (named pipe) relative to a directory file descriptor
mkostemp(3) - create a unique temporary file
mkostemps(3) - create a unique temporary file
mkstemp(3) - create a unique temporary file
mkstemps(3) - create a unique temporary file
mktemp(3) - make a unique temporary filename
mktime(3) - transform date and time to broken-down time or ASCII
mmap64(3) - map or unmap files or devices into memory
modf(3) - extract signed integral and fractional values from floating-point number
modff(3) - extract signed integral and fractional values from floating-point number
modfl(3) - extract signed integral and fractional values from floating-point number
mpool(3) - shared memory buffer pool
mprobe(3) - heap consistency checking
mq_close(3) - close a message queue descriptor
mq_getattr(3) - get/set message queue attributes
mq_notify(3) - register for notification when a message is available
mq_open(3) - open a message queue
mq_receive(3) - receive a message from a message queue
mq_send(3) - send a message to a message queue
mq_setattr(3) - get/set message queue attributes
mq_timedreceive(3) - receive a message from a message queue
mq_timedsend(3) - send a message to a message queue
mq_unlink(3) - remove a message queue
mrand48(3) - generate uniformly distributed pseudo-random numbers
mrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
mtrace(3) - malloc tracing
muntrace(3) - malloc tracing
nan(3) - return 'Not a Number'
NAN(3) - floating-point constants
nanf(3) - return 'Not a Number'
nanl(3) - return 'Not a Number'
nearbyint(3) - round to nearest integer
nearbyintf(3) - round to nearest integer
nearbyintl(3) - round to nearest integer
netlink(3) - Netlink macros
nextafter(3) - floating-point number manipulation
nextafterf(3) - floating-point number manipulation
nextafterl(3) - floating-point number manipulation
nexttoward(3) - floating-point number manipulation
nexttowardf(3) - floating-point number manipulation
nexttowardl(3) - floating-point number manipulation
nftw(3) - file tree walk
nl_langinfo(3) - query language and locale information
nrand48(3) - generate uniformly distributed pseudo-random numbers
nrand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
ntohl(3) - convert values between host and network byte order
ntohs(3) - convert values between host and network byte order
offsetof(3) - offset of a structure member
on_exit(3) - register a function to be called at normal process termination
opendir(3) - open a directory
openlog(3) - send messages to the system logger
open_memstream(3) -  open memory as stream
openpty(3) - tty utility functions
open_wmemstream(3) -  open memory as stream
optarg(3) - Parse command-line options
opterr(3) - Parse command-line options
optind(3) - Parse command-line options
optopt(3) - Parse command-line options
passwd2des(3) - RFS password encryption
pathconf(3) - get configuration values for files
pclose(3) - pipe stream to or from a process
perror(3) - print a system error message
pmap_getmaps(3) - library routines for remote procedure calls
pmap_getport(3) - library routines for remote procedure calls
pmap_rmtcall(3) - library routines for remote procedure calls
pmap_set(3) - library routines for remote procedure calls
pmap_unset(3) - library routines for remote procedure calls
popen(3) - pipe stream to or from a process
posix_fallocate(3) - allocate file space
posix_memalign(3) - allocate aligned memory
posix_openpt(3) - open a pseudoterminal device
pow10(3) - base-10 power functions
pow10f(3) - base-10 power functions
pow10l(3) - base-10 power functions
pow(3) - power functions
powf(3) - power functions
powl(3) - power functions
printf(3) - formatted output conversion
profil(3) - execution time profile
program_invocation_name(3) -  obtain name used to invoke calling program
program_invocation_short_name(3) -  obtain name used to invoke calling program
psiginfo(3) - print signal message
psignal(3) - print signal message
pthread_attr_destroy(3) - initialize and destroy thread attributes object
pthread_attr_getaffinity_np(3) - set/get CPU affinity attribute in thread attributes object
pthread_attr_getdetachstate(3) - set/get detach state attribute in thread attributes object
pthread_attr_getguardsize(3) - set/get guard size attribute in thread attributes object
pthread_attr_getinheritsched(3) - set/get inherit scheduler attribute in thread attributes object
pthread_attr_getschedparam(3) - set/get scheduling parameter attributes in thread attributes object
pthread_attr_getschedpolicy(3) - set/get scheduling policy attribute in thread attributes object
pthread_attr_getscope(3) - set/get contention scope attribute in thread attributes object
pthread_attr_getstack(3) - set/get stack attributes in thread attributes object
pthread_attr_getstackaddr(3) - set/get stack address attribute in thread attributes object
pthread_attr_getstacksize(3) - set/get stack size attribute in thread attributes object
pthread_attr_init(3) - initialize and destroy thread attributes object
pthread_attr_setaffinity_np(3) - set/get CPU affinity attribute in thread attributes object
pthread_attr_setdetachstate(3) - set/get detach state attribute in thread attributes object
pthread_attr_setguardsize(3) - set/get guard size attribute in thread attributes object
pthread_attr_setinheritsched(3) - set/get inherit scheduler attribute in thread attributes object
pthread_attr_setschedparam(3) - set/get scheduling parameter attributes in thread attributes object
pthread_attr_setschedpolicy(3) - set/get scheduling policy attribute in thread attributes object
pthread_attr_setscope(3) - set/get contention scope attribute in thread attributes object
pthread_attr_setstack(3) - set/get stack attributes in thread attributes object
pthread_attr_setstackaddr(3) - set/get stack address attribute in thread attributes object
pthread_attr_setstacksize(3) - set/get stack size attribute in thread attributes object
pthread_cancel(3) - send a cancellation request to a thread
pthread_cleanup_pop(3) - push and pop thread cancellation clean-up handlers
pthread_cleanup_pop_restore_np(3) - push and pop thread cancellation clean-up handlers while saving cancelability type
pthread_cleanup_push(3) - push and pop thread cancellation clean-up handlers
pthread_cleanup_push_defer_np(3) - push and pop thread cancellation clean-up handlers while saving cancelability type
pthread_create(3) - create a new thread
pthread_detach(3) - detach a thread
pthread_equal(3) - compare thread IDs
pthread_exit(3) - terminate calling thread
pthread_getaffinity_np(3) - set/get CPU affinity of a thread
pthread_getattr_np(3) - get attributes of created thread
pthread_getconcurrency(3) - set/get the concurrency level
pthread_getcpuclockid(3) - retrieve ID of a thread's CPU time clock
pthread_getschedparam(3) - set/get scheduling policy and parameters of a thread
pthread_join(3) - join with a terminated thread
pthread_kill(3) - send a signal to a thread
pthread_kill_other_threads_np(3) - terminate all other threads in process
pthread_self(3) - obtain ID of the calling thread
pthread_setaffinity_np(3) - set/get CPU affinity of a thread
pthread_setcancelstate(3) - set cancelability state and type
pthread_setcanceltype(3) - set cancelability state and type
pthread_setconcurrency(3) - set/get the concurrency level
pthread_setschedparam(3) - set/get scheduling policy and parameters of a thread
pthread_setschedprio(3) - set scheduling priority of a thread
pthread_sigmask(3) - examine and change mask of blocked signals
pthread_sigqueue(3) - queue a signal and data to a thread
pthread_testcancel(3) - request delivery of any pending cancellation request
pthread_timedjoin_np(3) - try to join with a terminated thread
pthread_tryjoin_np(3) - try to join with a terminated thread
pthread_yield(3) - yield the processor
ptsname(3) - get the name of the slave pseudoterminal
ptsname_r(3) - get the name of the slave pseudoterminal
putc(3) - output of characters and strings
putchar(3) - output of characters and strings
putchar_unlocked(3) - nonlocking stdio functions
putc_unlocked(3) - nonlocking stdio functions
putenv(3) - change or add an environment variable
putgrent(3) - write a group database entry to a file
putpwent(3) - write a password file entry
puts(3) - output of characters and strings
putspent(3) - get shadow password file entry
pututline(3) - access utmp file entries
pututxline(3) - access utmp file entries
putw(3) - input and output of words (ints)
putwc(3) - write a wide character to a FILE stream
putwchar(3) - write a wide character to standard output
putwchar_unlocked(3) - nonlocking stdio functions
putwc_unlocked(3) - nonlocking stdio functions
pvalloc(3) - allocate aligned memory
qecvt(3) - convert a floating-point number to a string
qecvt_r(3) - convert a floating-point number to a string
qfcvt(3) - convert a floating-point number to a string
qfcvt_r(3) - convert a floating-point number to a string
qgcvt(3) - convert a floating-point number to a string
qsort(3) - sort an array
qsort_r(3) - sort an array
queue(3) - implementations of lists, tail queues, and circular queues
raise(3) - send a signal to the caller
rand(3) - pseudo-random number generator
random(3) - random number generator
random_r(3) - reentrant random number generator
rand_r(3) - pseudo-random number generator
rawmemchr(3) - scan memory for a character
rcmd(3) - routines for returning a stream to a remote command
rcmd_af(3) - routines for returning a stream to a remote command
readdir(3) - read a directory
readdir_r(3) - read a directory
realloc(3) - allocate and free dynamic memory
realpath(3) - return the canonicalized absolute pathname
recno(3) - record number database access method
re_comp(3) - BSD regex functions
re_exec(3) - BSD regex functions
regcomp(3) - POSIX regex functions
regerror(3) - POSIX regex functions
regex(3) - POSIX regex functions
regexec(3) - POSIX regex functions
regfree(3) - POSIX regex functions
registerrpc(3) - library routines for remote procedure calls
remainder(3) -  floating-point remainder function
remainderf(3) -  floating-point remainder function
remainderl(3) -  floating-point remainder function
remove(3) - remove a file or directory
remque(3) - insert/remove an item from a queue
remquo(3) - remainder and part of quotient
remquof(3) - remainder and part of quotient
remquol(3) - remainder and part of quotient
res_init(3) - resolver routines
res_mkquery(3) - resolver routines
resolver(3) - resolver routines
res_query(3) - resolver routines
res_querydomain(3) - resolver routines
res_search(3) - resolver routines
res_send(3) - resolver routines
rewind(3) - reposition a stream
rewinddir(3) - reset directory stream
rexec(3) - return stream to a remote command
rexec_af(3) - return stream to a remote command
rindex(3) - locate character in string
rint(3) - round to nearest integer
rintf(3) - round to nearest integer
rintl(3) - round to nearest integer
round(3) - round to nearest integer, away from zero
roundf(3) - round to nearest integer, away from zero
roundl(3) - round to nearest integer, away from zero
rpc(3) - library routines for remote procedure calls
rpmatch(3) - determine if the answer to a question is affirmative or negative
rresvport(3) - routines for returning a stream to a remote command
rresvport_af(3) - routines for returning a stream to a remote command
rtime(3) - get time from a remote machine
rtnetlink(3) - macros to manipulate rtnetlink messages
ruserok(3) - routines for returning a stream to a remote command
ruserok_af(3) - routines for returning a stream to a remote command
scalb(3) - multiply floating-point number by integral power of radix (OBSOLETE)
scalbf(3) - multiply floating-point number by integral power of radix (OBSOLETE)
scalbl(3) - multiply floating-point number by integral power of radix (OBSOLETE)
scalbln(3) - multiply floating-point number by integral power of radix
scalblnf(3) - multiply floating-point number by integral power of radix
scalblnl(3) - multiply floating-point number by integral power of radix
scalbn(3) - multiply floating-point number by integral power of radix
scalbnf(3) - multiply floating-point number by integral power of radix
scalbnl(3) - multiply floating-point number by integral power of radix
scandir(3) - scan a directory for matching entries
scandirat(3) - scan a directory relative to a directory file descriptor
scanf(3) - input format conversion
sched_getcpu(3) - determine CPU on which the calling thread is running
secure_getenv(3) - get an environment variable
seed48(3) - generate uniformly distributed pseudo-random numbers
seed48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
seekdir(3) - set the position of the next readdir() call in the directory stream.
sem_close(3) - close a named semaphore
sem_destroy(3) - destroy an unnamed semaphore
sem_getvalue(3) - get the value of a semaphore
sem_init(3) - initialize an unnamed semaphore
sem_open(3) - initialize and open a named semaphore
sem_post(3) - unlock a semaphore
sem_timedwait(3) - lock a semaphore
sem_trywait(3) - lock a semaphore
sem_unlink(3) - remove a named semaphore
sem_wait(3) - lock a semaphore
setaliasent(3) - read an alias entry
setbuf(3) - stream buffering operations
setbuffer(3) - stream buffering operations
setenv(3) - change or add an environment variable
__setfpucw(3) - set FPU control word on i386 architecture (obsolete)
setfsent(3) - handle fstab entries
setgrent(3) - get group file entry
sethostent(3) - get network host entry
sethostid(3) - get or set the unique identifier of the current host
setjmp(3) - save stack context for nonlocal goto
setkey(3) - encrypt 64-bit messages
setkey_r(3) - encrypt 64-bit messages
setlinebuf(3) - stream buffering operations
setlocale(3) - set the current locale
setlogmask(3) - set log priority mask
setmntent(3) - get file system descriptor file entry
setnetent(3) - get network entry
setnetgrent(3) - handle network group entries
setprotoent(3) - get protocol entry
setpwent(3) - get password file entry
setrpcent(3) - get RPC entry
setservent(3) - get service entry
setspent(3) - get shadow password file entry
setstate(3) - random number generator
setstate_r(3) - reentrant random number generator
setttyent(3) - get ttys file entry
setusershell(3) - get permitted user shells
setutent(3) - access utmp file entries
setutxent(3) - access utmp file entries
setvbuf(3) - stream buffering operations
sgetspent(3) - get shadow password file entry
sgetspent_r(3) - get shadow password file entry
shm_open(3) - create/open or unlink POSIX shared memory objects
shm_unlink(3) - create/open or unlink POSIX shared memory objects
sigaddset(3) - POSIX signal set operations.
sigandset(3) - POSIX signal set operations.
sigblock(3) - BSD signal API
sigdelset(3) - POSIX signal set operations.
sigemptyset(3) - POSIX signal set operations.
sigfillset(3) - POSIX signal set operations.
siggetmask(3) - BSD signal API
sighold(3) - System V signal API
sigignore(3) - System V signal API
siginterrupt(3) - allow signals to interrupt system calls
sigisemptyset(3) - POSIX signal set operations.
sigismember(3) - POSIX signal set operations.
siglongjmp(3) - nonlocal jump to a saved stack context
sigmask(3) - BSD signal API
signbit(3) - test sign of a real floating-point number
signgam(3) - log gamma function
significand(3) - get mantissa of floating-point number
significandf(3) - get mantissa of floating-point number
significandl(3) - get mantissa of floating-point number
sigorset(3) - POSIX signal set operations.
sigpause(3) - atomically release blocked signals and wait for interrupt
sigqueue(3) - queue a signal and data to a process
sigrelse(3) - System V signal API
sigset(3) - System V signal API
sigsetjmp(3) - save stack context for nonlocal goto
sigsetmask(3) - BSD signal API
sigsetops(3) - POSIX signal set operations.
sigstack(3) - set and/or get signal stack context
sigvec(3) - BSD signal API
sigwait(3) - wait for a signal
sin(3) - sine function
sincos(3) - calculate sin and cos simultaneously
sincosf(3) - calculate sin and cos simultaneously
sincosl(3) - calculate sin and cos simultaneously
sinf(3) - sine function
sinh(3) - hyperbolic sine function
sinhf(3) - hyperbolic sine function
sinhl(3) - hyperbolic sine function
sinl(3) - sine function
sleep(3) - sleep for the specified number of seconds
snprintf(3) - formatted output conversion
sockatmark(3) - determine whether socket is at out-of-band mark
sprintf(3) - formatted output conversion
sqrt(3) - square root function
sqrtf(3) - square root function
sqrtl(3) - square root function
srand(3) - pseudo-random number generator
srand48(3) - generate uniformly distributed pseudo-random numbers
srand48_r(3) - generate uniformly distributed pseudo-random numbers reentrantly
srandom(3) - random number generator
srandom_r(3) - reentrant random number generator
sscanf(3) - input format conversion
ssignal(3) - software signal facility
statvfs(3) - get file system statistics
stdarg(3) - variable argument lists
stderr(3) - standard I/O streams
stdin(3) - standard I/O streams
stdio(3) - standard input/output library functions
stdio_ext(3) - interfaces to stdio FILE structure
stdout(3) - standard I/O streams
stpcpy(3) - copy a string returning a pointer to its end
stpncpy(3) - copy a fixed-size string, returning a pointer to its end
strcasecmp(3) - compare two strings ignoring case
strcasestr(3) - locate a substring
strcat(3) - concatenate two strings
strchr(3) - locate character in string
strchrnul(3) - locate character in string
strcmp(3) - compare two strings
strcoll(3) - compare two strings using the current locale
strcpy(3) - copy a string
strcspn(3) - search a string for a set of bytes
strdup(3) - duplicate a string
strdupa(3) - duplicate a string
strerror(3) - return string describing error number
strerror_r(3) - return string describing error number
strfmon(3) - convert monetary value to a string
strfry(3) - randomize a string
strftime(3) - format date and time
string(3) - string operations
strlen(3) - calculate the length of a string
strncasecmp(3) - compare two strings ignoring case
strncat(3) - concatenate two strings
strncmp(3) - compare two strings
strncpy(3) - copy a string
strndup(3) - duplicate a string
strndupa(3) - duplicate a string
strnlen(3) - determine the length of a fixed-size string
strpbrk(3) - search a string for any of a set of bytes
strptime(3) - convert a string representation of time to a time tm structure
strrchr(3) - locate character in string
strsep(3) - extract token from string
strsignal(3) - return string describing signal
strspn(3) - search a string for a set of bytes
strstr(3) - locate a substring
strtod(3) - convert ASCII string to floating-point number
strtof(3) - convert ASCII string to floating-point number
strtoimax(3) - convert string to integer
strtok(3) - extract tokens from strings
strtok_r(3) - extract tokens from strings
strtol(3) - convert a string to a long integer
strtold(3) - convert ASCII string to floating-point number
strtoll(3) - convert a string to a long integer
strtoq(3) - convert a string to a long integer
strtoul(3) - convert a string to an unsigned long integer
strtoull(3) - convert a string to an unsigned long integer
strtoumax(3) - convert string to integer
strtouq(3) - convert a string to an unsigned long integer
strverscmp(3) - compare two version strings
strxfrm(3) - string transformation
svc_destroy(3) - library routines for remote procedure calls
svcerr_auth(3) - library routines for remote procedure calls
svcerr_decode(3) - library routines for remote procedure calls
svcerr_noproc(3) - library routines for remote procedure calls
svcerr_noprog(3) - library routines for remote procedure calls
svcerr_progvers(3) - library routines for remote procedure calls
svcerr_systemerr(3) - library routines for remote procedure calls
svcerr_weakauth(3) - library routines for remote procedure calls
svcfd_create(3) - library routines for remote procedure calls
svc_freeargs(3) - library routines for remote procedure calls
svc_getargs(3) - library routines for remote procedure calls
svc_getcaller(3) - library routines for remote procedure calls
svc_getreq(3) - library routines for remote procedure calls
svc_getreqset(3) - library routines for remote procedure calls
svcraw_create(3) - library routines for remote procedure calls
svc_register(3) - library routines for remote procedure calls
svc_run(3) - library routines for remote procedure calls
svc_sendreply(3) - library routines for remote procedure calls
svctcp_create(3) - library routines for remote procedure calls
svcudp_bufcreate(3) - library routines for remote procedure calls
svcudp_create(3) - library routines for remote procedure calls
svc_unregister(3) - library routines for remote procedure calls
swab(3) - swap adjacent bytes
swapcontext(3) - manipulate user context
swprintf(3) - formatted wide-character output conversion
sysconf(3) - get configuration information at run time
sys_errlist(3) - print a system error message
syslog(3) - send messages to the system logger
sys_nerr(3) - print a system error message
system(3) - execute a shell command
sysv_signal(3) - signal handling with System V semantics
TAILQ_ENTRY(3) - implementations of lists, tail queues, and circular queues
TAILQ_HEAD(3) - implementations of lists, tail queues, and circular queues
TAILQ_INIT(3) - implementations of lists, tail queues, and circular queues
TAILQ_INSERT_AFTER(3) - implementations of lists, tail queues, and circular queues
TAILQ_INSERT_HEAD(3) - implementations of lists, tail queues, and circular queues
TAILQ_INSERT_TAIL(3) - implementations of lists, tail queues, and circular queues
TAILQ_REMOVE(3) - implementations of lists, tail queues, and circular queues
tan(3) - tangent function
tanf(3) - tangent function
tanh(3) - hyperbolic tangent function
tanhf(3) - hyperbolic tangent function
tanhl(3) - hyperbolic tangent function
tanl(3) - tangent function
tcdrain(3) - get and set terminal attributes, line control, get and set baud rate
tcflow(3) - get and set terminal attributes, line control, get and set baud rate
tcflush(3) - get and set terminal attributes, line control, get and set baud rate
tcgetattr(3) - get and set terminal attributes, line control, get and set baud rate
tcgetpgrp(3) - get and set terminal foreground process group
tcgetsid(3) - get session ID
tcsendbreak(3) - get and set terminal attributes, line control, get and set baud rate
tcsetattr(3) - get and set terminal attributes, line control, get and set baud rate
tcsetpgrp(3) - get and set terminal foreground process group
tdelete(3) - manage a binary tree
tdestroy(3) - manage a binary tree
telldir(3) - return current location in directory stream
tempnam(3) - create a name for a temporary file
termios(3) - get and set terminal attributes, line control, get and set baud rate
tfind(3) - manage a binary tree
tgamma(3) - true gamma function
tgammaf(3) - true gamma function
tgammal(3) - true gamma function
timegm(3) - inverses of gmtime and localtime
timelocal(3) - inverses of gmtime and localtime
timeradd(3) - timeval operations
timerclear(3) - timeval operations
timercmp(3) - timeval operations
timerisset(3) - timeval operations
timersub(3) - timeval operations
timezone(3) - initialize time conversion information
tmpfile(3) - create a temporary file
tmpnam(3) - create a name for a temporary file
tmpnam_r(3) - create a name for a temporary file
toascii(3) - convert character to ASCII
tolower(3) - convert letter to upper or lower case
toupper(3) - convert letter to upper or lower case
towctrans(3) - wide-character transliteration
towlower(3) - convert a wide character to lowercase
towupper(3) - convert a wide character to uppercase
trunc(3) - round to integer, toward zero
truncf(3) - round to integer, toward zero
truncl(3) - round to integer, toward zero
tsearch(3) - manage a binary tree
ttyname(3) - return name of a terminal
ttyname_r(3) - return name of a terminal
ttyslot(3) - find the slot of the current user's terminal in some file
twalk(3) - manage a binary tree
tzname(3) - initialize time conversion information
tzset(3) - initialize time conversion information
ualarm(3) - schedule signal after given number of microseconds
ulckpwdf(3) - get shadow password file entry
ulimit(3) - get and set user limits
undocumented(3) - undocumented library functions
ungetc(3) - input of characters and strings
ungetwc(3) - push back a wide character onto a FILE stream
unlocked_stdio(3) - nonlocking stdio functions
unlockpt(3) - unlock a pseudoterminal master/slave pair
unsetenv(3) - change or add an environment variable
updwtmp(3) - append an entry to the wtmp file
updwtmpx(3) - append an entry to the wtmp file
usleep(3) - suspend execution for microsecond intervals
utmpname(3) - access utmp file entries
utmpxname(3) - access utmp file entries
va_arg(3) - variable argument lists
va_copy(3) - variable argument lists
va_end(3) - variable argument lists
valloc(3) - allocate aligned memory
vasprintf(3) - print to allocated string
va_start(3) - variable argument lists
vdprintf(3) - print to a file descriptor
verr(3) - formatted error messages
verrx(3) - formatted error messages
versionsort(3) - scan a directory for matching entries
vfprintf(3) - formatted output conversion
vfscanf(3) - input format conversion
vfwprintf(3) - formatted wide-character output conversion
vlimit(3) - get/set resource limits
vprintf(3) - formatted output conversion
vscanf(3) - input format conversion
vsnprintf(3) - formatted output conversion
vsprintf(3) - formatted output conversion
vsscanf(3) - input format conversion
vswprintf(3) - formatted wide-character output conversion
vsyslog(3) - send messages to the system logger
vtimes(3) - get resource usage
vwarn(3) - formatted error messages
vwarnx(3) - formatted error messages
vwprintf(3) - formatted wide-character output conversion
warn(3) - formatted error messages
warnx(3) - formatted error messages
wcpcpy(3) - copy a wide-character string, returning a pointer to its end
wcpncpy(3) - copy a fixed-size string of wide characters, returning a pointer to its end
wcrtomb(3) - convert a wide character to a multibyte sequence
wcscasecmp(3) - compare two wide-character strings, ignoring case
wcscat(3) - concatenate two wide-character strings
wcschr(3) - search a wide character in a wide-character string
wcscmp(3) - compare two wide-character strings
wcscpy(3) - copy a wide-character string
wcscspn(3) - search a wide-character string for any of a set of wide characters
wcsdup(3) - duplicate a wide-character string
wcslen(3) - determine the length of a wide-character string
wcsncasecmp(3) - compare two fixed-size wide-character strings, ignoring case
wcsncat(3) - concatenate two wide-character strings
wcsncmp(3) - compare two fixed-size wide-character strings
wcsncpy(3) - copy a fixed-size string of wide characters
wcsnlen(3) - determine the length of a fixed-size wide-character string
wcsnrtombs(3) - convert a wide-character string to a multibyte string
wcspbrk(3) - search a wide-character string for any of a set of wide characters
wcsrchr(3) - search a wide character in a wide-character string
wcsrtombs(3) - convert a wide-character string to a multibyte string
wcsspn(3) - advance in a wide-character string, skipping any of a set of wide characters
wcsstr(3) - locate a substring in a wide-character string
wcstoimax(3) - convert wide-character string to integer
wcstok(3) - split wide-character string into tokens
wcstombs(3) - convert a wide-character string to a multibyte string
wcstoumax(3) - convert wide-character string to integer
wcswidth(3) - determine columns needed for a fixed-size wide-character string
wctob(3) - try to represent a wide character as a single byte
wctomb(3) - convert a wide character to a multibyte sequence
wctrans(3) - wide-character translation mapping
wctype(3) - wide-character classification
wcwidth(3) - determine columns needed for a wide character
wmemchr(3) - search a wide character in a wide-character array
wmemcmp(3) - compare two arrays of wide-characters
wmemcpy(3) - copy an array of wide-characters
wmemmove(3) - copy an array of wide-characters
wmempcpy(3) - copy memory area
wmemset(3) - fill an array of wide-characters with a constant wide character
wordexp(3) - perform word expansion like a posix-shell
wordfree(3) - perform word expansion like a posix-shell
wprintf(3) - formatted wide-character output conversion
xcrypt(3) - RFS password encryption
xdecrypt(3) - RFS password encryption
xdr(3) - library routines for external data representation
xdr_accepted_reply(3) - library routines for remote procedure calls
xdr_array(3) - library routines for external data representation
xdr_authunix_parms(3) - library routines for remote procedure calls
xdr_bool(3) - library routines for external data representation
xdr_bytes(3) - library routines for external data representation
xdr_callhdr(3) - library routines for remote procedure calls
xdr_callmsg(3) - library routines for remote procedure calls
xdr_char(3) - library routines for external data representation
xdr_destroy(3) - library routines for external data representation
xdr_double(3) - library routines for external data representation
xdr_enum(3) - library routines for external data representation
xdr_float(3) - library routines for external data representation
xdr_free(3) - library routines for external data representation
xdr_getpos(3) - library routines for external data representation
xdr_inline(3) - library routines for external data representation
xdr_int(3) - library routines for external data representation
xdr_long(3) - library routines for external data representation
xdrmem_create(3) - library routines for external data representation
xdr_opaque(3) - library routines for external data representation
xdr_opaque_auth(3) - library routines for remote procedure calls
xdr_pmap(3) - library routines for remote procedure calls
xdr_pmaplist(3) - library routines for remote procedure calls
xdr_pointer(3) - library routines for external data representation
xdrrec_create(3) - library routines for external data representation
xdrrec_endofrecord(3) - library routines for external data representation
xdrrec_eof(3) - library routines for external data representation
xdrrec_skiprecord(3) - library routines for external data representation
xdr_reference(3) - library routines for external data representation
xdr_rejected_reply(3) - library routines for remote procedure calls
xdr_replymsg(3) - library routines for remote procedure calls
xdr_setpos(3) - library routines for external data representation
xdr_short(3) - library routines for external data representation
xdrstdio_create(3) - library routines for external data representation
xdr_string(3) - library routines for external data representation
xdr_u_char(3) - library routines for external data representation
xdr_u_int(3) - library routines for external data representation
xdr_u_long(3) - library routines for external data representation
xdr_union(3) - library routines for external data representation
xdr_u_short(3) - library routines for external data representation
xdr_vector(3) - library routines for external data representation
xdr_void(3) - library routines for external data representation
xdr_wrapstring(3) - library routines for external data representation
xencrypt(3) - RFS password encryption
xprt_register(3) - library routines for remote procedure calls
xprt_unregister(3) - library routines for remote procedure calls
y0(3) - Bessel functions of the second kind
y0f(3) - Bessel functions of the second kind
y0l(3) - Bessel functions of the second kind
y1(3) - Bessel functions of the second kind
y1f(3) - Bessel functions of the second kind
y1l(3) - Bessel functions of the second kind
yn(3) - Bessel functions of the second kind
ynf(3) - Bessel functions of the second kind
ynl(3) - Bessel functions of the second kind

Section 4

 top
cciss(4) - HP Smart Array block driver
console(4) - console terminal and virtual consoles
console_codes(4) - Linux console escape and control sequences
console_ioctl(4) - ioctl's for console terminal and virtual consoles
cpuid(4) - x86 CPUID access device
dsp56k(4) - DSP56001 interface device
fd(4) - floppy disk device
full(4) - always full device
hd(4) - MFM/IDE hard disk devices
hpsa(4) - HP Smart Array SCSI driver
initrd(4) - boot loader initialized RAM disk
intro(4) - introduction to special files
kmem(4) - system memory, kernel memory and system ports
lp(4) - line printer devices
mem(4) - system memory, kernel memory and system ports
mouse(4) - serial mouse interface
msr(4) - x86 CPU MSR access device
null(4) - data sink
port(4) - system memory, kernel memory and system ports
ptmx(4) - pseudoterminal master and slave
pts(4) - pseudoterminal master and slave
ram(4) - ram disk device
random(4) - kernel random number source devices
rtc(4) - real-time clock
sd(4) - driver for SCSI disk drives
sk98lin(4) - Marvell/SysKonnect Gigabit Ethernet driver v6.21
st(4) - SCSI tape device
tty(4) - controlling terminal
tty_ioctl(4) - ioctls for terminals and serial lines
ttyS(4) - serial terminal lines
urandom(4) - kernel random number source devices
vcs(4) - virtual console memory
vcsa(4) - virtual console memory
wavelan(4) - AT&T GIS WaveLAN ISA device driver
zero(4) - data sink

Section 5

 top
acct(5) - process accounting file
charmap(5) - character symbols to define character encodings
core(5) - core dump file
dir_colors(5) - configuration file for dircolors(1)
elf(5) - format of Executable and Linking Format (ELF) files
filesystems(5) - Linux file-system types: minix, ext, ext2, ext3, ext4, Reiserfs, XFS, JFS, xia, msdos, umsdos, vfat, ntfs, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs
fs(5) - Linux file-system types: minix, ext, ext2, ext3, ext4, Reiserfs, XFS, JFS, xia, msdos, umsdos, vfat, ntfs, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs
ftpusers(5) - list of users that may not log in via the FTP daemon
group(5) - user group file
host.conf(5) - resolver configuration file
hosts(5) - static table lookup for hostnames
hosts.equiv(5) - list of hosts and users that are granted "trusted" fBrfP command access to your system
intro(5) - introduction to file formats
ipc(5) - System V interprocess communication mechanisms
issue(5) - prelogin message and identification file
locale(5) - describes a locale definition file
motd(5) - message of the day
networks(5) - network name information
nologin(5) - prevent unprivileged users from logging into the system
nscd.conf(5) - name service cache daemon configuration file
nsswitch.conf(5) - Name Service Switch configuration file
numa_maps(5) - overview of Non-Uniform Memory Architecture
passwd(5) - password file
proc(5) - process information pseudo-file system
protocols(5) - protocols definition file
resolv.conf(5) - resolver configuration file
resolver(5) - resolver configuration file
rpc(5) - RPC program number data base
securetty(5) - file which lists ttys from which root can log in
services(5) - Internet network services list
shells(5) - pathnames of valid login shells
slabinfo(5) - kernel slab allocator statistics
termcap(5) - terminal capability database
ttytype(5) - terminal device to default terminal type mapping
tzfile(5) - timezone information
utmp(5) - login records
utmpx(5) - login records
wtmp(5) - login records

Section 6

 top
intro(6) - introduction to games

Section 7

 top
aio(7) - POSIX asynchronous I/O overview
armscii-8(7) - Armenian character set encoded in octal, decimal, and hexadecimal
arp(7) - Linux ARP kernel module.
ascii(7) - ASCII character set encoded in octal, decimal, and hexadecimal
boot(7) - general description of boot sequence
bootparam(7) - introduction to boot time parameters of the Linux kernel
capabilities(7) - overview of Linux capabilities
charsets(7) - programmer's view of character sets and internationalization
complex(7) - basics of complex mathematics
cp1251(7) - CP 1251 character set encoded in octal, decimal, and hexadecimal
cpuset(7) - confine processes to processor and memory node subsets
credentials(7) - process identifiers
ddp(7) - Linux AppleTalk protocol implementation
environ(7) - user environment
epoll(7) - I/O event notification facility
feature_test_macros(7) - feature test macros
fifo(7) - first-in first-out special file, named pipe
futex(7) - fast user-space locking
glibc(7) - overview of standard C libraries on Linux
glob(7) - globbing pathnames
hier(7) - description of the file system hierarchy
hostname(7) - hostname resolution description
icmp(7) - Linux IPv4 ICMP kernel module.
inotify(7) - monitoring file system events
intro(7) - introduction to overview, conventions, and miscellany section
ip(7) - Linux IPv4 protocol implementation
ipv6(7) - Linux IPv6 protocol implementation
iso-8859-10(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
iso_8859-10(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
iso_8859_10(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
iso-8859-11(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
iso_8859-11(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
iso_8859_11(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
iso-8859-13(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
iso_8859-13(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
iso_8859_13(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
iso-8859-14(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
iso_8859-14(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
iso_8859_14(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
iso-8859-15(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
iso_8859-15(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
iso_8859_15(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
iso-8859-16(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
iso_8859-16(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
iso_8859_16(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
iso-8859-1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
iso_8859-1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
iso_8859_1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
iso-8859-2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
iso_8859-2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
iso_8859_2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
iso-8859-3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
iso_8859-3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
iso_8859_3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
iso-8859-4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
iso_8859-4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
iso_8859_4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
iso-8859-5(7) - ISO 8859-5 character set encoded in octal, decimal, and hexadecimal
iso_8859-5(7) - ISO 8859-5 character set encoded in octal, decimal, and hexadecimal
iso_8859_5(7) - ISO 8859-5 character set encoded in octal, decimal, and hexadecimal
iso-8859-6(7) - ISO 8859-6 character set encoded in octal, decimal, and hexadecimal
iso_8859-6(7) - ISO 8859-6 character set encoded in octal, decimal, and hexadecimal
iso_8859_6(7) - ISO 8859-6 character set encoded in octal, decimal, and hexadecimal
iso-8859-7(7) - ISO 8859-7 character set encoded in octal, decimal, and hexadecimal
iso_8859-7(7) - ISO 8859-7 character set encoded in octal, decimal, and hexadecimal
iso_8859_7(7) - ISO 8859-7 character set encoded in octal, decimal, and hexadecimal
iso-8859-8(7) - ISO 8859-8 character set encoded in octal, decimal, and hexadecimal
iso_8859-8(7) - ISO 8859-8 character set encoded in octal, decimal, and hexadecimal
iso_8859_8(7) - ISO 8859-8 character set encoded in octal, decimal, and hexadecimal
iso-8859-9(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
iso_8859-9(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
iso_8859_9(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
koi8-r(7) - Russian character set encoded in octal, decimal, and hexadecimal
koi8-u(7) - Ukrainian character set encoded in octal, decimal, and hexadecimal
latin10(7) - ISO 8859-16 character set encoded in octal, decimal, and hexadecimal
latin1(7) - ISO 8859-1 character set encoded in octal, decimal, and hexadecimal
latin2(7) - ISO 8859-2 character set encoded in octal, decimal, and hexadecimal
latin3(7) - ISO 8859-3 character set encoded in octal, decimal, and hexadecimal
latin4(7) - ISO 8859-4 character set encoded in octal, decimal, and hexadecimal
latin5(7) - ISO 8859-9 character set encoded in octal, decimal, and hexadecimal
latin6(7) - ISO 8859-10 character set encoded in octal, decimal, and hexadecimal
latin7(7) - ISO 8859-13 character set encoded in octal, decimal, and hexadecimal
latin8(7) - ISO 8859-14 character set encoded in octal, decimal, and hexadecimal
latin9(7) - ISO 8859-15 character set encoded in octal, decimal, and hexadecimal
libc(7) - overview of standard C libraries on Linux
locale(7) - description of multilanguage support
mailaddr(7) - mail addressing description
man(7) - macros to format man pages
man-pages(7) - conventions for writing Linux man pages
math_error(7) - detecting errors from mathematical functions
mdoc(7) - quick reference guide for the .Nm -mdoc macro package
mdoc.samples(7) - tutorial sampler for writing .Bx manuals with .Nm -mdoc
mq_overview(7) - overview of POSIX message queues
netdevice(7) - low-level access to Linux network devices
netlink(7) - communication between kernel and user space (AF_NETLINK)
numa(7) - overview of Non-Uniform Memory Architecture
operator(7) - C operator precedence and order of evaluation
packet(7) - packet interface on device level.
path_resolution(7) - how a pathname is resolved to a file
pipe(7) - overview of pipes and FIFOs
posixoptions(7) - optional parts of the POSIX standard
pthreads(7) - POSIX threads
pty(7) - pseudoterminal interfaces
raw(7) - Linux IPv4 raw sockets
regex(7) - POSIX.2 regular expressions
rtld-audit(7) - auditing API for the dynamic linker
rtnetlink(7) - Linux IPv4 routing socket
sem_overview(7) - overview of POSIX semaphores
shm_overview(7) - overview of POSIX shared memory
sigevent(7) - structure for notification from asynchronous routines
signal(7) - overview of signals
socket(7) - Linux socket interface
spufs(7) - SPU file system
standards(7) - C and UNIX Standards
suffixes(7) - list of file suffixes
svipc(7) - System V interprocess communication mechanisms
symlink(7) - symbolic link handling
tcp(7) - TCP protocol
termio(7) - System V terminal driver interface
time(7) - overview of time and timers
tis-620(7) - ISO 8859-11 character set encoded in octal, decimal, and hexadecimal
udp(7) - User Datagram Protocol for IPv4
udplite(7) - Lightweight User Datagram Protocol
unicode(7) - universal character set
units(7) - decimal and binary prefixes
unix(7) - sockets for local interprocess communication
uri(7) - uniform resource identifier (URI), including a URL or URN
url(7) - uniform resource identifier (URI), including a URL or URN
urn(7) - uniform resource identifier (URI), including a URL or URN
utf-8(7) - an ASCII compatible multibyte Unicode encoding
utf8(7) - an ASCII compatible multibyte Unicode encoding
x25(7) - ITU-T X.25 / ISO-8208 protocol interface.

Section 8

 top
intro(8) - introduction to administration and privileged commands
ldconfig(8) - configure dynamic linker run-time bindings
ld-linux(8) - dynamic linker/loader
ld-linux.so(8) - dynamic linker/loader
ld.so(8) - dynamic linker/loader
nscd(8) - name service cache daemon
sync(8) - synchronize data on disk with memory
tzselect(8) - select a timezone
zdump(8) - timezone dumper
zic(8) - timezone compiler


dir_colors(5) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DIR_COLORS(5)                    Linux User Manual                   DIR_COLORS(5)

NAME top

       dir_colors - configuration file for dircolors(1)

DESCRIPTION top

       The program ls(1) uses the environment variable LS_COLORS to determine the
       colors in which the filenames are to be displayed.  This environment
       variable is usually set by a command like

              eval `dircolors some_path/dir_colors`

       found in a system default shell initialization file, like /etc/profile or
       /etc/csh.cshrc.  (See also dircolors(1).)  Usually, the file used here is
       /etc/DIR_COLORS and can be overridden by a .dir_colors file in one's home
       directory.

       This configuration file consists of several statements, one per line.
       Anything right of a hash mark (#) is treated as a comment, if the hash mark
       is at the beginning of a line or is preceded by at least one whitespace.
       Blank lines are ignored.

       The global section of the file consists of any statement before the first
       TERM statement.  Any statement in the global section of the file is
       considered valid for all terminal types.  Following the global section is
       one or more terminal-specific sections, preceded by one or more TERM
       statements which specify the terminal types (as given by the TERM
       environment variable) the following declarations apply to.  It is always
       possible to override a global declaration by a subsequent terminal-specific
       one.

       The following statements are recognized; case is insignificant:

       TERM [22mterminal-type[0m
              Starts a terminal-specific section and specifies which terminal it
              applies to.  Multiple TERM statements can be used to create a
              section which applies for several terminal types.

       COLOR yes|all|no|none|tty
              (Slackware only; ignored by GNU dircolors(1).)  Specifies that
              colorization should always be enabled (yes or all), never enabled
              (no or none), or enabled only if the output is a terminal (tty).
              The default is no.

       EIGHTBIT yes|no
              (Slackware only; ignored by GNU dircolors(1).)  Specifies that
              eight-bit ISO 8859 characters should be enabled by default.  For
              compatibility reasons, this can also be specified as 1 for yes or 0
              for no.  The default is no.

       OPTIONS [22moptions[0m
              (Slackware only; ignored by GNU dircolors(1).)  Adds command-line
              options to the default ls command line.  The options can be any
              valid ls command-line options, and should include the leading minus
              sign.  Note that dircolors does not verify the validity of these
              options.

       NORMAL [22mcolor-sequence[0m
              Specifies the color used for normal (nonfilename) text.

       FILE [22mcolor-sequence[0m
              Specifies the color used for a regular file.

       DIR [22mcolor-sequence[0m
              Specifies the color used for directories.

       LINK [22mcolor-sequence[0m
              Specifies the color used for a symbolic link.

       ORPHAN [22mcolor-sequence[0m
              Specifies the color used for an orphaned symbolic link (one which
              points to a nonexistent file).  If this is unspecified, ls will use
              the LINK color instead.

       MISSING [22mcolor-sequence[0m
              Specifies the color used for a missing file (a nonexistent file
              which nevertheless has a symbolic link pointing to it).  If this is
              unspecified, ls will use the FILE color instead.

       FIFO [22mcolor-sequence[0m
              Specifies the color used for a FIFO (named pipe).

       SOCK [22mcolor-sequence[0m
              Specifies the color used for a socket.

       DOOR [22mcolor-sequence[0m
              (Supported since fileutils 4.1) Specifies the color used for a door
              (Solaris 2.5 and later).

       BLK [22mcolor-sequence[0m
              Specifies the color used for a block device special file.

       CHR [22mcolor-sequence[0m
              Specifies the color used for a character device special file.

       EXEC [22mcolor-sequence[0m
              Specifies the color used for a file with the executable attribute
              set.

       LEFTCODE [22mcolor-sequence[0m
              Specifies the left code for non-ISO 6429 terminals (see below).

       RIGHTCODE [22mcolor-sequence[0m
              Specifies the right code for non-ISO 6429 terminals (see below).

       ENDCODE [22mcolor-sequence[0m
              Specifies the end code for non-ISO 6429 terminals (see below).

       *extension color-sequence
              Specifies the color used for any file that ends in extension.

        .extension color-sequence
              Same as *.extension.  Specifies the color used for any file that
              ends in .extension.  Note that the period is included in the
              extension, which makes it impossible to specify an extension not
              starting with a period, such as ~ for emacs backup files.  This form
              should be considered obsolete.

ISO 6429 (ANSI) Color Sequences

       Most color-capable ASCII terminals today use ISO 6429 (ANSI) color
       sequences, and many common terminals without color capability, including
       xterm and the widely used and cloned DEC VT100, will recognize ISO 6429
       color codes and harmlessly eliminate them from the output or emulate them.
       ls uses ISO 6429 codes by default, assuming colorization is enabled.

       ISO 6429 color sequences are composed of sequences of numbers separated by
       semicolons.  The most common codes are:

          0     to restore default color
          1     for brighter colors
          4     for underlined text
          5     for flashing text
         30     for black foreground
         31     for red foreground
         32     for green foreground
         33     for yellow (or brown) foreground
         34     for blue foreground
         35     for purple foreground
         36     for cyan foreground
         37     for white (or gray) foreground
         40     for black background
         41     for red background
         42     for green background
         43     for yellow (or brown) background
         44     for blue background
         45     for purple background
         46     for cyan background
         47     for white (or gray) background

       Not all commands will work on all systems or display devices.

       ls uses the following defaults:

         NORMAL   0       Normal (nonfilename) text
         FILE     0       Regular file
         DIR      32      Directory
         LINK     36      Symbolic link
         ORPHAN   undefined       Orphaned symbolic link
         MISSING  undefined       Missing file
         FIFO     31      Named pipe (FIFO)
         SOCK     33      Socket
         BLK      44;37   Block device
         CHR      44;37   Character device
         EXEC     35      Executable file

       A few terminal programs do not recognize the default properly.  If all text
       gets colorized after you do a directory listing, change the NORMAL and FILE
       codes to the numerical codes for your normal foreground and background
       colors.

Other Terminal Types (Advanced Configuration)

       If you have a color-capable (or otherwise highlighting) terminal (or
       printer!) which uses a different set of codes, you can still generate a
       suitable setup.  To do so, you will have to use the LEFTCODE, RIGHTCODE,
       and ENDCODE definitions.

       When writing out a filename, ls generates the following output sequence:
       LEFTCODE typecode RIGHTCODE filename ENDCODE, where the typecode is the
       color sequence that depends on the type or name of file.  If the ENDCODE is
       undefined, the sequence LEFTCODE NORMAL RIGHTCODE will be used instead.
       The purpose of the left- and rightcodes is merely to reduce the amount of
       typing necessary (and to hide ugly escape codes away from the user).  If
       they are not appropriate for your terminal, you can eliminate them by
       specifying the respective keyword on a line by itself.

       NOTE: If the ENDCODE is defined in the global section of the setup file, it
       cannot be undefined in a terminal-specific section of the file.  This means
       any NORMAL definition will have no effect.  A different ENDCODE can,
       however, be specified, which would have the same effect.

Escape Sequences

       To specify control- or blank characters in the color sequences or filename
       extensions, either C-style \-escaped notation or stty-style ^-notation can
       be used.  The C-style notation includes the following characters:

         \a      Bell (ASCII 7)
         \b      Backspace (ASCII 8)
         \e      Escape (ASCII 27)
         \f      Form feed (ASCII 12)
         \n      Newline (ASCII 10)
         \r      Carriage Return (ASCII 13)
         \t      Tab (ASCII 9)
         \v      Vertical Tab (ASCII 11)
         \?      Delete (ASCII 127)
         \nnn Any character (octal notation)
         \xnnn        Any character (hexadecimal notation)
         \_      Space
         \\     Backslash (\)
         \^      Caret (^)
         \#      Hash mark (#)

       Please note that escapes are necessary to enter a space, backslash, caret,
       or any control character anywhere in the string, as well as a hash mark as
       the first character.

FILES top

       /etc/DIR_COLORS
              System-wide configuration file.

       ~/.dir_colors
              Per-user configuration file.

       This page describes the dir_colors file format as used in the fileutils-4.1
       package; other versions may differ slightly.

NOTES top

       The default LEFTCODE and RIGHTCODE definitions, which are used by ISO 6429
       terminals are:

         LEFTCODE  \e[
         RIGHTCODE m

       The default ENDCODE is undefined.

SEE ALSO top

       dircolors(1), ls(1), stty(1), xterm(1)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2001-12-26                       DIR_COLORS(5)


Linux man-pages: section 1

man-pages section 1

getent(1)
intro(1) 		ldd(1)
time(1)


Linux man-pages: section 2

man-pages section 2

accept(2)
accept4(2)
access(2)
acct(2)
add_key(2)
adjtimex(2)
afs_syscall(2)
alarm(2)
alloc_hugepages(2)
arch_prctl(2)
arm_fadvise(2)
arm_fadvise64_64(2)
arm_sync_file_range(2)
bdflush(2)
bind(2)
break(2)
brk(2)
cacheflush(2)
capget(2)
capset(2)
chdir(2)
chmod(2)
chown(2)
chown32(2)
chroot(2)
clock_getres(2)
clock_gettime(2)
clock_nanosleep(2)
clock_settime(2)
__clone2(2)
clone2(2)
clone(2)
close(2)
connect(2)
creat(2)
create_module(2)
delete_module(2)
dup2(2)
dup(2)
dup3(2)
epoll_create1(2)
epoll_create(2)
epoll_ctl(2)
epoll_pwait(2)
epoll_wait(2)
eventfd2(2)
eventfd(2)
execve(2)
_exit(2)
_Exit(2)
exit(2)
exit_group(2)
faccessat(2)
fadvise64(2)
fadvise64_64(2)
fallocate(2)
fchdir(2)
fchmod(2)
fchmodat(2)
fchown(2)
fchown32(2)
fchownat(2)
fcntl(2)
fcntl64(2)
fdatasync(2)
fgetxattr(2)
flistxattr(2)
flock(2)
fork(2)
free_hugepages(2)
fremovexattr(2)
fsetxattr(2)
fstat(2)
fstat64(2)
fstatat(2)
fstatat64(2)
fstatfs(2)
fstatfs64(2)
fstatvfs(2)
fsync(2)
ftruncate(2)
ftruncate64(2)
futex(2)
futimesat(2)
getcontext(2)
getcpu(2)
getcwd(2)
getdents(2)
getdents64(2)
getdomainname(2)
getdtablesize(2)
getegid(2)
getegid32(2)
geteuid(2)
geteuid32(2)
getgid(2)
getgid32(2)
getgroups(2)
getgroups32(2)
gethostid(2)
gethostname(2)
getitimer(2)
get_kernel_syms(2)
get_mempolicy(2)
getpagesize(2)
getpeername(2)
getpgid(2)
getpgrp(2)
getpid(2)
getpmsg(2)
getppid(2)
getpriority(2)
getresgid(2)
getresgid32(2)
getresuid(2)
getresuid32(2)
getrlimit(2)
get_robust_list(2)
getrusage(2)
getsid(2)
getsockname(2)
getsockopt(2)
get_thread_area(2)
gettid(2)
gettimeofday(2)
getuid(2)
getuid32(2)
getxattr(2)
gtty(2)
idle(2)
inb(2)
inb_p(2)
init_module(2)
inl(2)
inl_p(2)
inotify_add_watch(2)
inotify_init1(2)
inotify_init(2)
inotify_rm_watch(2)
insb(2)
insl(2)
insw(2)
intro(2)
inw(2)
inw_p(2)
io_cancel(2)
ioctl(2)
ioctl_list(2) 		io_destroy(2)
io_getevents(2)
ioperm(2)
iopl(2)
ioprio_get(2)
ioprio_set(2)
io_setup(2)
io_submit(2)
ipc(2)
kexec_load(2)
keyctl(2)
kill(2)
killpg(2)
lchown(2)
lchown32(2)
lgetxattr(2)
link(2)
linkat(2)
listen(2)
listxattr(2)
llistxattr(2)
_llseek(2)
llseek(2)
lock(2)
lookup_dcookie(2)
lremovexattr(2)
lseek(2)
lsetxattr(2)
lstat(2)
lstat64(2)
madvise1(2)
madvise(2)
mbind(2)
migrate_pages(2)
mincore(2)
mkdir(2)
mkdirat(2)
mknod(2)
mknodat(2)
mlock(2)
mlockall(2)
mmap2(2)
mmap(2)
modify_ldt(2)
mount(2)
move_pages(2)
mprotect(2)
mpx(2)
mq_getsetattr(2)
mq_notify(2)
mq_open(2)
mq_timedreceive(2)
mq_timedsend(2)
mq_unlink(2)
mremap(2)
msgctl(2)
msgget(2)
msgop(2)
msgrcv(2)
msgsnd(2)
msync(2)
munlock(2)
munlockall(2)
munmap(2)
nanosleep(2)
_newselect(2)
nfsservctl(2)
nice(2)
oldfstat(2)
oldlstat(2)
oldolduname(2)
oldstat(2)
olduname(2)
open(2)
openat(2)
outb(2)
outb_p(2)
outl(2)
outl_p(2)
outsb(2)
outsl(2)
outsw(2)
outw(2)
outw_p(2)
pause(2)
pciconfig_iobase(2)
pciconfig_read(2)
pciconfig_write(2)
personality(2)
phys(2)
pipe2(2)
pipe(2)
pivot_root(2)
poll(2)
posix_fadvise(2)
ppoll(2)
prctl(2)
pread(2)
pread64(2)
preadv(2)
prlimit(2)
process_vm_readv(2)
process_vm_writev(2)
prof(2)
pselect(2)
pselect6(2)
ptrace(2)
putpmsg(2)
pwrite(2)
pwrite64(2)
pwritev(2)
query_module(2)
quotactl(2)
read(2)
readahead(2)
readdir(2)
readlink(2)
readlinkat(2)
readv(2)
reboot(2)
recv(2)
recvfrom(2)
recvmmsg(2)
recvmsg(2)
remap_file_pages(2)
removexattr(2)
rename(2)
renameat(2)
request_key(2)
rmdir(2)
rt_sigaction(2)
rt_sigpending(2)
rt_sigprocmask(2)
rt_sigqueueinfo(2)
rt_sigreturn(2)
rt_sigsuspend(2)
rt_sigtimedwait(2)
rt_tgsigqueueinfo(2)
s390_runtime_instr(2)
sbrk(2)
sched_getaffinity(2)
sched_getparam(2)
sched_get_priority_max(2)
sched_get_priority_min(2)
sched_getscheduler(2)
sched_rr_get_interval(2)
sched_setaffinity(2)
sched_setparam(2) 		sched_setscheduler(2)
sched_yield(2)
security(2)
select(2)
select_tut(2)
semctl(2)
semget(2)
semop(2)
semtimedop(2)
send(2)
sendfile(2)
sendfile64(2)
sendmmsg(2)
sendmsg(2)
sendto(2)
setcontext(2)
setdomainname(2)
setegid(2)
seteuid(2)
setfsgid(2)
setfsgid32(2)
setfsuid(2)
setfsuid32(2)
setgid(2)
setgid32(2)
setgroups(2)
setgroups32(2)
sethostid(2)
sethostname(2)
setitimer(2)
set_mempolicy(2)
setns(2)
setpgid(2)
setpgrp(2)
setpriority(2)
setregid(2)
setregid32(2)
setresgid(2)
setresgid32(2)
setresuid(2)
setresuid32(2)
setreuid(2)
setreuid32(2)
setrlimit(2)
set_robust_list(2)
setsid(2)
setsockopt(2)
set_thread_area(2)
set_tid_address(2)
settimeofday(2)
setuid(2)
setuid32(2)
setup(2)
setxattr(2)
sgetmask(2)
shmat(2)
shmctl(2)
shmdt(2)
shmget(2)
shmop(2)
shutdown(2)
sigaction(2)
sigaltstack(2)
signal(2)
signalfd(2)
signalfd4(2)
sigpending(2)
sigprocmask(2)
sigqueue(2)
sigreturn(2)
sigsuspend(2)
sigtimedwait(2)
sigwaitinfo(2)
socket(2)
socketcall(2)
socketpair(2)
splice(2)
spu_create(2)
spu_run(2)
ssetmask(2)
stat(2)
stat64(2)
statfs(2)
statfs64(2)
statvfs(2)
stime(2)
stty(2)
subpage_prot(2)
swapoff(2)
swapon(2)
symlink(2)
symlinkat(2)
sync(2)
sync_file_range2(2)
sync_file_range(2)
syncfs(2)
_syscall(2)
syscall(2)
syscalls(2)
_sysctl(2)
sysctl(2)
sysfs(2)
sysinfo(2)
syslog(2)
tee(2)
tgkill(2)
time(2)
timer_create(2)
timer_delete(2)
timerfd_create(2)
timerfd_gettime(2)
timerfd_settime(2)
timer_getoverrun(2)
timer_gettime(2)
timer_settime(2)
times(2)
tkill(2)
truncate(2)
truncate64(2)
tuxcall(2)
ugetrlimit(2)
umask(2)
umount2(2)
umount(2)
uname(2)
unimplemented(2)
unlink(2)
unlinkat(2)
unshare(2)
uselib(2)
ustat(2)
utime(2)
utimensat(2)
utimes(2)
vfork(2)
vhangup(2)
vm86(2)
vm86old(2)
vmsplice(2)
vserver(2)
wait(2)
wait3(2)
wait4(2)
waitid(2)
waitpid(2)
write(2)
writev(2)


Linux man-pages: section 3

man-pages section 3

a64l(3)
abort(3)
abs(3)
acos(3)
acosf(3)
acosh(3)
acoshf(3)
acoshl(3)
acosl(3)
addmntent(3)
addseverity(3)
adjtime(3)
aio_cancel(3)
aio_error(3)
aio_fsync(3)
aio_init(3)
aio_read(3)
aio_return(3)
aio_suspend(3)
aio_write(3)
aligned_alloc(3)
alloca(3)
alphasort(3)
argz(3)
argz_add(3)
argz_add_sep(3)
argz_append(3)
argz_count(3)
argz_create(3)
argz_create_sep(3)
argz_delete(3)
argz_extract(3)
argz_insert(3)
argz_next(3)
argz_replace(3)
argz_stringify(3)
asctime(3)
asctime_r(3)
asin(3)
asinf(3)
asinh(3)
asinhf(3)
asinhl(3)
asinl(3)
asprintf(3)
assert(3)
assert_perror(3)
atan2(3)
atan2f(3)
atan2l(3)
atan(3)
atanf(3)
atanh(3)
atanhf(3)
atanhl(3)
atanl(3)
atexit(3)
atof(3)
atoi(3)
atol(3)
atoll(3)
atoq(3)
auth_destroy(3)
authnone_create(3)
authunix_create(3)
authunix_create_default(3)
backtrace(3)
backtrace_symbols(3)
backtrace_symbols_fd(3)
basename(3)
bcmp(3)
bcopy(3)
be16toh(3)
be32toh(3)
be64toh(3)
bindresvport(3)
bsd_signal(3)
bsearch(3)
bstring(3)
btowc(3)
btree(3)
byteorder(3)
bzero(3)
cabs(3)
cabsf(3)
cabsl(3)
cacos(3)
cacosf(3)
cacosh(3)
cacoshf(3)
cacoshl(3)
cacosl(3)
calloc(3)
callrpc(3)
canonicalize_file_name(3)
carg(3)
cargf(3)
cargl(3)
casin(3)
casinf(3)
casinh(3)
casinhf(3)
casinhl(3)
casinl(3)
catan(3)
catanf(3)
catanh(3)
catanhf(3)
catanhl(3)
catanl(3)
catclose(3)
catgets(3)
catopen(3)
cbc_crypt(3)
cbrt(3)
cbrtf(3)
cbrtl(3)
ccos(3)
ccosf(3)
ccosh(3)
ccoshf(3)
ccoshl(3)
ccosl(3)
ceil(3)
ceilf(3)
ceill(3)
cerf(3)
cerfc(3)
cerfcf(3)
cerfcl(3)
cerff(3)
cerfl(3)
cexp2(3)
cexp2f(3)
cexp2l(3)
cexp(3)
cexpf(3)
cexpl(3)
cfgetispeed(3)
cfgetospeed(3)
cfmakeraw(3)
cfree(3)
cfsetispeed(3)
cfsetospeed(3)
cfsetspeed(3)
cimag(3)
cimagf(3)
cimagl(3)
CIRCLEQ_ENTRY(3)
CIRCLEQ_HEAD(3)
CIRCLEQ_INIT(3)
CIRCLEQ_INSERT_AFTER(3)
CIRCLEQ_INSERT_BEFORE(3)
CIRCLEQ_INSERT_HEAD(3)
CIRCLEQ_INSERT_TAIL(3)
CIRCLEQ_REMOVE(3)
clearenv(3)
clearerr(3)
clearerr_unlocked(3)
clnt_broadcast(3)
clnt_call(3)
clnt_control(3)
clnt_create(3)
clnt_destroy(3)
clnt_freeres(3)
clnt_geterr(3)
clnt_pcreateerror(3)
clnt_perrno(3)
clnt_perror(3)
clntraw_create(3)
clnt_spcreateerror(3)
clnt_sperrno(3)
clnt_sperror(3)
clnttcp_create(3)
clntudp_bufcreate(3)
clntudp_create(3)
clock(3)
clock_getcpuclockid(3)
clock_getres(3)
clock_gettime(3)
clock_settime(3)
clog10(3)
clog10f(3)
clog10l(3)
clog2(3)
clog2f(3)
clog2l(3)
clog(3)
clogf(3)
clogl(3)
closedir(3)
closelog(3)
cmsg(3)
CMSG_ALIGN(3)
CMSG_FIRSTHDR(3)
CMSG_NXTHDR(3)
CMSG_SPACE(3)
confstr(3)
conj(3)
conjf(3)
conjl(3)
copysign(3)
copysignf(3)
copysignl(3)
cos(3)
cosf(3)
cosh(3)
coshf(3)
coshl(3)
cosl(3)
cpow(3)
cpowf(3)
cpowl(3)
cproj(3)
cprojf(3)
cprojl(3)
CPU_ALLOC(3)
CPU_ALLOC_SIZE(3)
CPU_AND(3)
CPU_AND_S(3)
CPU_CLR(3)
CPU_CLR_S(3)
CPU_COUNT(3)
CPU_COUNT_S(3)
CPU_EQUAL(3)
CPU_EQUAL_S(3)
CPU_FREE(3)
CPU_ISSET(3)
CPU_ISSET_S(3)
CPU_OR(3)
CPU_OR_S(3)
CPU_SET(3)
CPU_SET_S(3)
CPU_XOR(3)
CPU_XOR_S(3)
CPU_ZERO(3)
CPU_ZERO_S(3)
creal(3)
crealf(3)
creall(3)
crypt(3)
crypt_r(3)
csin(3)
csinf(3)
csinh(3)
csinhf(3)
csinhl(3)
csinl(3)
csqrt(3)
csqrtf(3)
csqrtl(3)
ctan(3)
ctanf(3)
ctanh(3)
ctanhf(3)
ctanhl(3)
ctanl(3)
ctermid(3)
ctime(3)
ctime_r(3)
cuserid(3)
daemon(3)
daylight(3)
db(3)
dbopen(3)
des_crypt(3)
DES_FAILED(3)
des_setparity(3)
difftime(3)
dirfd(3)
dirname(3)
div(3)
dladdr(3)
dlclose(3)
dlerror(3)
dl_iterate_phdr(3)
dlopen(3)
dlsym(3)
dlvsym(3)
dn_comp(3)
dn_expand(3)
dprintf(3)
drand48(3)
drand48_r(3)
drem(3)
dremf(3)
dreml(3)
dysize(3)
eaccess(3)
ecb_crypt(3)
ecvt(3)
ecvt_r(3)
edata(3)
encrypt(3)
encrypt_r(3)
end(3)
endaliasent(3)
endfsent(3)
endgrent(3)
endhostent(3)
endian(3)
endmntent(3)
endnetent(3)
endnetgrent(3)
endprotoent(3)
endpwent(3)
endrpcent(3)
endservent(3)
endspent(3)
endttyent(3)
endusershell(3)
endutent(3)
endutxent(3)
envz(3)
envz_add(3)
envz_entry(3)
envz_get(3)
envz_merge(3)
envz_remove(3)
envz_strip(3)
erand48(3)
erand48_r(3)
erf(3)
erfc(3)
erfcf(3)
erfcl(3)
erff(3)
erfl(3)
err(3)
errno(3)
error(3)
error_at_line(3)
error_message_count(3)
error_one_per_line(3)
error_print_progname(3)
errx(3)
etext(3)
ether_aton(3)
ether_aton_r(3)
ether_hostton(3)
ether_line(3)
ether_ntoa(3)
ether_ntoa_r(3)
ether_ntohost(3)
euidaccess(3)
eventfd_read(3)
eventfd_write(3)
exec(3)
execl(3)
execle(3)
execlp(3)
execv(3)
execvp(3)
execvpe(3)
exit(3)
exp10(3)
exp10f(3)
exp10l(3)
exp2(3)
exp2f(3)
exp2l(3)
exp(3)
expf(3)
expl(3)
expm1(3)
expm1f(3)
expm1l(3)
fabs(3)
fabsf(3)
fabsl(3)
__fbufsize(3)
fclose(3)
fcloseall(3)
fcvt(3)
fcvt_r(3)
FD_CLR(3)
fdim(3)
fdimf(3)
fdiml(3)
FD_ISSET(3)
fdopen(3)
fdopendir(3)
FD_SET(3)
FD_ZERO(3)
feclearexcept(3)
fedisableexcept(3)
feenableexcept(3)
fegetenv(3)
fegetexcept(3)
fegetexceptflag(3)
fegetround(3)
feholdexcept(3)
fenv(3)
feof(3)
feof_unlocked(3)
feraiseexcept(3)
ferror(3)
ferror_unlocked(3)
fesetenv(3)
fesetexceptflag(3)
fesetround(3)
fetestexcept(3)
feupdateenv(3)
fexecve(3)
fflush(3)
fflush_unlocked(3)
ffs(3)
ffsl(3)
ffsll(3)
fgetc(3)
fgetc_unlocked(3)
fgetgrent(3)
fgetgrent_r(3)
fgetpos(3)
fgetpwent(3)
fgetpwent_r(3)
fgets(3)
fgetspent(3)
fgetspent_r(3)
fgets_unlocked(3)
fgetwc(3)
fgetwc_unlocked(3)
fgetws(3)
fgetws_unlocked(3)
fileno(3)
fileno_unlocked(3)
finite(3)
finitef(3)
finitel(3)
__flbf(3)
flockfile(3)
floor(3)
floorf(3)
floorl(3)
_flushlbf(3)
fma(3)
fmaf(3)
fmal(3)
fmax(3)
fmaxf(3)
fmaxl(3)
fmemopen(3)
fmin(3)
fminf(3)
fminl(3)
fmod(3)
fmodf(3)
fmodl(3)
fmtmsg(3)
fnmatch(3)
fopen(3)
fopencookie(3)
forkpty(3)
fpathconf(3)
fpclassify(3)
__fpending(3)
fprintf(3)
__fpurge(3)
fpurge(3)
fputc(3)
fputc_unlocked(3)
fputs(3)
fputs_unlocked(3)
fputwc(3)
fputwc_unlocked(3)
fputws(3)
fputws_unlocked(3)
fread(3)
__freadable(3)
__freading(3)
fread_unlocked(3)
free(3)
freeaddrinfo(3)
freehostent(3)
freeifaddrs(3)
freopen(3)
frexp(3)
frexpf(3)
frexpl(3)
fscanf(3)
fseek(3)
fseeko(3)
__fsetlocking(3)
fsetpos(3)
fstatvfs(3)
ftell(3)
ftello(3)
ftime(3)
ftok(3)
ftrylockfile(3)
fts(3)
fts_children(3)
fts_close(3)
fts_open(3)
fts_read(3) 		fts_set(3)
ftw(3)
funlockfile(3)
futimens(3)
futimes(3)
fwide(3)
fwprintf(3)
__fwritable(3)
fwrite(3)
fwrite_unlocked(3)
__fwriting(3)
gai_cancel(3)
gai_error(3)
gai_strerror(3)
gai_suspend(3)
gamma(3)
gammaf(3)
gammal(3)
gcvt(3)
getaddrinfo(3)
getaddrinfo_a(3)
getaliasbyname(3)
getaliasbyname_r(3)
getaliasent(3)
getaliasent_r(3)
getauxval(3)
getc(3)
getchar(3)
getchar_unlocked(3)
getc_unlocked(3)
get_current_dir_name(3)
getcwd(3)
getdate(3)
getdate_err(3)
getdate_r(3)
getdelim(3)
getdirentries(3)
getenv(3)
getfsent(3)
getfsfile(3)
getfsspec(3)
getgrent(3)
getgrent_r(3)
getgrgid(3)
getgrgid_r(3)
getgrnam(3)
getgrnam_r(3)
getgrouplist(3)
gethostbyaddr(3)
gethostbyaddr_r(3)
gethostbyname2(3)
gethostbyname2_r(3)
gethostbyname(3)
gethostbyname_r(3)
gethostent(3)
gethostent_r(3)
gethostid(3)
getifaddrs(3)
getipnodebyaddr(3)
getipnodebyname(3)
getline(3)
getloadavg(3)
getlogin(3)
getlogin_r(3)
getmntent(3)
getmntent_r(3)
get_myaddress(3)
getnameinfo(3)
getnetbyaddr(3)
getnetbyaddr_r(3)
getnetbyname(3)
getnetbyname_r(3)
getnetent(3)
getnetent_r(3)
getnetgrent(3)
getnetgrent_r(3)
get_nprocs(3)
get_nprocs_conf(3)
getopt(3)
getopt_long(3)
getopt_long_only(3)
getpass(3)
getprotobyname(3)
getprotobyname_r(3)
getprotobynumber(3)
getprotobynumber_r(3)
getprotoent(3)
getprotoent_r(3)
getpt(3)
getpw(3)
getpwent(3)
getpwent_r(3)
getpwnam(3)
getpwnam_r(3)
getpwuid(3)
getpwuid_r(3)
getrpcbyname(3)
getrpcbyname_r(3)
getrpcbynumber(3)
getrpcbynumber_r(3)
getrpcent(3)
getrpcent_r(3)
getrpcport(3)
gets(3)
getservbyname(3)
getservbyname_r(3)
getservbyport(3)
getservbyport_r(3)
getservent(3)
getservent_r(3)
getspent(3)
getspent_r(3)
getspnam(3)
getspnam_r(3)
getsubopt(3)
getttyent(3)
getttynam(3)
getumask(3)
getusershell(3)
getutent(3)
getutent_r(3)
getutid(3)
getutid_r(3)
getutline(3)
getutline_r(3)
getutmp(3)
getutmpx(3)
getutxent(3)
getutxid(3)
getutxline(3)
getw(3)
getwc(3)
getwchar(3)
getwchar_unlocked(3)
getwc_unlocked(3)
getwd(3)
glob(3)
globfree(3)
gmtime(3)
gmtime_r(3)
gnu_dev_major(3)
gnu_dev_makedev(3)
gnu_dev_minor(3)
gnu_get_libc_release(3)
gnu_get_libc_version(3)
grantpt(3)
gsignal(3)
hash(3)
hasmntopt(3)
hcreate(3)
hcreate_r(3)
hdestroy(3)
hdestroy_r(3)
h_errno(3)
herror(3)
hsearch(3)
hsearch_r(3)
hstrerror(3)
htobe16(3)
htobe32(3)
htobe64(3)
htole16(3)
htole32(3)
htole64(3)
htonl(3)
htons(3)
HUGE_VAL(3)
HUGE_VALF(3)
HUGE_VALL(3)
hypot(3)
hypotf(3)
hypotl(3)
iconv(3)
iconv_close(3)
iconv_open(3)
if_freenameindex(3)
if_indextoname(3)
if_nameindex(3)
if_nametoindex(3)
ilogb(3)
ilogbf(3)
ilogbl(3)
imaxabs(3)
imaxdiv(3)
index(3)
inet(3)
inet_addr(3)
inet_aton(3)
inet_lnaof(3)
inet_makeaddr(3)
inet_netof(3)
inet_network(3)
inet_ntoa(3)
inet_ntop(3)
inet_pton(3)
INFINITY(3)
infnan(3)
initgroups(3)
initstate(3)
initstate_r(3)
innetgr(3)
insque(3)
intro(3)
iruserok(3)
iruserok_af(3)
isalnum(3)
isalpha(3)
isascii(3)
isatty(3)
isblank(3)
iscntrl(3)
isdigit(3)
isfinite(3)
isgraph(3)
isgreater(3)
isgreaterequal(3)
isinf(3)
isinff(3)
isinfl(3)
isless(3)
islessequal(3)
islessgreater(3)
islower(3)
isnan(3)
isnanf(3)
isnanl(3)
isnormal(3)
isprint(3)
ispunct(3)
isspace(3)
isunordered(3)
isupper(3)
iswalnum(3)
iswalpha(3)
iswblank(3)
iswcntrl(3)
iswctype(3)
iswdigit(3)
iswgraph(3)
iswlower(3)
iswprint(3)
iswpunct(3)
iswspace(3)
iswupper(3)
iswxdigit(3)
isxdigit(3)
j0(3)
j0f(3)
j0l(3)
j1(3)
j1f(3)
j1l(3)
jn(3)
jnf(3)
jnl(3)
jrand48(3)
jrand48_r(3)
key_decryptsession(3)
key_encryptsession(3)
key_gendes(3)
key_secretkey_is_set(3)
key_setsecret(3)
klogctl(3)
l64a(3)
labs(3)
lckpwdf(3)
lcong48(3)
lcong48_r(3)
ldexp(3)
ldexpf(3)
ldexpl(3)
ldiv(3)
le16toh(3)
le32toh(3)
le64toh(3)
lfind(3)
lgamma(3)
lgammaf(3)
lgammaf_r(3)
lgammal(3)
lgammal_r(3)
lgamma_r(3)
lio_listio(3)
LIST_ENTRY(3)
LIST_HEAD(3)
LIST_INIT(3)
LIST_INSERT_AFTER(3)
LIST_INSERT_HEAD(3)
LIST_REMOVE(3)
llabs(3)
lldiv(3)
llrint(3)
llrintf(3)
llrintl(3)
llround(3)
llroundf(3)
llroundl(3)
localeconv(3)
localtime(3)
localtime_r(3)
lockf(3)
log10(3)
log10f(3)
log10l(3)
log1p(3)
log1pf(3)
log1pl(3)
log2(3)
log2f(3)
log2l(3)
log(3)
logb(3)
logbf(3)
logbl(3)
logf(3)
login(3)
login_tty(3)
logl(3)
logout(3)
logwtmp(3)
longjmp(3)
lrand48(3)
lrand48_r(3)
lrint(3)
lrintf(3)
lrintl(3)
lround(3)
lroundf(3)
lroundl(3)
lsearch(3)
lseek64(3)
lutimes(3)
major(3)
makecontext(3)
makedev(3)
mallinfo(3)
malloc(3)
malloc_get_state(3)
__malloc_hook(3)
malloc_hook(3)
malloc_info(3)
malloc_set_state(3)
malloc_stats(3)
malloc_trim(3)
malloc_usable_size(3)
mallopt(3)
matherr(3)
MB_CUR_MAX(3)
mblen(3)
MB_LEN_MAX(3)
mbrlen(3)
mbrtowc(3)
mbsinit(3)
mbsnrtowcs(3)
mbsrtowcs(3)
mbstowcs(3)
mbtowc(3)
mcheck(3)
mcheck_check_all(3)
mcheck_pedantic(3)
memalign(3)
memccpy(3)
memchr(3)
memcmp(3)
memcpy(3)
memfrob(3)
memmem(3)
memmove(3)
mempcpy(3)
memrchr(3)
memset(3)
minor(3)
mkdtemp(3)
mkfifo(3)
mkfifoat(3)
mkostemp(3)
mkostemps(3)
mkstemp(3)
mkstemps(3)
mktemp(3)
mktime(3)
mmap64(3)
modf(3)
modff(3)
modfl(3)
mpool(3)
mprobe(3)
mq_close(3)
mq_getattr(3)
mq_notify(3)
mq_open(3)
mq_receive(3)
mq_send(3)
mq_setattr(3)
mq_timedreceive(3)
mq_timedsend(3)
mq_unlink(3)
mrand48(3)
mrand48_r(3)
mtrace(3)
muntrace(3)
nan(3)
NAN(3)
nanf(3)
nanl(3)
nearbyint(3)
nearbyintf(3)
nearbyintl(3)
netlink(3)
nextafter(3)
nextafterf(3)
nextafterl(3)
nexttoward(3)
nexttowardf(3)
nexttowardl(3)
nftw(3)
nl_langinfo(3)
nrand48(3)
nrand48_r(3)
ntohl(3)
ntohs(3)
offsetof(3)
on_exit(3)
opendir(3)
openlog(3)
open_memstream(3)
openpty(3)
open_wmemstream(3)
optarg(3)
opterr(3)
optind(3)
optopt(3)
passwd2des(3)
pathconf(3)
pclose(3)
perror(3)
pmap_getmaps(3)
pmap_getport(3)
pmap_rmtcall(3)
pmap_set(3)
pmap_unset(3)
popen(3)
posix_fallocate(3)
posix_memalign(3)
posix_openpt(3)
pow10(3)
pow10f(3)
pow10l(3)
pow(3)
powf(3)
powl(3)
printf(3)
profil(3)
program_invocation_name(3)
program_invocation_short_name(3)
psiginfo(3)
psignal(3)
pthread_attr_destroy(3)
pthread_attr_getaffinity_np(3)
pthread_attr_getdetachstate(3)
pthread_attr_getguardsize(3)
pthread_attr_getinheritsched(3)
pthread_attr_getschedparam(3)
pthread_attr_getschedpolicy(3)
pthread_attr_getscope(3)
pthread_attr_getstack(3)
pthread_attr_getstackaddr(3)
pthread_attr_getstacksize(3)
pthread_attr_init(3)
pthread_attr_setaffinity_np(3)
pthread_attr_setdetachstate(3)
pthread_attr_setguardsize(3)
pthread_attr_setinheritsched(3)
pthread_attr_setschedparam(3)
pthread_attr_setschedpolicy(3)
pthread_attr_setscope(3)
pthread_attr_setstack(3)
pthread_attr_setstackaddr(3)
pthread_attr_setstacksize(3)
pthread_cancel(3)
pthread_cleanup_pop(3)
pthread_cleanup_pop_restore_np(3)
pthread_cleanup_push(3)
pthread_cleanup_push_defer_np(3)
pthread_create(3)
pthread_detach(3)
pthread_equal(3)
pthread_exit(3)
pthread_getaffinity_np(3)
pthread_getattr_np(3)
pthread_getconcurrency(3)
pthread_getcpuclockid(3)
pthread_getschedparam(3)
pthread_join(3)
pthread_kill(3) 		pthread_kill_other_threads_np(3)
pthread_self(3)
pthread_setaffinity_np(3)
pthread_setcancelstate(3)
pthread_setcanceltype(3)
pthread_setconcurrency(3)
pthread_setschedparam(3)
pthread_setschedprio(3)
pthread_sigmask(3)
pthread_sigqueue(3)
pthread_testcancel(3)
pthread_timedjoin_np(3)
pthread_tryjoin_np(3)
pthread_yield(3)
ptsname(3)
ptsname_r(3)
putc(3)
putchar(3)
putchar_unlocked(3)
putc_unlocked(3)
putenv(3)
putgrent(3)
putpwent(3)
puts(3)
putspent(3)
pututline(3)
pututxline(3)
putw(3)
putwc(3)
putwchar(3)
putwchar_unlocked(3)
putwc_unlocked(3)
pvalloc(3)
qecvt(3)
qecvt_r(3)
qfcvt(3)
qfcvt_r(3)
qgcvt(3)
qsort(3)
qsort_r(3)
queue(3)
raise(3)
rand(3)
random(3)
random_r(3)
rand_r(3)
rawmemchr(3)
rcmd(3)
rcmd_af(3)
readdir(3)
readdir_r(3)
realloc(3)
realpath(3)
recno(3)
re_comp(3)
re_exec(3)
regcomp(3)
regerror(3)
regex(3)
regexec(3)
regfree(3)
registerrpc(3)
remainder(3)
remainderf(3)
remainderl(3)
remove(3)
remque(3)
remquo(3)
remquof(3)
remquol(3)
res_init(3)
res_mkquery(3)
resolver(3)
res_query(3)
res_querydomain(3)
res_search(3)
res_send(3)
rewind(3)
rewinddir(3)
rexec(3)
rexec_af(3)
rindex(3)
rint(3)
rintf(3)
rintl(3)
round(3)
roundf(3)
roundl(3)
rpc(3)
rpmatch(3)
rresvport(3)
rresvport_af(3)
rtime(3)
rtnetlink(3)
ruserok(3)
ruserok_af(3)
scalb(3)
scalbf(3)
scalbl(3)
scalbln(3)
scalblnf(3)
scalblnl(3)
scalbn(3)
scalbnf(3)
scalbnl(3)
scandir(3)
scandirat(3)
scanf(3)
sched_getcpu(3)
secure_getenv(3)
seed48(3)
seed48_r(3)
seekdir(3)
sem_close(3)
sem_destroy(3)
sem_getvalue(3)
sem_init(3)
sem_open(3)
sem_post(3)
sem_timedwait(3)
sem_trywait(3)
sem_unlink(3)
sem_wait(3)
setaliasent(3)
setbuf(3)
setbuffer(3)
setenv(3)
__setfpucw(3)
setfsent(3)
setgrent(3)
sethostent(3)
sethostid(3)
setjmp(3)
setkey(3)
setkey_r(3)
setlinebuf(3)
setlocale(3)
setlogmask(3)
setmntent(3)
setnetent(3)
setnetgrent(3)
setprotoent(3)
setpwent(3)
setrpcent(3)
setservent(3)
setspent(3)
setstate(3)
setstate_r(3)
setttyent(3)
setusershell(3)
setutent(3)
setutxent(3)
setvbuf(3)
sgetspent(3)
sgetspent_r(3)
shm_open(3)
shm_unlink(3)
sigaddset(3)
sigandset(3)
sigblock(3)
sigdelset(3)
sigemptyset(3)
sigfillset(3)
siggetmask(3)
sighold(3)
sigignore(3)
siginterrupt(3)
sigisemptyset(3)
sigismember(3)
siglongjmp(3)
sigmask(3)
signbit(3)
signgam(3)
significand(3)
significandf(3)
significandl(3)
sigorset(3)
sigpause(3)
sigqueue(3)
sigrelse(3)
sigset(3)
sigsetjmp(3)
sigsetmask(3)
sigsetops(3)
sigstack(3)
sigvec(3)
sigwait(3)
sin(3)
sincos(3)
sincosf(3)
sincosl(3)
sinf(3)
sinh(3)
sinhf(3)
sinhl(3)
sinl(3)
sleep(3)
snprintf(3)
sockatmark(3)
sprintf(3)
sqrt(3)
sqrtf(3)
sqrtl(3)
srand(3)
srand48(3)
srand48_r(3)
srandom(3)
srandom_r(3)
sscanf(3)
ssignal(3)
statvfs(3)
stdarg(3)
stderr(3)
stdin(3)
stdio(3)
stdio_ext(3)
stdout(3)
stpcpy(3)
stpncpy(3)
strcasecmp(3)
strcasestr(3)
strcat(3)
strchr(3)
strchrnul(3)
strcmp(3)
strcoll(3)
strcpy(3)
strcspn(3)
strdup(3)
strdupa(3)
strerror(3)
strerror_r(3)
strfmon(3)
strfry(3)
strftime(3)
string(3)
strlen(3)
strncasecmp(3)
strncat(3)
strncmp(3)
strncpy(3)
strndup(3)
strndupa(3)
strnlen(3)
strpbrk(3)
strptime(3)
strrchr(3)
strsep(3)
strsignal(3)
strspn(3)
strstr(3)
strtod(3)
strtof(3)
strtoimax(3)
strtok(3)
strtok_r(3)
strtol(3)
strtold(3)
strtoll(3)
strtoq(3)
strtoul(3)
strtoull(3)
strtoumax(3)
strtouq(3)
strverscmp(3)
strxfrm(3)
svc_destroy(3)
svcerr_auth(3)
svcerr_decode(3)
svcerr_noproc(3)
svcerr_noprog(3)
svcerr_progvers(3)
svcerr_systemerr(3)
svcerr_weakauth(3)
svcfd_create(3)
svc_freeargs(3)
svc_getargs(3)
svc_getcaller(3)
svc_getreq(3)
svc_getreqset(3)
svcraw_create(3)
svc_register(3)
svc_run(3)
svc_sendreply(3)
svctcp_create(3)
svcudp_bufcreate(3)
svcudp_create(3)
svc_unregister(3)
swab(3)
swapcontext(3)
swprintf(3)
sysconf(3)
sys_errlist(3)
syslog(3)
sys_nerr(3)
system(3)
sysv_signal(3)
TAILQ_ENTRY(3)
TAILQ_HEAD(3)
TAILQ_INIT(3)
TAILQ_INSERT_AFTER(3)
TAILQ_INSERT_HEAD(3)
TAILQ_INSERT_TAIL(3)
TAILQ_REMOVE(3)
tan(3)
tanf(3)
tanh(3)
tanhf(3)
tanhl(3)
tanl(3)
tcdrain(3)
tcflow(3)
tcflush(3)
tcgetattr(3)
tcgetpgrp(3)
tcgetsid(3)
tcsendbreak(3)
tcsetattr(3)
tcsetpgrp(3)
tdelete(3)
tdestroy(3)
telldir(3)
tempnam(3)
termios(3)
tfind(3)
tgamma(3)
tgammaf(3)
tgammal(3)
timegm(3)
timelocal(3)
timeradd(3)
timerclear(3)
timercmp(3)
timerisset(3)
timersub(3)
timezone(3)
tmpfile(3)
tmpnam(3)
tmpnam_r(3)
toascii(3)
tolower(3)
toupper(3)
towctrans(3)
towlower(3)
towupper(3)
trunc(3)
truncf(3)
truncl(3)
tsearch(3)
ttyname(3)
ttyname_r(3)
ttyslot(3)
twalk(3)
tzname(3)
tzset(3)
ualarm(3)
ulckpwdf(3)
ulimit(3)
undocumented(3)
ungetc(3)
ungetwc(3)
unlocked_stdio(3)
unlockpt(3)
unsetenv(3)
updwtmp(3)
updwtmpx(3)
usleep(3)
utmpname(3)
utmpxname(3)
va_arg(3)
va_copy(3)
va_end(3)
valloc(3)
vasprintf(3)
va_start(3)
vdprintf(3)
verr(3)
verrx(3)
versionsort(3)
vfprintf(3)
vfscanf(3)
vfwprintf(3)
vlimit(3)
vprintf(3)
vscanf(3)
vsnprintf(3)
vsprintf(3)
vsscanf(3)
vswprintf(3)
vsyslog(3)
vtimes(3)
vwarn(3)
vwarnx(3)
vwprintf(3)
warn(3)
warnx(3)
wcpcpy(3)
wcpncpy(3)
wcrtomb(3)
wcscasecmp(3)
wcscat(3)
wcschr(3)
wcscmp(3)
wcscpy(3)
wcscspn(3)
wcsdup(3)
wcslen(3)
wcsncasecmp(3)
wcsncat(3)
wcsncmp(3)
wcsncpy(3)
wcsnlen(3)
wcsnrtombs(3)
wcspbrk(3)
wcsrchr(3)
wcsrtombs(3)
wcsspn(3)
wcsstr(3)
wcstoimax(3)
wcstok(3)
wcstombs(3)
wcstoumax(3)
wcswidth(3)
wctob(3)
wctomb(3)
wctrans(3)
wctype(3)
wcwidth(3)
wmemchr(3)
wmemcmp(3)
wmemcpy(3)
wmemmove(3)
wmempcpy(3)
wmemset(3)
wordexp(3)
wordfree(3)
wprintf(3)
xcrypt(3)
xdecrypt(3)
xdr(3)
xdr_accepted_reply(3)
xdr_array(3)
xdr_authunix_parms(3)
xdr_bool(3)
xdr_bytes(3)
xdr_callhdr(3)
xdr_callmsg(3)
xdr_char(3)
xdr_destroy(3)
xdr_double(3)
xdr_enum(3)
xdr_float(3)
xdr_free(3)
xdr_getpos(3)
xdr_inline(3)
xdr_int(3)
xdr_long(3)
xdrmem_create(3)
xdr_opaque(3)
xdr_opaque_auth(3)
xdr_pmap(3)
xdr_pmaplist(3)
xdr_pointer(3)
xdrrec_create(3)
xdrrec_endofrecord(3)
xdrrec_eof(3)
xdrrec_skiprecord(3)
xdr_reference(3)
xdr_rejected_reply(3)
xdr_replymsg(3)
xdr_setpos(3)
xdr_short(3)
xdrstdio_create(3)
xdr_string(3)
xdr_u_char(3)
xdr_u_int(3)
xdr_u_long(3)
xdr_union(3)
xdr_u_short(3)
xdr_vector(3)
xdr_void(3)
xdr_wrapstring(3)
xencrypt(3)
xprt_register(3)
xprt_unregister(3)
y0(3)
y0f(3)
y0l(3)
y1(3)
y1f(3)
y1l(3)
yn(3)
ynf(3)
ynl(3)


Linux man-pages: section 4

man-pages section 4

cciss(4)
console(4)
console_codes(4)
console_ioctl(4)
cpuid(4)
dsp56k(4)
fd(4)
full(4)
hd(4)
hpsa(4)
initrd(4)
intro(4) 		kmem(4)
lp(4)
mem(4)
mouse(4)
msr(4)
null(4)
port(4)
ptmx(4)
pts(4)
ram(4)
random(4)
rtc(4) 		sd(4)
sk98lin(4)
st(4)
tty(4)
tty_ioctl(4)
ttyS(4)
urandom(4)
vcs(4)
vcsa(4)
wavelan(4)
zero(4)


Linux man-pages: section 5

man-pages section 5

acct(5)
charmap(5)
core(5)
dir_colors(5)
elf(5)
filesystems(5)
fs(5)
ftpusers(5)
group(5)
host.conf(5)
hosts(5)
hosts.equiv(5)
intro(5) 		ipc(5)
issue(5)
locale(5)
motd(5)
networks(5)
nologin(5)
nscd.conf(5)
nsswitch.conf(5)
numa_maps(5)
passwd(5)
proc(5)
protocols(5)
resolv.conf(5) 		resolver(5)
rpc(5)
securetty(5)
services(5)
shells(5)
slabinfo(5)
termcap(5)
ttytype(5)
tzfile(5)
utmp(5)
utmpx(5)
wtmp(5)


Linux man-pages: section 6

man-pages section 6

intro(6)


Linux man-pages: section 7

man-pages section 7

aio(7)
armscii-8(7)
arp(7)
ascii(7)
boot(7)
bootparam(7)
capabilities(7)
charsets(7)
complex(7)
cp1251(7)
cpuset(7)
credentials(7)
ddp(7)
environ(7)
epoll(7)
feature_test_macros(7)
fifo(7)
futex(7)
glibc(7)
glob(7)
hier(7)
hostname(7)
icmp(7)
inotify(7)
intro(7)
ip(7)
ipv6(7)
iso-8859-10(7)
iso_8859-10(7)
iso_8859_10(7)
iso-8859-11(7)
iso_8859-11(7)
iso_8859_11(7)
iso-8859-13(7)
iso_8859-13(7)
iso_8859_13(7)
iso-8859-14(7)
iso_8859-14(7)
iso_8859_14(7)
iso-8859-15(7)
iso_8859-15(7)
iso_8859_15(7)
iso-8859-16(7)
iso_8859-16(7) 		iso_8859_16(7)
iso-8859-1(7)
iso_8859-1(7)
iso_8859_1(7)
iso-8859-2(7)
iso_8859-2(7)
iso_8859_2(7)
iso-8859-3(7)
iso_8859-3(7)
iso_8859_3(7)
iso-8859-4(7)
iso_8859-4(7)
iso_8859_4(7)
iso-8859-5(7)
iso_8859-5(7)
iso_8859_5(7)
iso-8859-6(7)
iso_8859-6(7)
iso_8859_6(7)
iso-8859-7(7)
iso_8859-7(7)
iso_8859_7(7)
iso-8859-8(7)
iso_8859-8(7)
iso_8859_8(7)
iso-8859-9(7)
iso_8859-9(7)
iso_8859_9(7)
koi8-r(7)
koi8-u(7)
latin10(7)
latin1(7)
latin2(7)
latin3(7)
latin4(7)
latin5(7)
latin6(7)
latin7(7)
latin8(7)
latin9(7)
libc(7)
locale(7)
mailaddr(7)
man(7) 		man-pages(7)
math_error(7)
mdoc(7)
mdoc.samples(7)
mq_overview(7)
netdevice(7)
netlink(7)
numa(7)
operator(7)
packet(7)
path_resolution(7)
pipe(7)
posixoptions(7)
pthreads(7)
pty(7)
raw(7)
regex(7)
rtld-audit(7)
rtnetlink(7)
sem_overview(7)
shm_overview(7)
sigevent(7)
signal(7)
socket(7)
spufs(7)
standards(7)
suffixes(7)
svipc(7)
symlink(7)
tcp(7)
termio(7)
time(7)
tis-620(7)
udp(7)
udplite(7)
unicode(7)
units(7)
unix(7)
uri(7)
url(7)
urn(7)
utf-8(7)
utf8(7)
x25(7)


Linux man-pages: section 8

man-pages section 8

intro(8)
ldconfig(8)
ld-linux(8)
ld-linux.so(8) 		ld.so(8)
nscd(8)
sync(8)
tzselect(8) 		zdump(8)
zic(8)


div(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

DIV(3)                       Linux Programmer's Manual                      DIV(3)

NAME top

       div,  ldiv,  lldiv,  imaxdiv - compute quotient and remainder of an integer
       division

SYNOPSIS top

       #include <stdlib.h>

       div_t div(int numerator, int denominator);
       ldiv_t ldiv(long numerator, long denominator);
       lldiv_t lldiv(long long numerator, long long denominator);

       #include <inttypes.h>

       imaxdiv_t imaxdiv(intmax_t numerator, intmax_t denominator);

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

       lldiv():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The div() function computes the value numerator/denominator and returns the
       quotient and remainder in a structure named div_t that contains two integer
       members (in unspecified order) named quot and rem.  The quotient is rounded
       toward zero.  The result satisfies quot*denominator+rem = numerator.

       The ldiv(), lldiv(), and imaxdiv() functions do the same, dividing numbers
       of the indicated type and returning the result in a structure of the
       indicated name, in all cases with fields quot and rem of the same type as
       the function arguments.

RETURN VALUE top

       The div_t (etc.) structure.

CONFORMING TO top

       SVr4, 4.3BSD, C89. C99.  The functions lldiv() and imaxdiv() were added in
       C99.

EXAMPLE top

       After

               div_t q = div(-5, 3);

       the values q.quot and q.rem are -1 and -2, respectively.

SEE ALSO top

       abs(3), remainder(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-17                              DIV(3)


dlopen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

DLOPEN(3)                    Linux Programmer's Manual                   DLOPEN(3)

NAME top

       dladdr,  dlclose, dlerror, dlopen, dlsym, dlvsym - programming interface to
       dynamic linking loader

SYNOPSIS top

       #include <dlfcn.h>

       void *dlopen(const char *filename, int flag);

       char *dlerror(void);

       void *dlsym(void *handle, const char *symbol);

       int dlclose(void *handle);

       Link with -ldl.

DESCRIPTION top

       The four functions dlopen(), dlsym(), dlclose(), dlerror() implement the
       interface to the dynamic linking loader.

dlerror()

       The function dlerror() returns a human readable string describing the most
       recent error that occurred from dlopen(), dlsym() or dlclose() since the
       last call to dlerror().  It returns NULL if no errors have occurred since
       initialization or since it was last called.

dlopen()

       The function dlopen() loads the dynamic library file named by the null-
       terminated string filename and returns an opaque "handle" for the dynamic
       library.  If filename is NULL, then the returned handle is for the main
       program.  If filename contains a slash ("/"), then it is interpreted as a
       (relative or absolute) pathname.  Otherwise, the dynamic linker searches
       for the library as follows (see ld.so(8) for further details):

       o   (ELF only) If the executable file for the calling program contains a
           DT_RPATH tag, and does not contain a DT_RUNPATH tag, then the
           directories listed in the DT_RPATH tag are searched.

       o   If, at the time that the program was started, the environment variable
           LD_LIBRARY_PATH was defined to contain a colon-separated list of
           directories, then these are searched.  (As a security measure this
           variable is ignored for set-user-ID and set-group-ID programs.)

       o   (ELF only) If the executable file for the calling program contains a
           DT_RUNPATH tag, then the directories listed in that tag are searched.

       o   The cache file /etc/ld.so.cache (maintained by ldconfig(8)) is checked
           to see whether it contains an entry for filename.

       o   The directories /lib and /usr/lib are searched (in that order).

       If the library has dependencies on other shared libraries, then these are
       also automatically loaded by the dynamic linker using the same rules.
       (This process may occur recursively, if those libraries in turn have
       dependencies, and so on.)

       One of the following two values must be included in flag:

       RTLD_LAZY
              Perform lazy binding.  Only resolve symbols as the code that
              references them is executed.  If the symbol is never referenced,
              then it is never resolved.  (Lazy binding is only performed for
              function references; references to variables are always immediately
              bound when the library is loaded.)

       RTLD_NOW
              If this value is specified, or the environment variable LD_BIND_NOW
              is set to a nonempty string, all undefined symbols in the library
              are resolved before dlopen() returns.  If this cannot be done, an
              error is returned.

       Zero or more of the following values may also be ORed in flag:

       RTLD_GLOBAL
              The symbols defined by this library will be made available for
              symbol resolution of subsequently loaded libraries.

       RTLD_LOCAL
              This is the converse of RTLD_GLOBAL, and the default if neither flag
              is specified.  Symbols defined in this library are not made
              available to resolve references in subsequently loaded libraries.

       RTLD_NODELETE (since glibc 2.2)
              Do not unload the library during dlclose().  Consequently, the
              library's static variables are not reinitialized if the library is
              reloaded with dlopen() at a later time.  This flag is not specified
              in POSIX.1-2001.

       RTLD_NOLOAD (since glibc 2.2)
              Don't load the library.  This can be used to test if the library is
              already resident (dlopen() returns NULL if it is not, or the
              library's handle if it is resident).  This flag can also be used to
              promote the flags on a library that is already loaded.  For example,
              a library that was previously loaded with RTLD_LOCAL can be reopened
              with RTLD_NOLOAD | RTLD_GLOBAL.  This flag is not specified in
              POSIX.1-2001.

       RTLD_DEEPBIND (since glibc 2.3.4)
              Place the lookup scope of the symbols in this library ahead of the
              global scope.  This means that a self-contained library will use its
              own symbols in preference to global symbols with the same name
              contained in libraries that have already been loaded.  This flag is
              not specified in POSIX.1-2001.

       If filename is a NULL pointer, then the returned handle is for the main
       program.  When given to dlsym(), this handle causes a search for a symbol
       in the main program, followed by all shared libraries loaded at program
       startup, and then all shared libraries loaded by dlopen() with the flag
       RTLD_GLOBAL.

       External references in the library are resolved using the libraries in that
       library's dependency list and any other libraries previously opened with
       the RTLD_GLOBAL flag.  If the executable was linked with the flag
       "-rdynamic" (or, synonymously, "--export-dynamic"), then the global symbols
       in the executable will also be used to resolve references in a dynamically
       loaded library.

       If the same library is loaded again with dlopen(), the same file handle is
       returned.  The dl library maintains reference counts for library handles,
       so a dynamic library is not deallocated until dlclose() has been called on
       it as many times as dlopen() has succeeded on it.  The _init() routine, if
       present, is only called once.  But a subsequent call with RTLD_NOW may
       force symbol resolution for a library earlier loaded with RTLD_LAZY.

       If dlopen() fails for any reason, it returns NULL.

dlsym()

       The function dlsym() takes a "handle" of a dynamic library returned by
       dlopen() and the null-terminated symbol name, returning the address where
       that symbol is loaded into memory.  If the symbol is not found, in the
       specified library or any of the libraries that were automatically loaded by
       dlopen() when that library was loaded, dlsym() returns NULL.  (The search
       performed by dlsym() is breadth first through the dependency tree of these
       libraries.)  Since the value of the symbol could actually be NULL (so that
       a NULL return from dlsym() need not indicate an error), the correct way to
       test for an error is to call dlerror() to clear any old error conditions,
       then call dlsym(), and then call dlerror() again, saving its return value
       into a variable, and check whether this saved value is not NULL.

       There are two special pseudo-handles, RTLD_DEFAULT and RTLD_NEXT.  The
       former will find the first occurrence of the desired symbol using the
       default library search order.  The latter will find the next occurrence of
       a function in the search order after the current library.  This allows one
       to provide a wrapper around a function in another shared library.

dlclose()

       The function dlclose() decrements the reference count on the dynamic
       library handle handle.  If the reference count drops to zero and no other
       loaded libraries use symbols in it, then the dynamic library is unloaded.

       The function dlclose() returns 0 on success, and nonzero on error.

The obsolete symbols _init() and _fini()

       The linker recognizes special symbols _init and _fini.  If a dynamic
       library exports a routine named _init(), then that code is executed after
       the loading, before dlopen() returns.  If the dynamic library exports a
       routine named _fini(), then that routine is called just before the library
       is unloaded.  In case you need to avoid linking against the system startup
       files, this can be done by using the gcc(1) -nostartfiles command-line
       option.

       Using these routines, or the gcc -nostartfiles or -nostdlib options, is not
       recommended.  Their use may result in undesired behavior, since the
       constructor/destructor routines will not be executed (unless special
       measures are taken).

       Instead, libraries should export routines using the
       __attribute__((constructor)) and __attribute__((destructor)) function
       attributes.  See the gcc info pages for information on these.  Constructor
       routines are executed before dlopen() returns, and destructor routines are
       executed before dlclose() returns.

Glibc extensions: dladdr() and dlvsym()

       Glibc adds two functions not described by POSIX, with prototypes

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <dlfcn.h>

       int dladdr(void *addr, Dl_info *info);

       void *dlvsym(void *handle, char *symbol, char *version);

       The function dladdr() takes a function pointer and tries to resolve name
       and file where it is located.  Information is stored in the Dl_info
       structure:

           typedef struct {
               const char *dli_fname;  /* Pathname of shared object that
                                          contains address */
               void       *dli_fbase;  /* Address at which shared object
                                          is loaded */
               const char *dli_sname;  /* Name of nearest symbol with address
                                          lower than addr */
               void       *dli_saddr;  /* Exact address of symbol named
                                          in dli_sname */
           } Dl_info;

       If no symbol matching addr could be found, then dli_sname and dli_saddr are
       set to NULL.

       dladdr() returns 0 on error, and nonzero on success.

       The function dlvsym(), provided by glibc since version 2.1, does the same
       as dlsym() but takes a version string as an additional argument.

CONFORMING TO top

       POSIX.1-2001 describes dlclose(), dlerror(), dlopen(), and dlsym().

NOTES top

       The symbols RTLD_DEFAULT and RTLD_NEXT are defined by <dlfcn.h> only when
       _GNU_SOURCE was defined before including it.

       Since glibc 2.2.3, atexit(3) can be used to register an exit handler that
       is automatically called when a library is unloaded.

History

       The dlopen interface standard comes from SunOS.  That system also has
       dladdr(), but not dlvsym().

BUGS top

       Sometimes, the function pointers you pass to dladdr() may surprise you.  On
       some architectures (notably i386 and x86_64), dli_fname and dli_fbase may
       end up pointing back at the object from which you called dladdr(), even if
       the function used as an argument should come from a dynamically linked
       library.

       The problem is that the function pointer will still be resolved at compile
       time, but merely point to the plt (Procedure Linkage Table) section of the
       original object (which dispatches the call after asking the dynamic linker
       to resolve the symbol).  To work around this, you can try to compile the
       code to be position-independent: then, the compiler cannot prepare the
       pointer at compile time anymore and today's gcc(1) will generate code that
       just loads the final symbol address from the got (Global Offset Table) at
       run time before passing it to dladdr().

EXAMPLE top

       Load the math library, and print the cosine of 2.0:

       #include <stdio.h>
       #include <stdlib.h>
       #include <dlfcn.h>

       int
       main(int argc, char **argv)
       {
           void *handle;
           double (*cosine)(double);
           char *error;

           handle = dlopen("libm.so", RTLD_LAZY);
           if (!handle) {
               fprintf(stderr, "%s\n", dlerror());
               exit(EXIT_FAILURE);
           }

           dlerror();    /* Clear any existing error */

           /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos");
              would seem more natural, but the C99 standard leaves
              casting from "void *" to a function pointer undefined.
              The assignment used below is the POSIX.1-2003 (Technical
              Corrigendum 1) workaround; see the Rationale for the
              POSIX specification of dlsym(). */

           *(void **) (&cosine) = dlsym(handle, "cos");

           if ((error = dlerror()) != NULL)  {
               fprintf(stderr, "%s\n", error);
               exit(EXIT_FAILURE);
           }

           printf("%f\n", (*cosine)(2.0));
           dlclose(handle);
           exit(EXIT_SUCCESS);
       }

       If this program were in a file named "foo.c", you would build the program
       with the following command:

           gcc -rdynamic -o foo foo.c -ldl

       Libraries exporting _init() and _fini() will want to be compiled as
       follows, using bar.c as the example name:

           gcc -shared -nostartfiles -o bar bar.c

SEE ALSO top

       ld(1), ldd(1), dl_iterate_phdr(3), rtld-audit(7), ld.so(8), ldconfig(8)

       ld.so info pages, gcc info pages, ld info pages

COLOPHON top

       This page is part of release 3.45 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-06                           DLOPEN(3)


dl_iterate_phdr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

DL_ITERATE_PHDR(3)           Linux Programmer's Manual          DL_ITERATE_PHDR(3)

NAME top

       dl_iterate_phdr - walk through list of shared objects

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <link.h>

       int dl_iterate_phdr(
                 int (*callback) (struct dl_phdr_info *info,
                                  size_t size, void *data),
                 void *data);

DESCRIPTION top

       The dl_iterate_phdr() function allows an application to inquire at run time
       to find out which shared objects it has loaded.

       The dl_iterate_phdr() function walks through the list of an application's
       shared objects and calls the function callback once for each object, until
       either all shared objects have been processed or callback returns a nonzero
       value.

       Each call to callback receives three arguments: info, which is a pointer to
       a structure containing information about the shared object; size, which is
       the size of the structure pointed to by info; and data, which is a copy of
       whatever value was passed by the calling program as the second argument
       (also named data) in the call to dl_iterate_phdr().

       The info argument is a structure of the following type:

           struct dl_phdr_info {
               ElfW(Addr)        dlpi_addr;  /* Base address of object */
               const char       *dlpi_name;  /* (Null-terminated) name of
                                                object */
               const ElfW(Phdr) *dlpi_phdr;  /* Pointer to array of
                                                ELF program headers
                                                for this object */
               ElfW(Half)        dlpi_phnum; /* # of items in dlpi_phdr */
           };

       (The ElfW() macro definition turns its argument into the name of an ELF
       data type suitable for the hardware architecture.  For example, on a 32-bit
       platform, ElfW(Addr) yields the data type name Elf32_Addr.  Further
       information on these types can be found in the <elf.h> and <link.h> header
       files.)

       The dlpi_addr field indicates the base address of the shared object (i.e.,
       the difference between the virtual memory address of the shared object and
       the offset of that object in the file from which it was loaded).  The
       dlpi_name field is a null-terminated string giving the pathname from which
       the shared object was loaded.

       To understand the meaning of the dlpi_phdr and dlpi_phnum fields, we need
       to be aware that an ELF shared object consists of a number of segments,
       each of which has a corresponding program header describing the segment.
       The dlpi_phdr field is a pointer to an array of the program headers for
       this shared object.  The dlpi_phnum field indicates the size of this array.

       These program headers are structures of the following form:

           typedef struct {
               Elf32_Word  p_type;    /* Segment type */
               Elf32_Off   p_offset;  /* Segment file offset */
               Elf32_Addr  p_vaddr;   /* Segment virtual address */
               Elf32_Addr  p_paddr;   /* Segment physical address */
               Elf32_Word  p_filesz;  /* Segment size in file */
               Elf32_Word  p_memsz;   /* Segment size in memory */
               Elf32_Word  p_flags;   /* Segment flags */
               Elf32_Word  p_align;   /* Segment alignment */
           } Elf32_Phdr;

       Note that we can calculate the location of a particular program header, x,
       in virtual memory using the formula:

         addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr;

RETURN VALUE top

       The dl_iterate_phdr() function returns whatever value was returned by the
       last call to callback.

VERSIONS top

       dl_iterate_phdr() has been supported in glibc since version 2.2.4.

CONFORMING TO top

       The dl_iterate_phdr() function is Linux-specific and should be avoided in
       portable applications.

EXAMPLE top

       The following program displays a list of pathnames of the shared objects it
       has loaded.  For each shared object, the program lists the virtual
       addresses at which the object's ELF segments are loaded.

       #define _GNU_SOURCE
       #include <link.h>
       #include <stdlib.h>
       #include <stdio.h>

       static int
       callback(struct dl_phdr_info *info, size_t size, void *data)
       {
           int j;

           printf("name=%s (%d segments)\n", info->dlpi_name,
               info->dlpi_phnum);

           for (j = 0; j < info->dlpi_phnum; j++)
                printf("\t\t header %2d: address=%10p\n", j,
                    (void *) (info->dlpi_addr + info->dlpi_phdr[j].p_vaddr));
           return 0;
       }

       int
       main(int argc, char *argv[])
       {
           dl_iterate_phdr(callback, NULL);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       ldd(1), objdump(1), readelf(1), dlopen(3), elf(5), ld.so(8)

       Executable and Linking Format Specification, available at various locations
       online.

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-05-18                  DL_ITERATE_PHDR(3)


resolver(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

RESOLVER(3)                  Linux Programmer's Manual                 RESOLVER(3)

NAME top

       res_init,  res_query,  res_search,  res_querydomain, res_mkquery, res_send,
       dn_comp, dn_expand - resolver routines

SYNOPSIS top

       #include <netinet/in.h>
       #include <arpa/nameser.h>
       #include <resolv.h>
       extern struct state _res;

       int res_init(void);

       int res_query(const char *dname, int class, int type,
              unsigned char *answer, int anslen);

       int res_search(const char *dname, int class, int type,
              unsigned char *answer, int anslen);

       int res_querydomain(const char *name, const char *domain,
              int class, int type, unsigned char *answer,
              int anslen);

       int res_mkquery(int op, const char *dname, int class,
              int type, char *data, int datalen, struct rrec *newrr,
              char *buf, int buflen);

       int res_send(const char *msg, int msglen, char *answer,
              int anslen);

       int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
              int length, unsigned char **dnptrs, unsigned char **lastdnptr);

       int dn_expand(unsigned char *msg, unsigned char *eomorig,
              unsigned char *comp_dn, char *exp_dn,
              int length);

       Link with -lresolv.

DESCRIPTION top

       These functions make queries to and interpret the responses from Internet
       domain name servers.

       The res_init() function reads the configuration files (see resolv.conf(5))
       to get the default domain name, search order and name server address(es).
       If no server is given, the local host is tried.  If no domain is given,
       that associated with the local host is used.  It can be overridden with the
       environment variable LOCALDOMAIN.  res_init() is normally executed by the
       first call to one of the other functions.

       The res_query() function queries the name server for the fully qualified
       domain name name of specified type and class.  The reply is left in the
       buffer answer of length anslen supplied by the caller.

       The res_search() function makes a query and waits for the response like
       res_query(), but in addition implements the default and search rules
       controlled by RES_DEFNAMES and RES_DNSRCH (see description of _res options
       below).

       The res_querydomain() function makes a query using res_query() on the
       concatenation of name and domain.

       The following functions are lower-level routines used by res_query().

       The res_mkquery() function constructs a query message in buf of length
       buflen for the domain name dname.  The query type op is usually QUERY, but
       can be any of the types defined in <arpa/nameser.h>.  newrr is currently
       unused.

       The res_send() function sends a preformatted query given in msg of length
       msglen and returns the answer in answer which is of length anslen.  It will
       call res_init(), if it has not already been called.

       The dn_comp() function compresses the domain name exp_dn and stores it in
       the buffer comp_dn of length length.  The compression uses an array of
       pointers dnptrs to previously compressed names in the current message.  The
       first pointer points to the beginning of the message and the list ends with
       NULL.  The limit of the array is specified by lastdnptr.  If dnptr is NULL,
       domain names are not compressed.  If lastdnptr is NULL, the list of labels
       is not updated.

       The dn_expand() function expands the compressed domain name comp_dn to a
       full domain name, which is placed in the buffer exp_dn of size length.  The
       compressed name is contained in a query or reply message, and msg points to
       the beginning of the message.

       The resolver routines use global configuration and state information
       contained in the structure _res, which is defined in <resolv.h>.  The only
       field that is normally manipulated by the user is _res.options.  This field
       can contain the bitwise "OR" of the following options:

       RES_INIT
              True if res_init() has been called.

       RES_DEBUG
              Print debugging messages.

       RES_AAONLY
              Accept authoritative answers only.  res_send() continues until it
              finds an authoritative answer or returns an error.  [Not currently
              implemented].

       RES_USEVC
              Use TCP connections for queries rather than UDP datagrams.

       RES_PRIMARY
              Query primary domain name server only.

       RES_IGNTC
              Ignore truncation errors.  Don't retry with TCP.  [Not currently
              implemented].

       RES_RECURSE
              Set the recursion desired bit in queries.  Recursion is carried out
              by the domain name server, not by res_send().  [Enabled by default].

       RES_DEFNAMES
              If set, res_search() will append the default domain name to single
              component names, i.e., those that do not contain a dot.  [Enabled by
              default].

       RES_STAYOPEN
              Used with RES_USEVC to keep the TCP connection open between queries.

       RES_DNSRCH
              If set, res_search() will search for hostnames in the current domain
              and in parent domains.  This option is used by gethostbyname(3).
              [Enabled by default].

       This list is not complete.  You can find some other flags described in
       resolv.conf(5).

RETURN VALUE top

       The res_init() function returns 0 on success, or -1 if an error occurs.

       The res_query(), res_search(), res_querydomain(), res_mkquery() and
       res_send() functions return the length of the response, or -1 if an error
       occurs.

       The dn_comp() and dn_expand() functions return the length of the compressed
       name, or -1 if an error occurs.

FILES top

       /etc/resolv.conf          resolver configuration file
       /etc/host.conf            resolver configuration file

CONFORMING TO top

       4.3BSD.

SEE ALSO top

       gethostbyname(3), resolv.conf(5), resolver(5), hostname(7), named(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-23                         RESOLVER(3)


dprintf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

DPRINTF(3)                   Linux Programmer's Manual                  DPRINTF(3)

NAME top

       dprintf, vdprintf - print to a file descriptor

SYNOPSIS top

       #include <stdio.h>

       int dprintf(int fd, const char *format, ...);

       int vdprintf(int fd, const char *format, va_list ap);

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

       dprintf(), vdprintf():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The functions dprintf() and vdprintf() (as found in the glibc2 library) are
       exact analogs of fprintf(3) and vfprintf(3), except that they output to a
       file descriptor fd instead of to a stdio stream.

CONFORMING TO top

       These functions are GNU extensions that are nowadays specified in
       POSIX.1-2008.

SEE ALSO top

       printf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-15                          DPRINTF(3)


drand48(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DRAND48(3)                   Linux Programmer's Manual                  DRAND48(3)

NAME top

       drand48,  erand48,  lrand48,  nrand48,  mrand48,  jrand48, srand48, seed48,
       lcong48 - generate uniformly distributed pseudo-random numbers

SYNOPSIS top

       #include <stdlib.h>

       double drand48(void);

       double erand48(unsigned short xsubi[3]);

       long int lrand48(void);

       long int nrand48(unsigned short xsubi[3]);

       long int mrand48(void);

       long int jrand48(unsigned short xsubi[3]);

       void srand48(long int seedval);

       unsigned short *seed48(unsigned short seed16v[3]);

       void lcong48(unsigned short param[7]);

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

       All functions shown above: _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       These functions generate pseudo-random numbers using the linear
       congruential algorithm and 48-bit integer arithmetic.

       The drand48() and erand48() functions return nonnegative double-precision
       floating-point values uniformly distributed between [0.0, 1.0).

       The lrand48() and nrand48() functions return nonnegative long integers
       uniformly distributed between 0 and 2^31.

       The mrand48() and jrand48() functions return signed long integers uniformly
       distributed between -2^31 and 2^31.

       The srand48(), seed48() and lcong48() functions are initialization
       functions, one of which should be called before using drand48(), lrand48()
       or mrand48().  The functions erand48(), nrand48() and jrand48() do not
       require an initialization function to be called first.

       All the functions work by generating a sequence of 48-bit integers, Xi,
       according to the linear congruential formula:

              Xn+1 = (aXn + c) mod m, where n >= 0

       The parameter m = 2^48, hence 48-bit integer arithmetic is performed.
       Unless lcong48() is called, a and c are given by:

              a = 0x5DEECE66D
              c = 0xB

       The value returned by any of the functions drand48(), erand48(), lrand48(),
       nrand48(), mrand48() or jrand48() is computed by first generating the next
       48-bit Xi in the sequence.  Then the appropriate number of bits, according
       to the type of data item to be returned, is copied from the high-order bits
       of Xi and transformed into the returned value.

       The functions drand48(), lrand48() and mrand48() store the last 48-bit Xi
       generated in an internal buffer.  The functions erand48(), nrand48() and
       jrand48() require the calling program to provide storage for the successive
       Xi values in the array argument xsubi.  The functions are initialized by
       placing the initial value of Xi into the array before calling the function
       for the first time.

       The initializer function srand48() sets the high order 32-bits of Xi to the
       argument seedval.  The low order 16-bits are set to the arbitrary value
       0x330E.

       The initializer function seed48() sets the value of Xi to the 48-bit value
       specified in the array argument seed16v.  The previous value of Xi is
       copied into an internal buffer and a pointer to this buffer is returned by
       seed48().

       The initialization function lcong48() allows the user to specify initial
       values for Xi, a and c.  Array argument elements param[0-2] specify Xi,
       param[3-5] specify a, and param[6] specifies c.  After lcong48() has been
       called, a subsequent call to either srand48() or seed48() will restore the
       standard values of a and c.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       These functions are declared obsolete by SVID 3, which states that rand(3)
       should be used instead.

SEE ALSO top

       rand(3), random(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-07-26                          DRAND48(3)


drand48_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

DRAND48_R(3)                 Linux Programmer's Manual                DRAND48_R(3)

NAME top

       drand48_r,   erand48_r,   lrand48_r,   nrand48_r,   mrand48_r,   jrand48_r,
       srand48_r, seed48_r, lcong48_r - generate uniformly distributed pseudo-ran-
       dom numbers reentrantly

SYNOPSIS top

       #include <stdlib.h>

       int drand48_r(struct drand48_data *buffer, double *result);

       int erand48_r(unsigned short xsubi[3][22m,[0m
                     struct drand48_data *buffer, double *result);

       int lrand48_r(struct drand48_data *buffer, long int *result);

       int nrand48_r(unsigned short int xsubi[3],
                     struct drand48_data *buffer, long int *result);

       int mrand48_r(struct drand48_data *buffer,long int *result);

       int jrand48_r(unsigned short int xsubi[3],
                     struct drand48_data *buffer, long int *result);

       int srand48_r(long int seedval, struct drand48_data *buffer);

       int seed48_r(unsigned short int seed16v[3],
                    struct drand48_data *buffer);

       int lcong48_r(unsigned short int param[7],
                     struct drand48_data *buffer);

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

       All functions shown above: _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       These functions are the reentrant analogs of the functions described in
       drand48(3).  Instead of modifying the global random generator state, they
       use the supplied data buffer.

       Before the first use, this struct must be initialized, for example, by
       filling it with zeros, or by calling one of the functions srand48_r(),
       seed48_r(), or lcong48_r().

RETURN VALUE top

       The return value is 0.

CONFORMING TO top

       These functions are GNU extensions and are not portable.

SEE ALSO top

       drand48(3), rand(3), random(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                        DRAND48_R(3)


remainder(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

REMAINDER(3)                 Linux Programmer's Manual                REMAINDER(3)

NAME top

       drem,  dremf,  dreml,  remainder,  remainderf,  remainderl - floating-point
       remainder function

SYNOPSIS top

       #include <math.h>

       /* The C99 versions */
       double remainder(double x, double y);
       float remainderf(float x, float y);
       long double remainderl(long double x, long double y);

       /* Obsolete synonyms */
       double drem(double x, double y);
       float dremf(float x, float y);
       long double dreml(long double x, long double y);

       Link with -lm.

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

       remainder():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       remainderf(), remainderl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       drem(), dremf(), dreml():
           _SVID_SOURCE || _BSD_SOURCE

DESCRIPTION top

       The remainder() function computes the remainder of dividing x by y.  The
       return value is x-n*y, where n is the value x / y, rounded to the nearest
       integer.  If the absolute value of x-n*y is 0.5, n is chosen to be even.

       These functions are unaffected by the current rounding mode (see fenv(3)).

       The drem() function does precisely the same thing.

RETURN VALUE top

       On success, these functions return the floating-point remainder, x-n*y.  If
       the return value is 0, it has the sign of x.

       If x or y is a NaN, a NaN is returned.

       If x is an infinity, and y is not a NaN, a domain error occurs, and a NaN
       is returned.

       If y is zero, and x is not a NaN, a domain error occurs, and a NaN is
       returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity and y is not a NaN
              An invalid floating-point exception (FE_INVALID) is raised.

              These functions do not set errno for this case.

       Domain error: y is zero
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

CONFORMING TO top

       The functions remainder(), remainderf(), and remainderl() are specified in
       C99 and POSIX.1-2001.

       The function drem() is from 4.3BSD.  The float and long double variants
       dremf() and dreml() exist on some systems, such as Tru64 and glibc2.  Avoid
       the use of these functions in favor of remainder() etc.

BUGS top

       The call

           remainder(nan(""), 0);

       returns a NaN, as expected, but wrongly causes a domain error; it should
       yield a silent NaN.

EXAMPLE top

       The call "remainder(29.0, 3.0)" returns -1.

SEE ALSO top

       div(3), fmod(3), remquo(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                        REMAINDER(3)


dsp56k(4) - Linux manual page

NAME | SYNOPSIS | CONFIGURATION | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

DSP56K(4)                    Linux Programmer's Manual                   DSP56K(4)

NAME top

       dsp56k - DSP56001 interface device

SYNOPSIS top

       #include <asm/dsp56k.h>

       ssize_t read(int fd, void *data, size_t length);
       ssize_t write(int fd, void *data, size_t length);

       int ioctl(int fd, DSP56K_UPLOAD, struct dsp56k_upload *program);
       int ioctl(int fd, DSP56K_SET_TX_WSIZE, int wsize);
       int ioctl(int fd, DSP56K_SET_RX_WSIZE, int wsize);
       int ioctl(int fd, DSP56K_HOST_FLAGS, struct dsp56k_host_flags *flags);
       int ioctl(int fd, DSP56K_HOST_CMD, int cmd);

CONFIGURATION top

       The dsp56k device is a character device with major number 55 and minor num-
       ber 0.

DESCRIPTION top

       The Motorola DSP56001 is a fully programmable 24-bit digital signal
       processor found in Atari Falcon030-compatible computers.  The dsp56k
       special file is used to control the DSP56001, and to send and receive data
       using the bidirectional handshaked host port.

       To send a data stream to the signal processor, use write(2) to the device,
       and read(2) to receive processed data.  The data can be sent or received in
       8, 16, 24, or 32-bit quantities on the host side, but will always be seen
       as 24-bit quantities in the DSP56001.

       The following ioctl(2) calls are used to control the dsp56k device:

       DSP56K_UPLOAD
              resets the DSP56001 and uploads a program.  The third ioctl(2)
              argument must be a pointer to a struct dsp56k_binary with members
              bin pointing to a DSP56001 binary program, and len set to the length
              of the program, counted in 24-bit words.

       DSP56K_SET_TX_WSIZE
              sets the transmit word size.  Allowed values are in the range 1 to
              4, and is the number of bytes that will be sent at a time to the
              DSP56001.  These data quantities will either be padded with zero
              bytes, or truncated to fit the native 24-bit data format of the
              DSP56001.

       DSP56K_SET_RX_WSIZE
              sets the receive word size.  Allowed values are in the range 1 to 4,
              and is the number of bytes that will be received at a time from the
              DSP56001.  These data quantities will either truncated, or padded
              with a null byte ('\0') to fit the native 24-bit data format of the
              DSP56001.

       DSP56K_HOST_FLAGS
              read and write the host flags.  The host flags are four general-
              purpose bits that can be read by both the hosting computer and the
              DSP56001.  Bits 0 and 1 can be written by the host, and bits 2 and 3
              can be written by the DSP56001.

              To access the host flags, the third ioctl(2) argument must be a
              pointer to a struct dsp56k_host_flags.  If bit 0 or 1 is set in the
              dir member, the corresponding bit in out will be written to the host
              flags.  The state of all host flags will be returned in the lower
              four bits of the status member.

       DSP56K_HOST_CMD
              sends a host command.  Allowed values are in the range 0 to 31, and
              is a user-defined command handled by the program running in the
              DSP56001.

FILES top

       /dev/dsp56k

SEE ALSO top

       linux/include/asm-m68k/dsp56k.h, linux/drivers/char/dsp56k.c,
       <http://dsp56k.nocrew.org/>, DSP56000/DSP56001 Digital Signal Processor
       User's Manual

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                           DSP56K(4)


dup(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DUP(2)                       Linux Programmer's Manual                      DUP(2)

NAME top

       dup, dup2, dup3 - duplicate a file descriptor

SYNOPSIS top

       #include <unistd.h>

       int dup(int oldfd);
       int dup2(int oldfd, int newfd);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <fcntl.h>              /* Obtain O_* constant definitions */
       #include <unistd.h>

       int dup3(int oldfd, int newfd, int flags);

DESCRIPTION top

       These system calls create a copy of the file descriptor oldfd.

       dup() uses the lowest-numbered unused descriptor for the new descriptor.

       dup2() makes newfd be the copy of oldfd, closing newfd first if necessary,
       but note the following:

       *  If oldfd is not a valid file descriptor, then the call fails, and newfd
          is not closed.

       *  If oldfd is a valid file descriptor, and newfd has the same value as
          oldfd, then dup2() does nothing, and returns newfd.

       After a successful return from one of these system calls, the old and new
       file descriptors may be used interchangeably.  They refer to the same open
       file description (see open(2)) and thus share file offset and file status
       flags; for example, if the file offset is modified by using lseek(2) on one
       of the descriptors, the offset is also changed for the other.

       The two descriptors do not share file descriptor flags (the close-on-exec
       flag).  The close-on-exec flag (FD_CLOEXEC; see fcntl(2)) for the duplicate
       descriptor is off.

       dup3() is the same as dup2(), except that:

       *  The caller can force the close-on-exec flag to be set for the new file
          descriptor by specifying O_CLOEXEC in flags.  See the description of the
          same flag in open(2) for reasons why this may be useful.

       *  If oldfd equals newfd, then dup3() fails with the error EINVAL.

RETURN VALUE top

       On success, these system calls return the new descriptor.  On error, -1 is
       returned, and errno is set appropriately.

ERRORS top

       EBADF  oldfd isn't an open file descriptor, or newfd is out of the allowed
              range for file descriptors.

       EBUSY  (Linux only) This may be returned by dup2() or dup3() during a race
              condition with open(2) and dup().

       EINTR  The dup2() or dup3() call was interrupted by a signal; see
              signal(7).

       EINVAL (dup3()) flags contain an invalid value.  Or, oldfd was equal to
              newfd.

       EMFILE The process already has the maximum number of file descriptors open
              and tried to open a new one.

VERSIONS top

       dup3() was added to Linux in version 2.6.27; glibc support is available
       starting with version 2.9.

CONFORMING TO top

       dup(), dup2(): SVr4, 4.3BSD, POSIX.1-2001.

       dup3() is Linux-specific.

NOTES top

       The error returned by dup2() is different from that returned by fcntl(...,
       F_DUPFD, ...)  when newfd is out of range.  On some systems dup2() also
       sometimes returns EINVAL like F_DUPFD.

       If newfd was open, any errors that would have been reported at close(2)
       time are lost.  A careful programmer will not use dup2() or dup3() without
       closing newfd first.

SEE ALSO top

       close(2), fcntl(2), open(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-02-14                              DUP(2)


dysize(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

DYSIZE(3)                    Linux Programmer's Manual                   DYSIZE(3)

NAME top

       dysize - get number of days for a given year

SYNOPSIS top

       #include <time.h>

       int dysize(int year);

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

       dysize(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The function returns 365 for a normal year and 366 for a leap year.  The
       calculation for leap year is based on:

       (year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0)

       The formula is defined in the macro __isleap(year) also found in <time.h>.

CONFORMING TO top

       This function occurs in SunOS 4.x.

NOTES top

       This is a compatibility function only.  Don't use it in new programs.

SEE ALSO top

       strftime(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-22                           DYSIZE(3)


euidaccess(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

EUIDACCESS(3)                Linux Programmer's Manual               EUIDACCESS(3)

NAME top

       euidaccess, eaccess - check effective user's permissions for a file

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <unistd.h>

       int euidaccess(const char *pathname, int mode);
       int eaccess(const char *pathname, int mode);

DESCRIPTION top

       Like access(2), euidaccess() checks permissions and existence of the file
       identified by its argument pathname.  However, whereas access(2), performs
       checks using the real user and group identifiers of the process,
       euidaccess() uses the effective identifiers.

       mode is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK, with
       the same meanings as for access(2).

       eaccess() is a synonym for euidaccess(), provided for compatibility with
       some other systems.

RETURN VALUE top

       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 top

       As for access(2).

VERSIONS top

       The eaccess() function was added to glibc in version 2.4.

CONFORMING TO top

       These functions are nonstandard.  Some other systems have an eaccess()
       function.

NOTES top

       Warning: Using this function to check a process's permissions on a file
       before performing some operation based on that information leads to race
       conditions: the file permissions may change between the two steps.
       Generally, it is safer just to attempt the desired operation and handle any
       permission error that occurs.

       This function always dereferences symbolic links.  If you need to check the
       permissions on a symbolic link, use faccessat(2) with the flags AT_EACCESS
       and AT_SYMLINK_NOFOLLOW.

SEE ALSO top

       access(2), chmod(2), chown(2), faccessat(2), open(2), setgid(2), setuid(2),
       stat(2), credentials(7), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-11-01                       EUIDACCESS(3)


ecvt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ECVT(3)                      Linux Programmer's Manual                     ECVT(3)

NAME top

       ecvt, fcvt - convert a floating-point number to a string

SYNOPSIS top

       #include <stdlib.h>

       char *ecvt(double number, int ndigits, int *decpt, int *sign);

       char *fcvt(double number, int ndigits, int *decpt, int *sign);

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

       ecvt(), fcvt():
           Since glibc 2.12:
               _SVID_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The ecvt() function converts number to a null-terminated string of ndigits
       digits (where ndigits is reduced to a system-specific limit determined by
       the precision of a double), and returns a pointer to the string.  The high-
       order digit is nonzero, unless number is zero.  The low order digit is
       rounded.  The string itself does not contain a decimal point; however, the
       position of the decimal point relative to the start of the string is stored
       in *decpt.  A negative value for *decpt means that the decimal point is to
       the left of the start of the string.  If the sign of number is negative,
       *sign is set to a nonzero value, otherwise it is set to 0.  If number is
       zero, it is unspecified whether *decpt is 0 or 1.

       The fcvt() function is identical to ecvt(), except that ndigits specifies
       the number of digits after the decimal point.

RETURN VALUE top

       Both the ecvt() and fcvt() functions return a pointer to a static string
       containing the ASCII representation of number.  The static string is
       overwritten by each call to ecvt() or fcvt().

CONFORMING TO top

       SVr2; marked as LEGACY in POSIX.1-2001.  POSIX.1-2008 removes the
       specifications of ecvt() and fcvt(), recommending the use of sprintf(3)
       instead (though snprintf(3) may be preferable).

NOTES top

       Linux libc4 and libc5 specified the type of ndigits as size_t.  Not all
       locales use a point as the radix character ("decimal point").

SEE ALSO top

       ecvt_r(3), gcvt(3), qecvt(3), setlocale(3), sprintf(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             ECVT(3)


ecvt_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ECVT_R(3)                    Linux Programmer's Manual                   ECVT_R(3)

NAME top

       ecvt_r,  fcvt_r,  qecvt_r,  qfcvt_r  - convert a floating-point number to a
       string

SYNOPSIS top

       #include <stdlib.h>

       int ecvt_r(double number, int ndigits, int *decpt,
                  int *sign, char *buf, size_t len);

       int fcvt_r(double number, int ndigits, int *decpt,
                  int *sign, char *buf, size_t len);

       int qecvt_r(long double number, int ndigits, int *decpt,
                  int *sign, char *buf, size_t len);

       int qfcvt_r(long double number, int ndigits, int *decpt,
                  int *sign, char *buf, size_t len);

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

       ecvt_r(), fcvt_r(), qecvt_r(), qfcvt_r():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 500

DESCRIPTION top

       The functions ecvt_r(), fcvt_r(), qecvt_r() and qfcvt_r() are identical to
       ecvt(3), fcvt(3), qecvt(3) and qfcvt(3), respectively, except that they do
       not return their result in a static buffer, but instead use the supplied
       buf of size len.  See ecvt(3) and qecvt(3).

RETURN VALUE top

       These functions return 0 on success, and -1 otherwise.

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       These functions are obsolete.  Instead, sprintf(3) is recommended.

SEE ALSO top

       ecvt(3), qecvt(3), sprintf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                           ECVT_R(3)


end(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

END(3)                       Linux Programmer's Manual                      END(3)

NAME top

       etext, edata, end - end of program segments

SYNOPSIS top

       extern etext;
       extern edata;
       extern end;

DESCRIPTION top

       The addresses of these symbols indicate the end of various program
       segments:

       etext  This is the first address past the end of the text segment (the
              program code).

       edata  This is the first address past the end of the initialized data
              segment.

       end    This is the first address past the end of the uninitialized data
              segment (also known as the BSS segment).

CONFORMING TO top

       Although these symbols have long been provided on most UNIX systems, they
       are not standardized; use with caution.

NOTES top

       The program must explicitly declare these symbols; they are not defined in
       any header file.

       On some systems the names of these symbols are preceded by underscores,
       thus: _etext, _edata, and _end.  These symbols are also defined for
       programs compiled on Linux.

       At the start of program execution, the program break will be somewhere near
       &end (perhaps at the start of the following page).  However, the break will
       change as memory is allocated via brk(2) or malloc(3).  Use sbrk(2) with an
       argument of zero to find the current value of the program break.

EXAMPLE top

       When run, the program below produces output such as the following:

           $ ./a.out
           First address past:
               program text (etext)       0x8048568
               initialized data (edata)   0x804a01c
               uninitialized data (end)   0x804a024

Program source

       #include <stdio.h>
       #include <stdlib.h>

       extern char etext, edata, end; /* The symbols must have some type,
                                          or "gcc -Wall" complains */

       int
       main(int argc, char *argv[])
       {
           printf("First address past:\n");
           printf("    program text (etext)      %10p\n", &etext);
           printf("    initialized data (edata)  %10p\n", &edata);
           printf("    uninitialized data (end)  %10p\n", &end);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       objdump(1), readelf(1), sbrk(2), elf(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-07-17                              END(3)


elf(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ELF(5)                       Linux Programmer's Manual                      ELF(5)

NAME top

       elf - format of Executable and Linking Format (ELF) files

SYNOPSIS top

       #include <elf.h>

DESCRIPTION top

       The header file <elf.h> defines the format of ELF executable binary files.
       Amongst these files are normal executable files, relocatable object files,
       core files and shared libraries.

       An executable file using the ELF file format consists of an ELF header,
       followed by a program header table or a section header table, or both.  The
       ELF header is always at offset zero of the file.  The program header table
       and the section header table's offset in the file are defined in the ELF
       header.  The two tables describe the rest of the particularities of the
       file.

       This header file describes the above mentioned headers as C structures and
       also includes structures for dynamic sections, relocation sections and
       symbol tables.

       The following types are used for N-bit architectures (N=32,64, ElfN stands
       for Elf32 or Elf64, uintN_t stands for uint32_t or uint64_t):

           ElfN_Addr       Unsigned program address, uintN_t
           ElfN_Off        Unsigned file offset, uintN_t
           ElfN_Section    Unsigned section index, uint16_t
           ElfN_Versym     Unsigned version symbol information, uint16_t
           Elf_Byte        unsigned char
           ElfN_Half       uint16_t
           ElfN_Sword      int32_t
           ElfN_Word       uint32_t
           ElfN_Sxword     int64_t
           ElfN_Xword      uint64_t

       (Note: The *BSD terminology is a bit different.  There Elf64_Half is twice
       as large as Elf32_Half, and Elf64Quarter is used for uint16_t.  In order to
       avoid confusion these types are replaced by explicit ones in the below.)

       All data structures that the file format defines follow the "natural" size
       and alignment guidelines for the relevant class.  If necessary, data
       structures contain explicit padding to ensure 4-byte alignment for 4-byte
       objects, to force structure sizes to a multiple of 4, etc.

       The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr:

           #define EI_NIDENT 16

           typedef struct {
               unsigned char e_ident[EI_NIDENT];
               uint16_t      e_type;
               uint16_t      e_machine;
               uint32_t      e_version;
               ElfN_Addr     e_entry;
               ElfN_Off      e_phoff;
               ElfN_Off      e_shoff;
               uint32_t      e_flags;
               uint16_t      e_ehsize;
               uint16_t      e_phentsize;
               uint16_t      e_phnum;
               uint16_t      e_shentsize;
               uint16_t      e_shnum;
               uint16_t      e_shstrndx;
           } ElfN_Ehdr;

       The fields have the following meanings:

       e_ident     This array of bytes specifies to interpret the file,
                   independent of the processor or the file's remaining contents.
                   Within this array everything is named by macros, which start
                   with the prefix EI_ and may contain values which start with the
                   prefix ELF.  The following macros are defined:

                   EI_MAG0     The first byte of the magic number.  It must be
                               filled with ELFMAG0.  (0: 0x7f)

                   EI_MAG1     The second byte of the magic number.  It must be
                               filled with ELFMAG1.  (1: 'E')

                   EI_MAG2     The third byte of the magic number.  It must be
                               filled with ELFMAG2.  (2: 'L')

                   EI_MAG3     The fourth byte of the magic number.  It must be
                               filled with ELFMAG3.  (3: 'F')

                   EI_CLASS    The fifth byte identifies the architecture for this
                               binary:

                               ELFCLASSNONE  This class is invalid.
                               ELFCLASS32    This defines the 32-bit architecture.
                                             It supports machines with files and
                                             virtual address spaces up to 4
                                             Gigabytes.
                               ELFCLASS64    This defines the 64-bit architecture.

                   EI_DATA     The sixth byte specifies the data encoding of the
                               processor-specific data in the file.  Currently
                               these encodings are supported:

                               ELFDATANONE   Unknown data format.
                               ELFDATA2LSB   Two's complement, little-endian.
                               ELFDATA2MSB   Two's complement, big-endian.

                   EI_VERSION  The version number of the ELF specification:
                               EV_NONE       Invalid version.
                               EV_CURRENT    Current version.

                   EI_OSABI    This byte identifies the operating system and ABI
                               to which the object is targeted.  Some fields in
                               other ELF structures have flags and values that
                               have platform-specific meanings; the interpretation
                               of those fields is determined by the value of this
                               byte.  E.g.:

                               ELFOSABI_NONE       Same as ELFOSABI_SYSV
                               ELFOSABI_SYSV       UNIX System V ABI.
                               ELFOSABI_HPUX       HP-UX ABI.
                               ELFOSABI_NETBSD     NetBSD ABI.
                               ELFOSABI_LINUX      Linux ABI.
                               ELFOSABI_SOLARIS    Solaris ABI.
                               ELFOSABI_IRIX       IRIX ABI.
                               ELFOSABI_FREEBSD    FreeBSD ABI.
                               ELFOSABI_TRU64      TRU64 UNIX ABI.
                               ELFOSABI_ARM        ARM architecture ABI.
                               ELFOSABI_STANDALONE Stand-alone (embedded) ABI.

                   EI_ABIVERSION
                               This byte identifies the version of the ABI to
                               which the object is targeted.  This field is used
                               to distinguish among incompatible versions of an
                               ABI.  The interpretation of this version number is
                               dependent on the ABI identified by the EI_OSABI
                               field.  Applications conforming to this
                               specification use the value 0.

                   EI_PAD      Start of padding.  These bytes are reserved and set
                               to zero.  Programs which read them should ignore
                               them.  The value for EI_PAD will change in the
                               future if currently unused bytes are given
                               meanings.

                   EI_NIDENT   The size of the e_ident array.

       e_type      This member of the structure identifies the object file type:

                   ET_NONE     An unknown type.
                   ET_REL      A relocatable file.
                   ET_EXEC     An executable file.
                   ET_DYN      A shared object.
                   ET_CORE     A core file.

       e_machine   This member specifies the required architecture for an
                   individual file.  E.g.:

                   EM_NONE     An unknown machine.
                   EM_M32      AT&T WE 32100.
                   EM_SPARC    Sun Microsystems SPARC.
                   EM_386      Intel 80386.
                   EM_68K      Motorola 68000.
                   EM_88K      Motorola 88000.
                   EM_860      Intel 80860.
                   EM_MIPS     MIPS RS3000 (big-endian only).
                   EM_PARISC   HP/PA.
                   EM_SPARC32PLUS
                               SPARC with enhanced instruction set.
                   EM_PPC      PowerPC.
                   EM_PPC64    PowerPC 64-bit.
                   EM_S390     IBM S/390
                   EM_ARM      Advanced RISC Machines
                   EM_SH       Renesas SuperH
                   EM_SPARCV9  SPARC v9 64-bit.
                   EM_IA_64    Intel Itanium
                   EM_X86_64   AMD x86-64
                   EM_VAX      DEC Vax.

       e_version   This member identifies the file version:

                   EV_NONE     Invalid version.
                   EV_CURRENT  Current version.

       e_entry     This member gives the virtual address to which the system first
                   transfers control, thus starting the process.  If the file has
                   no associated entry point, this member holds zero.

       e_phoff     This member holds the program header table's file offset in
                   bytes.  If the file has no program header table, this member
                   holds zero.

       e_shoff     This member holds the section header table's file offset in
                   bytes.  If the file has no section header table this member
                   holds zero.

       e_flags     This member holds processor-specific flags associated with the
                   file.  Flag names take the form EF_`machine_flag'.  Currently
                   no flags have been defined.

       e_ehsize    This member holds the ELF header's size in bytes.

       e_phentsize This member holds the size in bytes of one entry in the file's
                   program header table; all entries are the same size.

       e_phnum     This member holds the number of entries in the program header
                   table.  Thus the product of e_phentsize and e_phnum gives the
                   table's size in bytes.  If a file has no program header,
                   e_phnum holds the value zero.

                   If the number of entries in the program header table is larger
                   than or equal to PN_XNUM (0xffff), this member holds PN_XNUM
                   (0xffff) and the real number of entries in the program header
                   table is held in the sh_info member of the initial entry in
                   section header table.  Otherwise, the sh_info member of the
                   initial entry contains the value zero.

                   PN_XNUM  This is defined as 0xffff, the largest number e_phnum
                            can have, specifying where the actual number of
                            program headers is assigned.

       e_shentsize This member holds a sections header's size in bytes.  A section
                   header is one entry in the section header table; all entries
                   are the same size.

       e_shnum     This member holds the number of entries in the section header
                   table.  Thus the product of e_shentsize and e_shnum gives the
                   section header table's size in bytes.  If a file has no section
                   header table, e_shnum holds the value of zero.

                   If the number of entries in the section header table is larger
                   than or equal to SHN_LORESERVE (0xff00), e_shnum holds the
                   value zero and the real number of entries in the section header
                   table is held in the sh_size member of the initial entry in
                   section header table.  Otherwise, the sh_size member of the
                   initial entry in the section header table holds the value zero.

       e_shstrndx  This member holds the section header table index of the entry
                   associated with the section name string table.  If the file has
                   no section name string table, this member holds the value
                   SHN_UNDEF.

                   If the index of section name string table section is larger
                   than or equal to SHN_LORESERVE (0xff00), this member holds
                   SHN_XINDEX (0xffff) and the real index of the section name
                   string table section is held in the sh_link member of the
                   initial entry in section header table.  Otherwise, the sh_link
                   member of the initial entry in section header table contains
                   the value zero.

                   SHN_UNDEF     This value marks an undefined, missing,
                                 irrelevant, or otherwise meaningless section
                                 reference.  For example, a symbol "defined"
                                 relative to section number SHN_UNDEF is an
                                 undefined symbol.

                   SHN_LORESERVE This value specifies the lower bound of the range
                                 of reserved indices.

                   SHN_LOPROC    Values greater than or equal to SHN_HIPROC are
                                 reserved for processor-specific semantics.

                   SHN_HIPROC    Values less than or equal to SHN_LOPROC are
                                 reserved for processor-specific semantics.

                   SHN_ABS       This value specifies absolute values for the
                                 corresponding reference.  For example, symbols
                                 defined relative to section number SHN_ABS have
                                 absolute values and are not affected by
                                 relocation.

                   SHN_COMMON    Symbols defined relative to this section are
                                 common symbols, such as Fortran COMMON or
                                 unallocated C external variables.

                   SHN_HIRESERVE This value specifies the upper bound of the range
                                 of reserved indices between SHN_LORESERVE and
                                 SHN_HIRESERVE, inclusive; the values do not
                                 reference the section header table.  That is, the
                                 section header table does not contain entries for
                                 the reserved indices.

       An executable or shared object file's program header table is an array of
       structures, each describing a segment or other information the system needs
       to prepare the program for execution.  An object file segment contains one
       or more sections.  Program headers are meaningful only for executable and
       shared object files.  A file specifies its own program header size with the
       ELF header's e_phentsize and e_phnum members.  The ELF program header is
       described by the type Elf32_Phdr or Elf64_Phdr depending on the
       architecture:

           typedef struct {
               uint32_t   p_type;
               Elf32_Off  p_offset;
               Elf32_Addr p_vaddr;
               Elf32_Addr p_paddr;
               uint32_t   p_filesz;
               uint32_t   p_memsz;
               uint32_t   p_flags;
               uint32_t   p_align;
           } Elf32_Phdr;

           typedef struct {
               uint32_t   p_type;
               uint32_t   p_flags;
               Elf64_Off  p_offset;
               Elf64_Addr p_vaddr;
               Elf64_Addr p_paddr;
               uint64_t   p_filesz;
               uint64_t   p_memsz;
               uint64_t   p_align;
           } Elf64_Phdr;

       The main difference between the 32-bit and the 64-bit program header lies
       in the location of the p_flags member in the total struct.

       p_type      This member of the Phdr struct tells what kind of segment this
                   array element describes or how to interpret the array element's
                   information.

                   PT_NULL     The array element is unused and the other members'
                               values are undefined.  This lets the program header
                               have ignored entries.

                   PT_LOAD     The array element specifies a loadable segment,
                               described by p_filesz and p_memsz.  The bytes from
                               the file are mapped to the beginning of the memory
                               segment.  If the segment's memory size p_memsz is
                               larger than the file size p_filesz, the "extra"
                               bytes are defined to hold the value 0 and to follow
                               the segment's initialized area.  The file size may
                               not be larger than the memory size.  Loadable
                               segment entries in the program header table appear
                               in ascending order, sorted on the p_vaddr member.

                   PT_DYNAMIC  The array element specifies dynamic linking
                               information.

                   PT_INTERP   The array element specifies the location and size
                               of a null-terminated pathname to invoke as an
                               interpreter.  This segment type is meaningful only
                               for executable files (though it may occur for
                               shared objects).  However it may not occur more
                               than once in a file.  If it is present, it must
                               precede any loadable segment entry.

                   PT_NOTE     The array element specifies the location and size
                               for auxiliary information.

                   PT_SHLIB    This segment type is reserved but has unspecified
                               semantics.  Programs that contain an array element
                               of this type do not conform to the ABI.

                   PT_PHDR     The array element, if present, specifies the
                               location and size of the program header table
                               itself, both in the file and in the memory image of
                               the program.  This segment type may not occur more
                               than once in a file.  Moreover, it may only occur
                               if the program header table is part of the memory
                               image of the program.  If it is present, it must
                               precede any loadable segment entry.

                   PT_LOPROC   Values greater than or equal to PT_HIPROC are
                               reserved for processor-specific semantics.

                   PT_HIPROC   Values less than or equal to PT_LOPROC are reserved
                               for processor-specific semantics.

                   PT_GNU_STACK
                               GNU extension which is used by the Linux kernel to
                               control the state of the stack via the flags set in
                               the p_flags member.

       p_offset    This member holds the offset from the beginning of the file at
                   which the first byte of the segment resides.

       p_vaddr     This member holds the virtual address at which the first byte
                   of the segment resides in memory.

       p_paddr     On systems for which physical addressing is relevant, this
                   member is reserved for the segment's physical address.  Under
                   BSD this member is not used and must be zero.

       p_filesz    This member holds the number of bytes in the file image of the
                   segment.  It may be zero.

       p_memsz     This member holds the number of bytes in the memory image of
                   the segment.  It may be zero.

       p_flags     This member holds a bitmask of flags relevant to the segment:

                   PF_X   An executable segment.
                   PF_W   A writable segment.
                   PF_R   A readable segment.

                   A text segment commonly has the flags PF_X and PF_R.  A data
                   segment commonly has PF_X, PF_W and PF_R.

       p_align     This member holds the value to which the segments are aligned
                   in memory and in the file.  Loadable process segments must have
                   congruent values for p_vaddr and p_offset, modulo the page
                   size.  Values of zero and one mean no alignment is required.
                   Otherwise, p_align should be a positive, integral power of two,
                   and p_vaddr should equal p_offset, modulo p_align.

       A file's section header table lets one locate all the file's sections.  The
       section header table is an array of Elf32_Shdr or Elf64_Shdr structures.
       The ELF header's e_shoff member gives the byte offset from the beginning of
       the file to the section header table.  e_shnum holds the number of entries
       the section header table contains.  e_shentsize holds the size in bytes of
       each entry.

       A section header table index is a subscript into this array.  Some section
       header table indices are reserved: the initial entry and the indices
       between SHN_LORESERVE and SHN_HIRESERVE.  The initial entry is used in ELF
       extensions for e_phnum, e_shnum and e_strndx; in other cases, each field in
       the initial entry is set to zero.  An object file does not have sections
       for these special indices:

              SHN_UNDEF     This value marks an undefined, missing, irrelevant or
                            otherwise meaningless section reference.

              SHN_LORESERVE This value specifies the lower bound of the range of
                            reserved indices.

              SHN_LOPROC    Values greater than or equal to SHN_HIPROC are
                            reserved for processor-specific semantics.

              SHN_HIPROC    Values less than or equal to SHN_LOPROC are reserved
                            for processor-specific semantics.

              SHN_ABS       This value specifies the absolute value for the
                            corresponding reference.  For example, a symbol
                            defined relative to section number SHN_ABS has an
                            absolute value and is not affected by relocation.

              SHN_COMMON    Symbols defined relative to this section are common
                            symbols, such as FORTRAN COMMON or unallocated C
                            external variables.

              SHN_HIRESERVE This value specifies the upper bound of the range of
                            reserved indices.  The system reserves indices between
                            SHN_LORESERVE and SHN_HIRESERVE, inclusive.  The
                            section header table does not contain entries for the
                            reserved indices.

       The section header has the following structure:

           typedef struct {
               uint32_t   sh_name;
               uint32_t   sh_type;
               uint32_t   sh_flags;
               Elf32_Addr sh_addr;
               Elf32_Off  sh_offset;
               uint32_t   sh_size;
               uint32_t   sh_link;
               uint32_t   sh_info;
               uint32_t   sh_addralign;
               uint32_t   sh_entsize;
           } Elf32_Shdr;

           typedef struct {
               uint32_t   sh_name;
               uint32_t   sh_type;
               uint64_t   sh_flags;
               Elf64_Addr sh_addr;
               Elf64_Off  sh_offset;
               uint64_t   sh_size;
               uint32_t   sh_link;
               uint32_t   sh_info;
               uint64_t   sh_addralign;
               uint64_t   sh_entsize;
           } Elf64_Shdr;

       No real differences exist between the 32-bit and 64-bit section headers.

       sh_name   This member specifies the name of the section.  Its value is an
                 index into the section header string table section, giving the
                 location of a null-terminated string.

       sh_type   This member categorizes the section's contents and semantics.

                 SHT_NULL       This value marks the section header as inactive.
                                It does not have an associated section.  Other
                                members of the section header have undefined
                                values.

                 SHT_PROGBITS   This section holds information defined by the
                                program, whose format and meaning are determined
                                solely by the program.

                 SHT_SYMTAB     This section holds a symbol table.  Typically,
                                SHT_SYMTAB provides symbols for link editing,
                                though it may also be used for dynamic linking.
                                As a complete symbol table, it may contain many
                                symbols unnecessary for dynamic linking.  An
                                object file can also contain a SHT_DYNSYM section.

                 SHT_STRTAB     This section holds a string table.  An object file
                                may have multiple string table sections.

                 SHT_RELA       This section holds relocation entries with
                                explicit addends, such as type Elf32_Rela for the
                                32-bit class of object files.  An object may have
                                multiple relocation sections.

                 SHT_HASH       This section holds a symbol hash table.  An object
                                participating in dynamic linking must contain a
                                symbol hash table.  An object file may have only
                                one hash table.

                 SHT_DYNAMIC    This section holds information for dynamic
                                linking.  An object file may have only one dynamic
                                section.

                 SHT_NOTE       This section holds information that marks the file
                                in some way.

                 SHT_NOBITS     A section of this type occupies no space in the
                                file but otherwise resembles SHT_PROGBITS.
                                Although this section contains no bytes, the
                                sh_offset member contains the conceptual file
                                offset.

                 SHT_REL        This section holds relocation offsets without
                                explicit addends, such as type Elf32_Rel for the
                                32-bit class of object files.  An object file may
                                have multiple relocation sections.

                 SHT_SHLIB      This section is reserved but has unspecified
                                semantics.

                 SHT_DYNSYM     This section holds a minimal set of dynamic
                                linking symbols.  An object file can also contain
                                a SHT_SYMTAB section.

                 SHT_LOPROC     This value up to and including SHT_HIPROC is
                                reserved for processor-specific semantics.

                 SHT_HIPROC     This value down to and including SHT_LOPROC is
                                reserved for processor-specific semantics.

                 SHT_LOUSER     This value specifies the lower bound of the range
                                of indices reserved for application programs.

                 SHT_HIUSER     This value specifies the upper bound of the range
                                of indices reserved for application programs.
                                Section types between SHT_LOUSER and SHT_HIUSER
                                may be used by the application, without
                                conflicting with current or future system-defined
                                section types.

       sh_flags  Sections support one-bit flags that describe miscellaneous
                 attributes.  If a flag bit is set in sh_flags, the attribute is
                 "on" for the section.  Otherwise, the attribute is "off" or does
                 not apply.  Undefined attributes are set to zero.

                 SHF_WRITE      This section contains data that should be writable
                                during process execution.

                 SHF_ALLOC      This section occupies memory during process
                                execution.  Some control sections do not reside in
                                the memory image of an object file.  This
                                attribute is off for those sections.

                 SHF_EXECINSTR  This section contains executable machine
                                instructions.

                 SHF_MASKPROC   All bits included in this mask are reserved for
                                processor-specific semantics.

       sh_addr   If this section appears in the memory image of a process, this
                 member holds the address at which the section's first byte should
                 reside.  Otherwise, the member contains zero.

       sh_offset This member's value holds the byte offset from the beginning of
                 the file to the first byte in the section.  One section type,
                 SHT_NOBITS, occupies no space in the file, and its sh_offset
                 member locates the conceptual placement in the file.

       sh_size   This member holds the section's size in bytes.  Unless the
                 section type is SHT_NOBITS, the section occupies sh_size bytes in
                 the file.  A section of type SHT_NOBITS may have a nonzero size,
                 but it occupies no space in the file.

       sh_link   This member holds a section header table index link, whose
                 interpretation depends on the section type.

       sh_info   This member holds extra information, whose interpretation depends
                 on the section type.

       sh_addralign
                 Some sections have address alignment constraints.  If a section
                 holds a doubleword, the system must ensure doubleword alignment
                 for the entire section.  That is, the value of sh_addr must be
                 congruent to zero, modulo the value of sh_addralign.  Only zero
                 and positive integral powers of two are allowed.  Values of zero
                 or one mean the section has no alignment constraints.

       sh_entsize
                 Some sections hold a table of fixed-sized entries, such as a
                 symbol table.  For such a section, this member gives the size in
                 bytes for each entry.  This member contains zero if the section
                 does not hold a table of fixed-size entries.

       Various sections hold program and control information:

       .bss      This section holds uninitialized data that contributes to the
                 program's memory image.  By definition, the system initializes
                 the data with zeros when the program begins to run.  This section
                 is of type SHT_NOBITS.  The attribute types are SHF_ALLOC and
                 SHF_WRITE.

       .comment  This section holds version control information.  This section is
                 of type SHT_PROGBITS.  No attribute types are used.

       .ctors    This section holds initialized pointers to the C++ constructor
                 functions.  This section is of type SHT_PROGBITS.  The attribute
                 types are SHF_ALLOC and SHF_WRITE.

       .data     This section holds initialized data that contribute to the
                 program's memory image.  This section is of type SHT_PROGBITS.
                 The attribute types are SHF_ALLOC and SHF_WRITE.

       .data1    This section holds initialized data that contribute to the
                 program's memory image.  This section is of type SHT_PROGBITS.
                 The attribute types are SHF_ALLOC and SHF_WRITE.

       .debug    This section holds information for symbolic debugging.  The
                 contents are unspecified.  This section is of type SHT_PROGBITS.
                 No attribute types are used.

       .dtors    This section holds initialized pointers to the C++ destructor
                 functions.  This section is of type SHT_PROGBITS.  The attribute
                 types are SHF_ALLOC and SHF_WRITE.

       .dynamic  This section holds dynamic linking information.  The section's
                 attributes will include the SHF_ALLOC bit.  Whether the SHF_WRITE
                 bit is set is processor-specific.  This section is of type
                 SHT_DYNAMIC.  See the attributes above.

       .dynstr   This section holds strings needed for dynamic linking, most
                 commonly the strings that represent the names associated with
                 symbol table entries.  This section is of type SHT_STRTAB.  The
                 attribute type used is SHF_ALLOC.

       .dynsym   This section holds the dynamic linking symbol table.  This
                 section is of type SHT_DYNSYM.  The attribute used is SHF_ALLOC.

       .fini     This section holds executable instructions that contribute to the
                 process termination code.  When a program exits normally the
                 system arranges to execute the code in this section.  This
                 section is of type SHT_PROGBITS.  The attributes used are
                 SHF_ALLOC and SHF_EXECINSTR.

       .gnu.version
                 This section holds the version symbol table, an array of
                 ElfN_Half elements.  This section is of type SHT_GNU_versym.  The
                 attribute type used is SHF_ALLOC.

       .gnu.version_d
                 This section holds the version symbol definitions, a table of
                 ElfN_Verdef structures.  This section is of type SHT_GNU_verdef.
                 The attribute type used is SHF_ALLOC.

       .gnu.version_r
                 This section holds the version symbol needed elements, a table of
                 ElfN_Verneed structures.  This section is of type SHT_GNU_versym.
                 The attribute type used is SHF_ALLOC.

       .got      This section holds the global offset table.  This section is of
                 type SHT_PROGBITS.  The attributes are processor specific.

       .hash     This section holds a symbol hash table.  This section is of type
                 SHT_HASH.  The attribute used is SHF_ALLOC.

       .init     This section holds executable instructions that contribute to the
                 process initialization code.  When a program starts to run the
                 system arranges to execute the code in this section before
                 calling the main program entry point.  This section is of type
                 SHT_PROGBITS.  The attributes used are SHF_ALLOC and
                 SHF_EXECINSTR.

       .interp   This section holds the pathname of a program interpreter.  If the
                 file has a loadable segment that includes the section, the
                 section's attributes will include the SHF_ALLOC bit.  Otherwise,
                 that bit will be off.  This section is of type SHT_PROGBITS.

       .line     This section holds line number information for symbolic
                 debugging, which describes the correspondence between the program
                 source and the machine code.  The contents are unspecified.  This
                 section is of type SHT_PROGBITS.  No attribute types are used.

       .note     This section holds information in the "Note Section" format.
                 This section is of type SHT_NOTE.  No attribute types are used.
                 OpenBSD native executables usually contain a .note.openbsd.ident
                 section to identify themselves, for the kernel to bypass any
                 compatibility ELF binary emulation tests when loading the file.

       .note.GNU-stack
                 This section is used in Linux object files for declaring stack
                 attributes.  This section is of type SHT_PROGBITS.  The only
                 attribute used is SHF_EXECINSTR.  This indicates to the GNU
                 linker that the object file requires an executable stack.

       .plt      This section holds the procedure linkage table.  This section is
                 of type SHT_PROGBITS.  The attributes are processor specific.

       .relNAME  This section holds relocation information as described below.  If
                 the file has a loadable segment that includes relocation, the
                 section's attributes will include the SHF_ALLOC bit.  Otherwise
                 the bit will be off.  By convention, "NAME" is supplied by the
                 section to which the relocations apply.  Thus a relocation
                 section for .text normally would have the name .rel.text.  This
                 section is of type SHT_REL.

       .relaNAME This section holds relocation information as described below.  If
                 the file has a loadable segment that includes relocation, the
                 section's attributes will include the SHF_ALLOC bit.  Otherwise
                 the bit will be off.  By convention, "NAME" is supplied by the
                 section to which the relocations apply.  Thus a relocation
                 section for .text normally would have the name .rela.text.  This
                 section is of type SHT_RELA.

       .rodata   This section holds read-only data that typically contributes to a
                 nonwritable segment in the process image.  This section is of
                 type SHT_PROGBITS.  The attribute used is SHF_ALLOC.

       .rodata1  This section holds read-only data that typically contributes to a
                 nonwritable segment in the process image.  This section is of
                 type SHT_PROGBITS.  The attribute used is SHF_ALLOC.

       .shstrtab This section holds section names.  This section is of type
                 SHT_STRTAB.  No attribute types are used.

       .strtab   This section holds strings, most commonly the strings that
                 represent the names associated with symbol table entries.  If the
                 file has a loadable segment that includes the symbol string
                 table, the section's attributes will include the SHF_ALLOC bit.
                 Otherwise the bit will be off.  This section is of type
                 SHT_STRTAB.

       .symtab   This section holds a symbol table.  If the file has a loadable
                 segment that includes the symbol table, the section's attributes
                 will include the SHF_ALLOC bit.  Otherwise the bit will be off.
                 This section is of type SHT_SYMTAB.

       .text     This section holds the "text", or executable instructions, of a
                 program.  This section is of type SHT_PROGBITS.  The attributes
                 used are SHF_ALLOC and SHF_EXECINSTR.

       String table sections hold null-terminated character sequences, commonly
       called strings.  The object file uses these strings to represent symbol and
       section names.  One references a string as an index into the string table
       section.  The first byte, which is index zero, is defined to hold a null
       byte ('\0').  Similarly, a string table's last byte is defined to hold a
       null byte, ensuring null termination for all strings.

       An object file's symbol table holds information needed to locate and
       relocate a program's symbolic definitions and references.  A symbol table
       index is a subscript into this array.

           typedef struct {
               uint32_t      st_name;
               Elf32_Addr    st_value;
               uint32_t      st_size;
               unsigned char st_info;
               unsigned char st_other;
               uint16_t      st_shndx;
           } Elf32_Sym;

           typedef struct {
               uint32_t      st_name;
               unsigned char st_info;
               unsigned char st_other;
               uint16_t      st_shndx;
               Elf64_Addr    st_value;
               uint64_t      st_size;
           } Elf64_Sym;

       The 32-bit and 64-bit versions have the same members, just in a different
       order.

       st_name   This member holds an index into the object file's symbol string
                 table, which holds character representations of the symbol names.
                 If the value is nonzero, it represents a string table index that
                 gives the symbol name.  Otherwise, the symbol table has no name.

       st_value  This member gives the value of the associated symbol.

       st_size   Many symbols have associated sizes.  This member holds zero if
                 the symbol has no size or an unknown size.

       st_info   This member specifies the symbol's type and binding attributes:

                 STT_NOTYPE  The symbol's type is not defined.

                 STT_OBJECT  The symbol is associated with a data object.

                 STT_FUNC    The symbol is associated with a function or other
                             executable code.

                 STT_SECTION The symbol is associated with a section.  Symbol
                             table entries of this type exist primarily for
                             relocation and normally have STB_LOCAL bindings.

                 STT_FILE    By convention, the symbol's name gives the name of
                             the source file associated with the object file.  A
                             file symbol has STB_LOCAL bindings, its section index
                             is SHN_ABS, and it precedes the other STB_LOCAL
                             symbols of the file, if it is present.

                 STT_LOPROC  This value up to and including STT_HIPROC is reserved
                             for processor-specific semantics.

                 STT_HIPROC  This value down to and including STT_LOPROC is
                             reserved for processor-specific semantics.

                 STB_LOCAL   Local symbols are not visible outside the object file
                             containing their definition.  Local symbols of the
                             same name may exist in multiple files without
                             interfering with each other.

                 STB_GLOBAL  Global symbols are visible to all object files being
                             combined.  One file's definition of a global symbol
                             will satisfy another file's undefined reference to
                             the same symbol.

                 STB_WEAK    Weak symbols resemble global symbols, but their
                             definitions have lower precedence.

                 STB_LOPROC  This value up to and including STB_HIPROC is reserved
                             for processor-specific semantics.

                 STB_HIPROC  This value down to and including STB_LOPROC is
                             reserved for processor-specific semantics.

                             There are macros for packing and unpacking the
                             binding and type fields:

                             ELF32_ST_BIND(info) or ELF64_ST_BIND(info) extract a
                             binding from an st_info value.

                             ELF32_ST_TYPE(info) or ELF64_ST_TYPE(info)
                             extract a type from an st_info value.

                             ELF32_ST_INFO(bind, type) or ELF64_ST_INFO(bind,
                             type)
                             convert a binding and a type into an st_info value.

       st_other  This member defines the symbol visibility.

                 STV_DEFAULT     Default symbol visibility rules.
                 STV_INTERNAL    Processor-specific hidden class.
                 STV_HIDDEN      Symbol is unavailable in other modules.
                 STV_PROTECTED   Not preemptible, not exported.

                 There are macros for extracting the visibility type:

                 ELF32_ST_VISIBILITY(other) or ELF64_ST_VISIBILITY(other)

       st_shndx  Every symbol table entry is "defined" in relation to some
                 section.  This member holds the relevant section header table
                 index.

       Relocation is the process of connecting symbolic references with symbolic
       definitions.  Relocatable files must have information that describes how to
       modify their section contents, thus allowing executable and shared object
       files to hold the right information for a process's program image.
       Relocation entries are these data.

       Relocation structures that do not need an addend:

           typedef struct {
               Elf32_Addr r_offset;
               uint32_t   r_info;
           } Elf32_Rel;

           typedef struct {
               Elf64_Addr r_offset;
               uint64_t   r_info;
           } Elf64_Rel;

       Relocation structures that need an addend:

           typedef struct {
               Elf32_Addr r_offset;
               uint32_t   r_info;
               int32_t    r_addend;
           } Elf32_Rela;

           typedef struct {
               Elf64_Addr r_offset;
               uint64_t   r_info;
               int64_t    r_addend;
           } Elf64_Rela;

       r_offset    This member gives the location at which to apply the relocation
                   action.  For a relocatable file, the value is the byte offset
                   from the beginning of the section to the storage unit affected
                   by the relocation.  For an executable file or shared object,
                   the value is the virtual address of the storage unit affected
                   by the relocation.

       r_info      This member gives both the symbol table index with respect to
                   which the relocation must be made and the type of relocation to
                   apply.  Relocation types are processor specific.  When the text
                   refers to a relocation entry's relocation type or symbol table
                   index, it means the result of applying ELF[32|64]_R_TYPE or
                   ELF[32|64]_R_SYM, respectively, to the entry's r_info member.

       r_addend    This member specifies a constant addend used to compute the
                   value to be stored into the relocatable field.

       The .dynamic section contains a series of structures that hold relevant
       dynamic linking information.  The d_tag member controls the interpretation
       of d_un.

           typedef struct {
               Elf32_Sword    d_tag;
               union {
                   Elf32_Word d_val;
                   Elf32_Addr d_ptr;
               } d_un;
           } Elf32_Dyn;
           extern Elf32_Dyn _DYNAMIC[];

           typedef struct {
               Elf64_Sxword    d_tag;
               union {
                   Elf64_Xword d_val;
                   Elf64_Addr  d_ptr;
               } d_un;
           } Elf64_Dyn;
           extern Elf64_Dyn _DYNAMIC[];

       d_tag     This member may have any of the following values:

                 DT_NULL     Marks end of dynamic section

                 DT_NEEDED   String table offset to name of a needed library

                 DT_PLTRELSZ Size in bytes of PLT relocs

                 DT_PLTGOT   Address of PLT and/or GOT

                 DT_HASH     Address of symbol hash table

                 DT_STRTAB   Address of string table

                 DT_SYMTAB   Address of symbol table

                 DT_RELA     Address of Rela relocs table

                 DT_RELASZ   Size in bytes of Rela table

                 DT_RELAENT  Size in bytes of a Rela table entry

                 DT_STRSZ    Size in bytes of string table

                 DT_SYMENT   Size in bytes of a symbol table entry

                 DT_INIT     Address of the initialization function

                 DT_FINI     Address of the termination function

                 DT_SONAME   String table offset to name of shared object

                 DT_RPATH    String table offset to library search path
                             (deprecated)

                 DT_SYMBOLIC Alert linker to search this shared object before the
                             executable for symbols

                 DT_REL      Address of Rel relocs table

                 DT_RELSZ    Size in bytes of Rel table

                 DT_RELENT   Size in bytes of a Rel table entry

                 DT_PLTREL   Type of reloc the PLT refers (Rela or Rel)

                 DT_DEBUG    Undefined use for debugging

                 DT_TEXTREL  Absence of this indicates no relocs should apply to a
                             nonwritable segment

                 DT_JMPREL   Address of reloc entries solely for the PLT

                 DT_BIND_NOW Instruct dynamic linker to process all relocs before
                             transferring control to the executable

                 DT_RUNPATH  String table offset to library search path

                 DT_LOPROC   Start of processor-specific semantics

                 DT_HIPROC   End of processor-specific semantics

       d_val     This member represents integer values with various
                 interpretations.

       d_ptr     This member represents program virtual addresses.  When
                 interpreting these addresses, the actual address should be
                 computed based on the original file value and memory base
                 address.  Files do not contain relocation entries to fixup these
                 addresses.

       _DYNAMIC  Array containing all the dynamic structures in the .dynamic
                 section.  This is automatically populated by the linker.

NOTES top

       ELF first appeared in System V.  The ELF format is an adopted standard.

       The extensions for e_phnum, e_shnum and e_strndx respectively are Linux
       extensions.  Sun, BSD and AMD64 also support them; for further information,
       look under SEE ALSO.

SEE ALSO top

       as(1), gdb(1), ld(1), objdump(1), execve(2), core(5)

       Hewlett-Packard, Elf-64 Object File Format.

       Santa Cruz Operation, System V Application Binary Interface.

       UNIX System Laboratories, "Object Files", Executable and Linking Format
       (ELF).

       Sun Microsystems, Linker and Libraries Guide.

       AMD64 ABI Draft, System V Application Binary Interface AMD64 Architecture
       Processor Supplement.

COLOPHON top

       This page is part of release 3.45 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                               2010-06-19                              ELF(5)


encrypt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

ENCRYPT(3)                   Linux Programmer's Manual                  ENCRYPT(3)

NAME top

       encrypt, setkey, encrypt_r, setkey_r - encrypt 64-bit messages

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <unistd.h>

       void encrypt(char block[64], int edflag);

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <stdlib.h>

       void setkey(const char *key);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <crypt.h>

       void setkey_r(const char *key, struct crypt_data *data);
       void encrypt_r(char *block, int edflag, struct crypt_data *data);

       Each of these requires linking with -lcrypt.

DESCRIPTION top

       These functions encrypt and decrypt 64-bit messages.  The setkey() function
       sets the key used by encrypt().  The key argument used here is an array of
       64 bytes, each of which has numerical value 1 or 0.  The bytes key[n] where
       n=8*i-1 are ignored, so that the effective key length is 56 bits.

       The encrypt() function modifies the passed buffer, encoding if edflag is 0,
       and decoding if 1 is being passed.  Like the key argument, also block is a
       bit vector representation of the actual value that is encoded.  The result
       is returned in that same vector.

       These two functions are not reentrant, that is, the key data is kept in
       static storage.  The functions setkey_r() and encrypt_r() are the reentrant
       versions.  They use the following structure to hold the key data:

           struct crypt_data {
               char     keysched[16 * 8];
               char     sb0[32768];
               char     sb1[32768];
               char     sb2[32768];
               char     sb3[32768];
               char     crypt_3_buf[14];
               char     current_salt[2];
               long int current_saltbits;
               int      direction;
               int      initialized;
           };

       Before calling setkey_r() set data->initialized to zero.

RETURN VALUE top

       These functions do not return any value.

ERRORS top

       Set errno to zero before calling the above functions.  On success, it is
       unchanged.

       ENOSYS The function is not provided.  (For example because of former USA
              export restrictions.)

CONFORMING TO top

       The functions encrypt() and setkey() conform to SVr4, SUSv2, and
       POSIX.1-2001.  The functions encrypt_r() and setkey_r() are GNU extensions.

NOTES top

       In glibc 2.2 these functions use the DES algorithm.

EXAMPLE top

       You need to link with libcrypt to compile this example with glibc.  To do
       useful work the key[] and txt[] arrays must be filled with a useful bit
       pattern.

       #define _XOPEN_SOURCE
       #include <unistd.h>
       #include <stdlib.h>

       int
       main(void)
       {
           char key[64];      /* bit pattern for key */
           char txt[64];      /* bit pattern for messages */

           setkey(key);
           encrypt(txt, 0);   /* encode */
           encrypt(txt, 1);   /* decode */
       }

SEE ALSO top

       cbc_crypt(3), crypt(3), ecb_crypt(3),

COLOPHON top

       This page is part of release 3.45 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/.

                                    2003-04-04                          ENCRYPT(3)


setaliasent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SETALIASENT(3)               Linux Programmer's Manual              SETALIASENT(3)

NAME top

       setaliasent,   endaliasent,   getaliasent,  getaliasent_r,  getaliasbyname,
       getaliasbyname_r - read an alias entry

SYNOPSIS top

       #include <aliases.h>

       void setaliasent(void);

       void endaliasent(void);

       struct aliasent *getaliasent(void);

       int getaliasent_r(struct aliasent *result,
               char *buffer, size_t buflen, struct aliasent **res);

       struct aliasent *getaliasbyname(const char *name);

       int getaliasbyname_r(const char *name, struct aliasent *result,
               char *buffer, size_t buflen, struct aliasent **res);

DESCRIPTION top

       One of the databases available with the Name Service Switch (NSS) is the
       aliases database, that contains mail aliases.  (To find out which databases
       are supported, try  getent --help.)  Six functions are provided to access
       the aliases database.

       The getaliasent() function returns a pointer to a structure containing the
       group information from the aliases database.  The first time it is called
       it returns the first entry; thereafter, it returns successive entries.

       The setaliasent() function rewinds the file pointer to the beginning of the
       aliases database.

       The endaliasent() function closes the aliases database.

       getaliasent_r() is the reentrant version of the previous function.  The
       requested structure is stored via the first argument but the programmer
       needs to fill the other arguments also.  Not providing enough space causes
       the function to fail.

       The function getaliasbyname() takes the name argument and searches the
       aliases database.  The entry is returned as a pointer to a struct aliasent.

       getaliasbyname_r() is the reentrant version of the previous function.  The
       requested structure is stored via the second argument but the programmer
       needs to fill the other arguments also.  Not providing enough space causes
       the function to fail.

       The struct aliasent is defined in <aliases.h>:

           struct aliasent {
               char    *alias_name;             /* alias name */
               size_t   alias_members_len;
               char   **alias_members;          /* alias name list */
               int      alias_local;
           };

RETURN VALUE top

       The functions getaliasent_r() and getaliasbyname_r() return a nonzero value
       on error.

FILES top

       The default alias database is the file /etc/aliases.  This can be changed
       in the /etc/nsswitch.conf file.

CONFORMING TO top

       These routines are glibc-specific.  The NeXT system has similar routines:

           #include <aliasdb.h>

           void alias_setent(void);
           void alias_endent(void);
           alias_ent *alias_getent(void);
           alias_ent *alias_getbyname(char *name);

EXAMPLE top

       The following example compiles with gcc example.c -o example.  It will dump
       all names in the alias database.

       #include <aliases.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <errno.h>

       int
       main(void)
       {
           struct aliasent *al;
           setaliasent();
           for (;;) {
               al = getaliasent();
               if (al == NULL)
                   break;
               printf("Name: %s\n", al->alias_name);
           }
           if (errno) {
               perror("reading alias");
               exit(EXIT_FAILURE);
           }
           endaliasent();
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getgrent(3), getpwent(3), getspent(3), aliases(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2003-09-09                      SETALIASENT(3)


getfsent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETFSENT(3)                  Linux Programmer's Manual                 GETFSENT(3)

NAME top

       getfsent, getfsspec, getfsfile, setfsent, endfsent - handle fstab entries

SYNOPSIS top

       #include <fstab.h>

       void endfsent(void);

       struct fstab *getfsent(void);

       struct fstab *getfsfile(const char *mount_point);

       struct fstab *getfsspec(const char *special_file);

       int setfsent(void);

DESCRIPTION top

       These functions read from the file /etc/fstab.  The struct fstab is defined
       by:

           struct fstab {
               char       *fs_spec;       /* block device name */
               char       *fs_file;       /* mount point */
               char       *fs_vfstype;    /* file-sysem type */
               char       *fs_mntops;     /* mount options */
               const char *fs_type;       /* rw/rq/ro/sw/xx option */
               int         fs_freq;       /* dump frequency, in days */
               int         fs_passno;     /* pass number on parallel dump */
           };

       Here the field fs_type contains (on a *BSD system) one of the five strings
       "rw", "rq", "ro", "sw", "xx" (read-write, read-write with quota, read-only,
       swap, ignore).

       The function setfsent() opens the file when required and positions it at
       the first line.

       The function getfsent() parses the next line from the file.  (After opening
       it when required.)

       The function endfsent() closes the file when required.

       The function getfsspec() searches the file from the start and returns the
       first entry found for which the fs_spec field matches the special_file
       argument.

       The function getfsfile() searches the file from the start and returns the
       first entry found for which the fs_file field matches the mount_point
       argument.

RETURN VALUE top

       Upon success, the functions getfsent(), getfsfile(), and getfsspec() return
       a pointer to a struct fstab, while setfsent() returns 1.  Upon failure or
       end-of-file, these functions return NULL and 0, respectively.

CONFORMING TO top

       These functions are not in POSIX.1-2001.  Several operating systems have
       them, e.g., *BSD, SunOS, Digital UNIX, AIX (which also has a getfstype()).
       HP-UX has functions of the same names, that however use a struct checklist
       instead of a struct fstab, and calls these functions obsolete, superseded
       by getmntent(3).

NOTES top

       These functions are not thread-safe.

       Since Linux allows mounting a block special device in several places, and
       since several devices can have the same mount point, where the last device
       with a given mount point is the interesting one, while getfsfile() and
       getfsspec() only return the first occurrence, these two functions are not
       suitable for use under Linux.

SEE ALSO top

       getmntent(3), fstab(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2002-02-28                         GETFSENT(3)


getgrent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETGRENT(3)                  Linux Programmer's Manual                 GETGRENT(3)

NAME top

       getgrent, setgrent, endgrent - get group file entry

SYNOPSIS top

       #include <sys/types.h>
       #include <grp.h>

       struct group *getgrent(void);

       void setgrent(void);

       void endgrent(void);

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

       setgrent():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED ||
           /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

       getgrent(), endgrent():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The getgrent() function returns a pointer to a structure containing the
       broken-out fields of a record in the group database (e.g., the local group
       file /etc/group, NIS, and LDAP).  The first time getgrent() is called, it
       returns the first entry; thereafter, it returns successive entries.

       The setgrent() function rewinds to the beginning of the group database, to
       allow repeated scans.

       The endgrent() function is used to close the group database after all
       processing has been performed.

       The group structure is defined in <grp.h> as follows:

           struct group {
               char   *gr_name;       /* group name */
               char   *gr_passwd;     /* group password */
               gid_t   gr_gid;        /* group ID */
               char  **gr_mem;        /* group members */
           };

       For more information about the fields of this structure, see group(5).

RETURN VALUE top

       The getgrent() function returns a pointer to a group structure, or NULL if
       there are no more entries or an error occurs.

       Upon error, errno may be set.  If one wants to check errno after the call,
       it should be set to zero before the call.

       The return value may point to a static area, and may be overwritten by
       subsequent calls to getgrent(), getgrgid(3), or getgrnam(3).  (Do not pass
       the returned pointer to free(3).)

ERRORS top

       EINTR  A signal was caught.

       EIO    I/O error.

       EMFILE The calling process already has too many open files.

       ENFILE Too many open files in the system.

       ENOMEM Insufficient memory to allocate group structure.

       ERANGE Insufficient buffer space supplied.

FILES top

       /etc/group
              local group database file

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

SEE ALSO top

       fgetgrent(3), getgrent_r(3), getgrgid(3), getgrnam(3), getgrouplist(3),
       putgrent(3), group(5)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-10-21                         GETGRENT(3)


gethostbyname(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETHOSTBYNAME(3)             Linux Programmer's Manual            GETHOSTBYNAME(3)

NAME top

       gethostbyname,  gethostbyaddr, sethostent, gethostent, endhostent, h_errno,
       herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, geth-
       ostbyname_r, gethostent_r - get network host entry

SYNOPSIS top

       #include <netdb.h>
       extern int h_errno;

       struct hostent *gethostbyname(const char *name);

       #include <sys/socket.h>       /* for AF_INET */
       struct hostent *gethostbyaddr(const void *addr,
                                     socklen_t len, int type);

       void sethostent(int stayopen);

       void endhostent(void);

       void herror(const char *s);

       const char *hstrerror(int err);

       /* System V/POSIX extension */
       struct hostent *gethostent(void);

       /* GNU extensions */
       struct hostent *gethostbyname2(const char *name, int af);

       int gethostent_r(
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyaddr_r(const void *addr, socklen_t len, int type,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyname_r(const char *name,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyname2_r(const char *name, int [22maf,[0m
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

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

       gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
       gethostbyname2_r():
           _BSD_SOURCE || _SVID_SOURCE

       herror(), hstrerror():
           Since glibc 2.8:
               _BSD_SOURCE || _SVID_SOURCE || _GNU_SOURCE
           Before glibc 2.8:
               none

DESCRIPTION top

       The gethostbyname*() and gethostbyaddr*() functions are obsolete.
       Applications should use getaddrinfo(3) and getnameinfo(3) instead.

       The gethostbyname() function returns a structure of type hostent for the
       given host name.  Here name is either a hostname, or an IPv4 address in
       standard dot notation (as for inet_addr(3)), or an IPv6 address in colon
       (and possibly dot) notation.  (See RFC 1884 for the description of IPv6
       addresses.)  If name is an IPv4 or IPv6 address, no lookup is performed and
       gethostbyname() simply copies name into the h_name field and its struct
       in_addr equivalent into the h_addr_list[0] field of the returned hostent
       structure.  If name doesn't end in a dot and the environment variable
       HOSTALIASES is set, the alias file pointed to by HOSTALIASES will first be
       searched for name (see hostname(7) for the file format).  The current
       domain and its parents are searched unless name ends in a dot.

       The gethostbyaddr() function returns a structure of type hostent for the
       given host address addr of length len and address type type.  Valid address
       types are AF_INET and AF_INET6.  The host address argument is a pointer to
       a struct of a type depending on the address type, for example a struct
       in_addr * (probably obtained via a call to inet_addr(3)) for address type
       AF_INET.

       The sethostent() function specifies, if stayopen is true (1), that a
       connected TCP socket should be used for the name server queries and that
       the connection should remain open during successive queries.  Otherwise,
       name server queries will use UDP datagrams.

       The endhostent() function ends the use of a TCP connection for name server
       queries.

       The (obsolete) herror() function prints the error message associated with
       the current value of h_errno on stderr.

       The (obsolete) hstrerror() function takes an error number (typically
       h_errno) and returns the corresponding message string.

       The domain name queries carried out by gethostbyname() and gethostbyaddr()
       use a combination of any or all of the name server named(8), a broken out
       line from /etc/hosts, and the Network Information Service (NIS or YP),
       depending upon the contents of the order line in /etc/host.conf.  The
       default action is to query named(8), followed by /etc/hosts.

       The hostent structure is defined in <netdb.h> as follows:

           struct hostent {
               char  *h_name;            /* official name of host */
               char **h_aliases;         /* alias list */
               int    h_addrtype;        /* host address type */
               int    h_length;          /* length of address */
               char **h_addr_list;       /* list of addresses */
           }
           #define h_addr h_addr_list[0] /* for backward compatibility */

       The members of the hostent structure are:

       h_name The official name of the host.

       h_aliases
              An array of alternative names for the host, terminated by a NULL
              pointer.

       h_addrtype
              The type of address; always AF_INET or AF_INET6 at present.

       h_length
              The length of the address in bytes.

       h_addr_list
              An array of pointers to network addresses for the host (in network
              byte order), terminated by a NULL pointer.

       h_addr The first address in h_addr_list for backward compatibility.

RETURN VALUE top

       The gethostbyname() and gethostbyaddr() functions return the hostent
       structure or a NULL pointer if an error occurs.  On error, the h_errno
       variable holds an error number.  When non-NULL, the return value may point
       at static data, see the notes below.

ERRORS top

       The variable h_errno can have the following values:

       HOST_NOT_FOUND
              The specified host is unknown.

       NO_ADDRESS or NO_DATA
              The requested name is valid but does not have an IP address.

       NO_RECOVERY
              A nonrecoverable name server error occurred.

       TRY_AGAIN
              A temporary error occurred on an authoritative name server.  Try
              again later.

FILES top

       /etc/host.conf
              resolver configuration file

       /etc/hosts
              host database file

       /etc/nsswitch.conf
              name service switch configuration

CONFORMING TO top

       POSIX.1-2001 specifies gethostbyname(), gethostbyaddr(), sethostent(),
       endhostent(), gethostent(), and h_errno; gethostbyname(), gethostbyaddr(),
       and h_errno are marked obsolescent in that standard.  POSIX.1-2008 removes
       the specifications of gethostbyname(), gethostbyaddr(), and h_errno,
       recommending the use of getaddrinfo(3) and getnameinfo(3) instead.

NOTES top

       The functions gethostbyname() and gethostbyaddr() may return pointers to
       static data, which may be overwritten by later calls.  Copying the struct
       hostent does not suffice, since it contains pointers; a deep copy is
       required.

       In the original BSD implementation the len argument of gethostbyname() was
       an int.  The SUSv2 standard is buggy and declares the len argument of
       gethostbyaddr() to be of type size_t.  (That is wrong, because it has to be
       int, and size_t is not.  POSIX.1-2001 makes it socklen_t, which is OK.)
       See also accept(2).

       The BSD prototype for gethostbyaddr() uses const char * for the first
       argument.

System V/POSIX Extension

       POSIX requires the gethostent() call, that should return the next entry in
       the host data base.  When using DNS/BIND this does not make much sense, but
       it may be reasonable if the host data base is a file that can be read line
       by line.  On many systems a routine of this name reads from the file
       /etc/hosts.  It may be available only when the library was built without
       DNS support.  The glibc version will ignore ipv6 entries.  This function is
       not reentrant, and glibc adds a reentrant version gethostent_r().

GNU Extensions

       Glibc2 also has a gethostbyname2() that works like gethostbyname(), but
       permits to specify the address family to which the address must belong.

       Glibc2 also has reentrant versions gethostent_r(), gethostbyaddr_r(),
       gethostbyname_r() and gethostbyname2_r().  The caller supplies a hostent
       structure ret which will be filled in on success, and a temporary work
       buffer buf of size buflen.  After the call, result will point to the result
       on success.  In case of an error or if no entry is found result will be
       NULL.  The functions return 0 on success and a nonzero error number on
       failure.  In addition to the errors returned by the nonreentrant versions
       of these functions, if buf is too small, the functions will return ERANGE,
       and the call should be retried with a larger buffer.  The global variable
       h_errno is not modified, but the address of a variable in which to store
       error numbers is passed in h_errnop.

BUGS top

       gethostbyname() does not recognize components of a dotted IPv4 address
       string that are expressed in hexadecimal.

SEE ALSO top

       getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3),
       resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-10-04                    GETHOSTBYNAME(3)


getnetent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETNETENT(3)                 Linux Programmer's Manual                GETNETENT(3)

NAME top

       getnetent,  getnetbyname,  getnetbyaddr, setnetent, endnetent - get network
       entry

SYNOPSIS top

       #include <netdb.h>

       struct netent *getnetent(void);

       struct netent *getnetbyname(const char *name);

       struct netent *getnetbyaddr(uint32_t net, int type);

       void setnetent(int stayopen);

       void endnetent(void);

DESCRIPTION top

       The getnetent() function reads the next entry from the networks database
       and returns a netent structure containing the broken-out fields from the
       entry.  A connection is opened to the database if necessary.

       The getnetbyname() function returns a netent structure for the entry from
       the database that matches the network name.

       The getnetbyaddr() function returns a netent structure for the entry from
       the database that matches the network number net of type type.  The net
       argument must be in host byte order.

       The setnetent() function opens a connection to the database, and sets the
       next entry to the first entry.  If stayopen is nonzero, then the connection
       to the database will not be closed between calls to one of the getnet*()
       functions.

       The endnetent() function closes the connection to the database.

       The netent structure is defined in <netdb.h> as follows:

           struct netent {
               char      *n_name;     /* official network name */
               char     **n_aliases;  /* alias list */
               int        n_addrtype; /* net address type */
               uint32_t   n_net;      /* network number */
           }

       The members of the netent structure are:

       n_name The official name of the network.

       n_aliases
              A NULL-terminated list of alternative names for the network.

       n_addrtype
              The type of the network number; always AF_INET.

       n_net  The network number in host byte order.

RETURN VALUE top

       The getnetent(), getnetbyname() and getnetbyaddr() functions return a
       pointer to a statically allocated netent structure, or a NULL pointer if an
       error occurs or the end of the file is reached.

FILES top

       /etc/networks
              networks database file

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

NOTES top

       In glibc versions before 2.2, the net argument of getnetbyaddr() was of
       type long.

SEE ALSO top

       getnetent_r(3), getprotoent(3), getservent(3)
       RFC 1101

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-19                        GETNETENT(3)


setnetgrent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETNETGRENT(3)               Linux Programmer's Manual              SETNETGRENT(3)

NAME top

       setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr - handle net-
       work group entries

SYNOPSIS top

       #include <netdb.h>

       int setnetgrent(const char *netgroup);

       void endnetgrent(void);

       int getnetgrent(char **host, char **user, char **domain);

       int getnetgrent_r(char **host, char **user,
                         char **domain, char *buf, int buflen);

       int innetgr(const char *netgroup, const char *host,
                   const char *user, const char *domain);

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

       setnetgrent(), endnetgrent(), getnetgrent(), getnetgrent_r(), innetgr():
       _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The netgroup is a SunOS invention.  A netgroup database is a list of string
       triples (hostname, username, domainname) or other netgroup names.  Any of
       the elements in a triple can be empty, which means that anything matches.
       The functions described here allow access to the netgroup databases.  The
       file /etc/nsswitch.conf defines what database is searched.

       The setnetgrent() call defines the netgroup that will be searched by
       subsequent getnetgrent() calls.  The getnetgrent() function retrieves the
       next netgroup entry, and returns pointers in host, user, domain.  A NULL
       pointer means that the corresponding entry matches any string.  The
       pointers are valid only as long as there is no call to other netgroup-
       related functions.  To avoid this problem you can use the GNU function
       getnetgrent_r() that stores the strings in the supplied buffer.  To free
       all allocated buffers use endnetgrent().

       In most cases you only want to check if the triplet (hostname, username,
       domainname) is a member of a netgroup.  The function innetgr() can be used
       for this without calling the above three functions.  Again, a NULL pointer
       is a wildcard and matches any string.  The function is thread-safe.

RETURN VALUE top

       These functions return 1 on success and 0 for failure.

FILES top

       /etc/netgroup
       /etc/nsswitch.conf

CONFORMING TO top

       These functions are not in POSIX.1-2001, but setnetgrent(), endnetgrent(),
       getnetgrent(), and innetgr() are available on most UNIX systems.
       getnetgrent_r() is not widely available on other systems.

NOTES top

       In the BSD implementation, setnetgrent() returns void.

SEE ALSO top

       sethostent(3), setprotoent(3), setservent(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                      SETNETGRENT(3)


getprotoent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETPROTOENT(3)               Linux Programmer's Manual              GETPROTOENT(3)

NAME top

       getprotoent,  getprotobyname,  getprotobynumber, setprotoent, endprotoent -
       get protocol entry

SYNOPSIS top

       #include <netdb.h>

       struct protoent *getprotoent(void);

       struct protoent *getprotobyname(const char *name);

       struct protoent *getprotobynumber(int proto);

       void setprotoent(int stayopen);

       void endprotoent(void);

DESCRIPTION top

       The getprotoent() function reads the next entry from the protocols database
       (see protocols(5)) and returns a protoent structure containing the broken-
       out fields from the entry.  A connection is opened to the database if
       necessary.

       The getprotobyname() function returns a protoent structure for the entry
       from the database that matches the protocol name name.  A connection is
       opened to the database if necessary.

       The getprotobynumber() function returns a protoent structure for the entry
       from the database that matches the protocol number number.  A connection is
       opened to the database if necessary.

       The setprotoent() function opens a connection to the database, and sets the
       next entry to the first entry.  If stayopen is nonzero, then the connection
       to the database will not be closed between calls to one of the getproto*()
       functions.

       The endprotoent() function closes the connection to the database.

       The protoent structure is defined in <netdb.h> as follows:

           struct protoent {
               char  *p_name;       /* official protocol name */
               char **p_aliases;    /* alias list */
               int    p_proto;      /* protocol number */
           }

       The members of the protoent structure are:

       p_name The official name of the protocol.

       p_aliases
              A NULL-terminated list of alternative names for the protocol.

       p_proto
              The protocol number.

RETURN VALUE top

       The getprotoent(), getprotobyname() and getprotobynumber() functions return
       a pointer to a statically allocated protoent structure, or a NULL pointer
       if an error occurs or the end of the file is reached.

FILES top

       /etc/protocols
              protocol database file

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

SEE ALSO top

       getnetent(3), getprotoent_r(3), getservent(3), protocols(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-19                      GETPROTOENT(3)


getpwent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETPWENT(3)                  Linux Programmer's Manual                 GETPWENT(3)

NAME top

       getpwent, setpwent, endpwent - get password file entry

SYNOPSIS top

       #include <sys/types.h>
       #include <pwd.h>

       struct passwd *getpwent(void);

       void setpwent(void);

       void endpwent(void);

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

       getpwent(), setpwent(), endpwent():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The getpwent() function returns a pointer to a structure containing the
       broken-out fields of a record from the password database (e.g., the local
       password file /etc/passwd, NIS, and LDAP).  The first time getpwent() is
       called, it returns the first entry; thereafter, it returns successive
       entries.

       The setpwent() function rewinds to the beginning of the password database.

       The endpwent() function is used to close the password database after all
       processing has been performed.

       The passwd structure is defined in <pwd.h> as follows:

           struct passwd {
               char   *pw_name;       /* username */
               char   *pw_passwd;     /* user password */
               uid_t   pw_uid;        /* user ID */
               gid_t   pw_gid;        /* group ID */
               char   *pw_gecos;      /* user information */
               char   *pw_dir;        /* home directory */
               char   *pw_shell;      /* shell program */
           };

       For more information about the fields of this structure, see passwd(5).

RETURN VALUE top

       The getpwent() function returns a pointer to a passwd structure, or NULL if
       there are no more entries or an error occurs.  If an error occurs, errno is
       set appropriately.  If one wants to check errno after the call, it should
       be set to zero before the call.

       The return value may point to a static area, and may be overwritten by
       subsequent calls to getpwent(), getpwnam(3), or getpwuid(3).  (Do not pass
       the returned pointer to free(3).)

ERRORS top

       EINTR  A signal was caught.

       EIO    I/O error.

       EMFILE The maximum number (OPEN_MAX) of files was open already in the
              calling process.

       ENFILE The maximum number of files was open already in the system.

       ENOMEM Insufficient memory to allocate passwd structure.

       ERANGE Insufficient buffer space supplied.

FILES top

       /etc/passwd
              local password database file

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  The pw_gecos field is not specified in POSIX,
       but is present on most implementations.

SEE ALSO top

       fgetpwent(3), getpw(3), getpwent_r(3), getpwnam(3), getpwuid(3),
       putpwent(3), passwd(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-21                         GETPWENT(3)


getrpcent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETRPCENT(3)                 Linux Programmer's Manual                GETRPCENT(3)

NAME top

       getrpcent,  getrpcbyname,  getrpcbynumber,  setrpcent,  endrpcent - get RPC
       entry

SYNOPSIS top

       #include <netdb.h>

       struct rpcent *getrpcent(void);

       struct rpcent *getrpcbyname(char *name);

       struct rpcent *getrpcbynumber(int number);

       void setrpcent(int stayopen);

       void endrpcent(void);

DESCRIPTION top

       getrpcent(), getrpcbyname(), and getrpcbynumber() each return a pointer to
       an object with the following structure containing the broken-out fields of
       an entry in the RPC program number data base.

           struct rpcent {
               char  *r_name;     /* name of server for this RPC program */
               char **r_aliases;  /* alias list */
               long   r_number;   /* RPC program number */
           };

       The members of this structure are:

           r_name      The name of the server for this RPC program.

           r_aliases   A NULL-terminated list of alternate names for the RPC
                       program.

           r_number    The RPC program number for this service.

       getrpcent() reads the next entry from the database.  A connection is opened
       to the database if necessary.

       setrpcent() function opens a connection to the database, and sets the next
       entry to the first entry.  If stayopen is nonzero, then the connection to
       the database will not be closed between calls to one of the getrpc*()
       functions.

       The endrpcent() function closes the connection to the database.

       getrpcbyname() and getrpcbynumber() sequentially search from the beginning
       of the file until a matching RPC program name or program number is found,
       or until end-of-file is encountered.

RETURN VALUE top

       On success, getrpcent(), getrpcbyname(), and getrpcbynumber() return a
       pointer to a statically allocated rpcent structure.  A NULL pointer is
       returned on EOF or error.

FILES top

       /etc/rpc
              RPC program number database.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs, Solaris, and many other systems.

BUGS top

       All information is contained in a static area so it must be copied if it is
       to be saved.

SEE ALSO top

       getrpcent_r(3), rpc(5), rpcinfo(8), ypserv(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-19                        GETRPCENT(3)


getservent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETSERVENT(3)                Linux Programmer's Manual               GETSERVENT(3)

NAME top

       getservent, getservbyname, getservbyport, setservent, endservent - get ser-
       vice entry

SYNOPSIS top

       #include <netdb.h>

       struct servent *getservent(void);

       struct servent *getservbyname(const char *name, const char *proto);

       struct servent *getservbyport(int port, const char *proto);

       void setservent(int stayopen);

       void endservent(void);

DESCRIPTION top

       The getservent() function reads the next entry from the services database
       (see services(5)) and returns a servent structure containing the broken-out
       fields from the entry.  A connection is opened to the database if
       necessary.

       The getservbyname() function returns a servent structure for the entry from
       the database that matches the service name using protocol proto.  If proto
       is NULL, any protocol will be matched.  A connection is opened to the
       database if necessary.

       The getservbyport() function returns a servent structure for the entry from
       the database that matches the port port (given in network byte order) using
       protocol proto.  If proto is NULL, any protocol will be matched.  A
       connection is opened to the database if necessary.

       The setservent() function opens a connection to the database, and sets the
       next entry to the first entry.  If stayopen is nonzero, then the connection
       to the database will not be closed between calls to one of the getserv*()
       functions.

       The endservent() function closes the connection to the database.

       The servent structure is defined in <netdb.h> as follows:

           struct servent {
               char  *s_name;       /* official service name */
               char **s_aliases;    /* alias list */
               int    s_port;       /* port number */
               char  *s_proto;      /* protocol to use */
           }

       The members of the servent structure are:

       s_name The official name of the service.

       s_aliases
              A NULL-terminated list of alternative names for the service.

       s_port The port number for the service given in network byte order.

       s_proto
              The name of the protocol to use with this service.

RETURN VALUE top

       The getservent(), getservbyname() and getservbyport() functions return a
       pointer to a statically allocated servent structure, or a NULL pointer if
       an error occurs or the end of the file is reached.

FILES top

       /etc/services
              services database file

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

SEE ALSO top

       getnetent(3), getprotoent(3), getservent_r(3), services(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-19                       GETSERVENT(3)


getspnam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETSPNAM(3)                  Linux Programmer's Manual                 GETSPNAM(3)

NAME top

       getspnam,  getspnam_r, getspent, getspent_r, setspent, endspent, fgetspent,
       fgetspent_r, sgetspent, sgetspent_r,  putspent,  lckpwdf,  ulckpwdf  -  get
       shadow password file entry

SYNOPSIS top

       /* General shadow password file API */
       #include <shadow.h>

       struct spwd *getspnam(const char *name);

       struct spwd *getspent(void);

       void setspent(void);

       void endspent(void);

       struct spwd *fgetspent(FILE *fp);

       struct spwd *sgetspent(const char *s);

       int putspent(struct spwd *p, FILE *fp);

       int lckpwdf(void);

       int ulckpwdf(void);

       /* GNU extension */
       #include <shadow.h>

       int getspent_r(struct spwd *spbuf,
               char *buf, size_t buflen, struct spwd **spbufp);

       int getspnam_r(const char *name, struct spwd *spbuf,
               char *buf, size_t buflen, struct spwd **spbufp);

       int fgetspent_r(FILE *fp, struct spwd *spbuf,
               char *buf, size_t buflen, struct spwd **spbufp);

       int sgetspent_r(const char *s, struct spwd *spbuf,
               char *buf, size_t buflen, struct spwd **spbufp);

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

       getspent_r(), getspnam_r(), fgetspent_r(), sgetspent_r():
           _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       Long ago it was considered safe to have encrypted passwords openly visible
       in the password file.  When computers got faster and people got more
       security-conscious, this was no longer acceptable.  Julianne Frances Haugh
       implemented the shadow password suite that keeps the encrypted passwords in
       the shadow password database (e.g., the local shadow password file
       /etc/shadow, NIS, and LDAP), readable only by root.

       The functions described below resemble those for the traditional password
       database (e.g., see getpwnam(3) and getpwent(3)).

       The getspnam() function returns a pointer to a structure containing the
       broken-out fields of the record in the shadow password database that
       matches the username name.

       The getspent() function returns a pointer to the next entry in the shadow
       password database.  The position in the input stream is initialized by
       setspent().  When done reading, the program may call endspent() so that
       resources can be deallocated.

       The fgetspent() function is similar to getspent() but uses the supplied
       stream instead of the one implicitly opened by setspent().

       The sgetspent() function parses the supplied string s into a struct spwd.

       The putspent() function writes the contents of the supplied struct spwd *p
       as a text line in the shadow password file format to the stream fp.  String
       entries with value NULL and numerical entries with value -1 are written as
       an empty string.

       The lckpwdf() function is intended to protect against multiple simultaneous
       accesses of the shadow password database.  It tries to acquire a lock, and
       returns 0 on success, or -1 on failure (lock not obtained within 15
       seconds).  The ulckpwdf() function releases the lock again.  Note that
       there is no protection against direct access of the shadow password file.
       Only programs that use lckpwdf() will notice the lock.

       These were the functions that formed the original shadow API.  They are
       widely available.

Reentrant versions

       Analogous to the reentrant functions for the password database, glibc also
       has reentrant functions for the shadow password database.  The getspnam_r()
       function is like getspnam() but stores the retrieved shadow password
       structure in the space pointed to by spbuf.  This shadow password structure
       contains pointers to strings, and these strings are stored in the buffer
       buf of size buflen.  A pointer to the result (in case of success) or NULL
       (in case no entry was found or an error occurred) is stored in *spbufp.

       The functions getspent_r(), fgetspent_r(), and sgetspent_r() are similarly
       analogous to their nonreentrant counterparts.

       Some non-glibc systems also have functions with these names, often with
       different prototypes.

Structure

       The shadow password structure is defined in <shadow.h> as follows:

           struct spwd {
               char *sp_namp;     /* Login name */
               char *sp_pwdp;     /* Encrypted password */
               long  sp_lstchg;   /* Date of last change (measured
                                     in days since 1970-01-01 00:00:00 +0000 (UTC)) */
               long  sp_min;      /* Min # of days between changes */
               long  sp_max;      /* Max # of days between changes */
               long  sp_warn;     /* # of days before password expires
                                     to warn user to change it */
               long  sp_inact;    /* # of days after password expires
                                     until account is disabled */
               long  sp_expire;   /* Date when account expires (measured
                                     in days since 1970-01-01 00:00:00 +0000 (UTC)) */
               unsigned long sp_flag;  /* Reserved */
           };

RETURN VALUE top

       The functions that return a pointer return NULL if no more entries are
       available or if an error occurs during processing.  The functions which
       have int as the return value return 0 for success and -1 for failure.

       For the nonreentrant functions, the return value may point to static area,
       and may be overwritten by subsequent calls to these functions.

       The reentrant functions return zero on success.  In case of error, an error
       number is returned.

ERRORS top

       ERANGE Supplied buffer is too small.

FILES top

       /etc/shadow
              local shadow password database file

       /etc/.pwd.lock
              lock file

       The include file <paths.h> defines the constant _PATH_SHADOW to the
       pathname of the shadow password file.

CONFORMING TO top

       The shadow password database and its associated API are not specified in
       POSIX.1-2001.  However, many other systems provide a similar API.

SEE ALSO top

       getgrnam(3), getpwnam(3), getpwnam_r(3), shadow(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-02-25                         GETSPNAM(3)


getttyent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETTTYENT(3)                 Linux Programmer's Manual                GETTTYENT(3)

NAME top

       getttyent, getttynam, setttyent, endttyent - get ttys file entry

SYNOPSIS top

       #include <ttyent.h>

       struct ttyent *getttyent(void);

       struct ttyent *getttynam(const char *name);

       int setttyent(void);

       int endttyent(void);

DESCRIPTION top

       These functions provide an interface to the file _PATH_TTYS (e.g.,
       /etc/ttys).

       The function setttyent() opens the file or rewinds it if already open.

       The function endttyent() closes the file.

       The function getttynam() searches for a given ttyname in the file.  It
       returns a pointer to a ttyent structure (description below).

       The function getttyent() opens the file _PATH_TTYS (if necessary) and
       returns the first entry.  If the file is already open, the next entry.  The
       ttyent structure has the form:

           struct ttyent {
               char *ty_name;     /* terminal device name */
               char *ty_getty;    /* command to execute, usually getty */
               char *ty_type;     /* terminal type for termcap */
               int   ty_status;   /* status flags */
               char *ty_window;   /* command to start up window manager */
               char *ty_comment;  /* comment field */
           };

       ty_status can be:

       #define TTY_ON     0x01  /* enable logins (start ty_getty program) */
       #define TTY_SECURE 0x02  /* allow UID 0 to login */

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs, and perhaps other systems.

NOTES top

       Under Linux the file /etc/ttys, and the functions described above, are not
       used.

SEE ALSO top

       ttyname(3), ttyslot(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2002-07-18                        GETTTYENT(3)


getusershell(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETUSERSHELL(3)              Linux Programmer's Manual             GETUSERSHELL(3)

NAME top

       getusershell, setusershell, endusershell - get permitted user shells

SYNOPSIS top

       #include <unistd.h>

       char *getusershell(void);

       void setusershell(void);

       void endusershell(void);

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

       getusershell(), setusershell(), endusershell():
           _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       The getusershell() function returns the next line from the file
       /etc/shells, opening the file if necessary.  The line should contain the
       pathname of a valid user shell.  If /etc/shells does not exist or is
       unreadable, getusershell() behaves as if  /bin/sh and /bin/csh were listed
       in the file.

       The setusershell() function rewinds /etc/shells.

       The endusershell() function closes /etc/shells.

RETURN VALUE top

       The getusershell() function returns a NULL pointer on end-of-file.

FILES top

       /etc/shells

CONFORMING TO top

       4.3BSD.

SEE ALSO top

       shells(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                     GETUSERSHELL(3)


getutent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETUTENT(3)                  Linux Programmer's Manual                 GETUTENT(3)

NAME top

       getutent,  getutid,  getutline,  pututline,  setutent, endutent, utmpname -
       access utmp file entries

SYNOPSIS top

       #include <utmp.h>

       struct utmp *getutent(void);
       struct utmp *getutid(struct utmp *ut);
       struct utmp *getutline(struct utmp *ut);

       struct utmp *pututline(struct utmp *ut);

       void setutent(void);
       void endutent(void);

       int utmpname(const char *file);

DESCRIPTION top

       New applications should use the POSIX.1-specified "utmpx" versions of these
       functions; see CONFORMING TO.

       utmpname() sets the name of the utmp-format file for the other utmp
       functions to access.  If utmpname() is not used to set the filename before
       the other functions are used, they assume _PATH_UTMP, as defined in
       <paths.h>.

       setutent() rewinds the file pointer to the beginning of the utmp file.  It
       is generally a good idea to call it before any of the other functions.

       endutent() closes the utmp file.  It should be called when the user code is
       done accessing the file with the other functions.

       getutent() reads a line from the current file position in the utmp file.
       It returns a pointer to a structure containing the fields of the line.  The
       definition of this structure is shown in utmp(5).

       getutid() searches forward from the current file position in the utmp file
       based upon ut.  If ut->ut_type is one of RUN_LVL, BOOT_TIME, NEW_TIME, or
       OLD_TIME, getutid() will find the first entry whose ut_type field matches
       ut->ut_type.  If ut->ut_type is one of INIT_PROCESS, LOGIN_PROCESS,
       USER_PROCESS, or DEAD_PROCESS, getutid() will find the first entry whose
       ut_id field matches ut->ut_id.

       getutline() searches forward from the current file position in the utmp
       file.  It scans entries whose ut_type is USER_PROCESS or LOGIN_PROCESS and
       returns the first one whose ut_line field matches ut->ut_line.

       pututline() writes the utmp structure ut into the utmp file.  It uses
       getutid() to search for the proper place in the file to insert the new
       entry.  If it cannot find an appropriate slot for ut, pututline() will
       append the new entry to the end of the file.

RETURN VALUE top

       getutent(), getutid(), and getutline() return a pointer to a struct utmp on
       success, and NULL on failure (which includes the "record not found" case).
       This struct utmp is allocated in static storage, and may be overwritten by
       subsequent calls.

       On success pututline() returns ut; on failure, it returns NULL.

       utmpname() returns 0 if the new name was successfully stored, or -1 on
       failure.

ERRORS top

       ENOMEM Out of memory.

       ESRCH  Record not found.

       setutent(), pututline(), and the getut* () functions can also fail for the
       reasons described in open(2).

FILES top

       /var/run/utmp  database of currently logged-in users
       /var/log/wtmp  database of past user logins

CONFORMING TO top

       XPG2, SVr4.

       In XPG2 and SVID 2 the function pututline() is documented to return void,
       and that is what it does on many systems (AIX, HP-UX, Linux libc5).  HP-UX
       introduces a new function _pututline() with the prototype given above for
       pututline() (also found in Linux libc5).

       All these functions are obsolete now on non-Linux systems.  POSIX.1-2001,
       following SUSv1, does not have any of these functions, but instead uses

       #include <utmpx.h>

       struct utmpx *getutxent(void);
       struct utmpx *getutxid(const struct utmpx *);
       struct utmpx *getutxline(const struct utmpx *);
       struct utmpx *pututxline(const struct utmpx *);
       void setutxent(void);
       void endutxent(void);

       These functions are provided by glibc, and perform the same task as their
       equivalents without the "x", but use struct utmpx, defined on Linux to be
       the same as struct utmp.  For completeness, glibc also provides
       utmpxname(), although this function is not specified by POSIX.1.

       On some other systems, the utmpx structure is a superset of the utmp
       structure, with additional fields, and larger versions of the existing
       fields, and parallel files are maintained, often /var/*/utmpx and
       /var/*/wtmpx.

       Linux glibc on the other hand does not use a parallel utmpx file since its
       utmp structure is already large enough.  The "x" functions listed above are
       just aliases for their counterparts without the "x" (e.g., getutxent() is
       an alias for getutent()).

NOTES top

Glibc Notes

       The above functions are not thread-safe.  Glibc adds reentrant versions

       #define _GNU_SOURCE    /* or _SVID_SOURCE or _BSD_SOURCE;
                                 see feature_test_macros(7) */
       #include <utmp.h>

       int getutent_r(struct utmp *ubuf, struct utmp **ubufp);

       int getutid_r(struct utmp *ut,
                     struct utmp *ubuf, struct utmp **ubufp);

       int getutline_r(struct utmp *ut,
                       struct utmp *ubuf, struct utmp **ubufp);

       These functions are GNU extensions, analogs of the functions of the same
       name without the _r suffix.  The ubuf argument gives these functions a
       place to store their result.  On success they return 0, and a pointer to
       the result is written in *ubufp.  On error these functions return -1.
       There are no utmpx equivalents of the above functions.  (POSIX.1 does not
       specify such functions.)

EXAMPLE          top
       The following example adds and removes a utmp record, assuming it is run
       from within a pseudo terminal.  For usage in a real application, you should
       check the return values of getpwuid(3) and ttyname(3).

       #include <string.h>
       #include <stdlib.h>
       #include <pwd.h>
       #include <unistd.h>
       #include <utmp.h>

       int
       main(int argc, char *argv[])
       {
           struct utmp entry;

           system("echo before adding entry:;who");

           entry.ut_type = USER_PROCESS;
           entry.ut_pid = getpid();
           strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
           /* only correct for ptys named /dev/tty[pqr][0-9a-z] */
           strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
           time(&entry.ut_time);
           strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
           memset(entry.ut_host, 0, UT_HOSTSIZE);
           entry.ut_addr = 0;
           setutent();
           pututline(&entry);

           system("echo after adding entry:;who");

           entry.ut_type = DEAD_PROCESS;
           memset(entry.ut_line, 0, UT_LINESIZE);
           entry.ut_time = 0;
           memset(entry.ut_user, 0, UT_NAMESIZE);
           setutent();
           pututline(&entry);

           system("echo after removing entry:;who");

           endutent();
           exit(EXIT_SUCCESS);
       }

SEE ALSO          top
       getutmp(3), utmp(5)

COLOPHON          top
       This page is part of release 3.45 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/.

                                    2008-06-29                         GETUTENT(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


environ(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ENVIRON(7)                   Linux Programmer's Manual                  ENVIRON(7)

NAME top

       environ - user environment

SYNOPSIS top

       extern char **environ;

DESCRIPTION top

       The variable environ points to an array of pointers to strings called the
       "environment".  The last pointer in this array has the value NULL.  (This
       variable must be declared in the user program, but is declared in the
       header file <unistd.h> in case the header files came from libc4 or libc5,
       and in case they came from glibc and _GNU_SOURCE was defined.)  This array
       of strings is made available to the process by the exec(3) call that
       started the process.

       By convention the strings in environ have the form "name=value".  Common
       examples are:

       USER   The name of the logged-in user (used by some BSD-derived programs).

       LOGNAME
              The name of the logged-in user (used by some System-V derived
              programs).

       HOME   A user's login directory, set by login(1) from the password file
              passwd(5).

       LANG   The name of a locale to use for locale categories when not
              overridden by LC_ALL or more specific environment variables like
              LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME,
              cf.  locale(5).

       PATH   The sequence of directory prefixes that sh(1) and many other
              programs apply in searching for a file known by an incomplete
              pathname.  The prefixes are separated by ':'.  (Similarly one has
              CDPATH used by some shells to find the target of a change directory
              command, MANPATH used by man(1) to find manual pages, and so on)

       PWD    The current working directory.  Set by some shells.

       SHELL  The pathname of the user's login shell.

       TERM   The terminal type for which output is to be prepared.

       PAGER  The user's preferred utility to display text files.

       EDITOR/VISUAL
              The user's preferred utility to edit text files.

       Further names may be placed in the environment by the export command and
       "name=value" in sh(1), or by the setenv command if you use csh(1).
       Arguments may also be placed in the environment at the point of an exec(3).
       A C program can manipulate its environment using the functions getenv(3),
       putenv(3), setenv(3), and unsetenv(3).

       Note that the behavior of many programs and library routines is influenced
       by the presence or value of certain environment variables.  A random
       collection:

       The variables LANG, LANGUAGE, NLSPATH, LOCPATH, LC_ALL, LC_MESSAGES, etc.
       influence locale handling, cf.  locale(5).

       TMPDIR influences the path prefix of names created by tmpnam(3) and other
       routines, the temporary directory used by sort(1) and other programs, etc.

       LD_LIBRARY_PATH, LD_PRELOAD and other LD_* variables influence the behavior
       of the dynamic loader/linker.

       POSIXLY_CORRECT makes certain programs and library routines follow the
       prescriptions of POSIX.

       The behavior of malloc(3) is influenced by MALLOC_* variables.

       The variable HOSTALIASES gives the name of a file containing aliases to be
       used with gethostbyname(3).

       TZ and TZDIR give timezone information used by tzset(3) and through that by
       functions like ctime(3), localtime(3), mktime(3), strftime(3).  See also
       tzselect(8).

       TERMCAP gives information on how to address a given terminal (or gives the
       name of a file containing such information).

       COLUMNS and LINES tell applications about the window size, possibly
       overriding the actual size.

       PRINTER or LPDEST may specify the desired printer to use.  See lpr(1).

       Etc.

BUGS top

       Clearly there is a security risk here.  Many a system command has been
       tricked into mischief by a user who specified unusual values for IFS or
       LD_LIBRARY_PATH.

       There is also the risk of name space pollution.  Programs like make and
       autoconf allow overriding of default utility names from the environment
       with similarly named variables in all caps.  Thus one uses CC to select the
       desired C compiler (and similarly MAKE, AR, AS, FC, LD, LEX, RM, YACC,
       etc.).  However, in some traditional uses such an environment variable
       gives options for the program instead of a pathname.  Thus, one has MORE,
       LESS, and GZIP.  Such usage is considered mistaken, and to be avoided in
       new programs.  The authors of gzip should consider renaming their option to
       GZIP_OPT.

SEE ALSO top

       bash(1), csh(1), login(1), sh(1), tcsh(1), execve(2), clearenv(3), exec(3),
       getenv(3), putenv(3), setenv(3), unsetenv(3), locale(5)

COLOPHON top

       This page is part of release 3.45 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                               2009-07-25                          ENVIRON(7)


envz_add(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

ENVZ_ADD(3)                  Linux Programmer's Manual                 ENVZ_ADD(3)

NAME top

       envz_add, envz_entry, envz_get, envz_merge, envz_remove, envz_strip - envi-
       ronment string support

SYNOPSIS top

       #include <envz.h>

       error_t envz_add(char **envz, size_t *envz_len,
                    const char *name, const char *value);

       char *envz_entry(const char *envz, size_t *envz_len, const char *name);

       char *envz_get(const char *envz, size_t *envz_len, const char *name);

       error_t envz_merge(char **envz, size_t *envz_len,
                    const char *envz2, size_t envz2_len, int override);

       void envz_remove(char **envz, size_t *envz_len, const char *name);

       void envz_strip(char **envz, size_t *envz_len);

DESCRIPTION top

       These functions are glibc-specific.

       An argz vector is a pointer to a character buffer together with a length,
       see argz_add(3).  An envz vector is a special argz vector, namely one where
       the strings have the form "name=value".  Everything after the first '=' is
       considered to be the value.  If there is no '=', the value is taken to be
       NULL.  (While the value in case of a trailing '=' is the empty string "".)

       These functions are for handling envz vectors.

       envz_add() adds the string "name=value" (in case value is non-NULL) or
       "name" (in case value is NULL) to the envz vector (*envz, *envz_len) and
       updates *envz and *envz_len.  If an entry with the same name existed, it is
       removed.

       envz_entry() looks for name in the envz vector (envz, envz_len) and returns
       the entry if found, or NULL if not.

       envz_get() looks for name in the envz vector (envz, envz_len) and returns
       the value if found, or NULL if not.  (Note that the value can also be NULL,
       namely when there is an entry for name without '=' sign.)

       envz_merge() adds each entry in envz2 to *envz, as if with envz_add().  If
       override is true, then values in envz2 will supersede those with the same
       name in *envz, otherwise not.

       envz_remove() removes the entry for name from (*envz, *envz_len) if there
       was one.

       envz_strip() removes all entries with value NULL.

RETURN VALUE top

       All envz functions that do memory allocation have a return type of error_t,
       and return 0 for success, and ENOMEM if an allocation error occurs.

CONFORMING TO top

       These functions are a GNU extension.  Handle with care.

EXAMPLE top

       #include <stdio.h>
       #include <stdlib.h>
       #include <envz.h>

       int
       main(int argc, char *argv[], char *envp[])
       {
           int i, e_len = 0;
           char *str;

           for (i = 0; envp[i] != NULL; i++)
               e_len += strlen(envp[i]) + 1;

           str = envz_entry(*envp, e_len, "HOME");
           printf("%s\n", str);
           str = envz_get(*envp, e_len, "HOME");
           printf("%s\n", str);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       argz_add(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-05-18                         ENVZ_ADD(3)


epoll(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

EPOLL(7)                     Linux Programmer's Manual                    EPOLL(7)

NAME top

       epoll - I/O event notification facility

SYNOPSIS top

       #include <sys/epoll.h>

DESCRIPTION top

       The epoll API performs a similar task to poll(2): monitoring multiple file
       descriptors to see if I/O is possible on any of them.  The epoll API can be
       used either as an edge-triggered or a level-triggered interface and scales
       well to large numbers of watched file descriptors.  The following system
       calls are provided to create and manage an epoll instance:

       *  epoll_create(2) creates an epoll instance and returns a file descriptor
          referring to that instance.  (The more recent epoll_create1(2) extends
          the functionality of epoll_create(2).)

       *  Interest in particular file descriptors is then registered via
          epoll_ctl(2).  The set of file descriptors currently registered on an
          epoll instance is sometimes called an epoll set.

       *  epoll_wait(2) waits for I/O events, blocking the calling thread if no
          events are currently available.

Level-Triggered and Edge-Triggered

       The epoll event distribution interface is able to behave both as edge-
       triggered (ET) and as level-triggered (LT).  The difference between the two
       mechanisms can be described as follows.  Suppose that this scenario
       happens:

       1. The file descriptor that represents the read side of a pipe (rfd) is
          registered on the epoll instance.

       2. A pipe writer writes 2 kB of data on the write side of the pipe.

       3. A call to epoll_wait(2) is done that will return rfd as a ready file
          descriptor.

       4. The pipe reader reads 1 kB of data from rfd.

       5. A call to epoll_wait(2) is done.

       If the rfd file descriptor has been added to the epoll interface using the
       EPOLLET (edge-triggered) flag, the call to epoll_wait(2) done in step 5
       will probably hang despite the available data still present in the file
       input buffer; meanwhile the remote peer might be expecting a response based
       on the data it already sent.  The reason for this is that edge-triggered
       mode only delivers events when changes occur on the monitored file
       descriptor.  So, in step 5 the caller might end up waiting for some data
       that is already present inside the input buffer.  In the above example, an
       event on rfd will be generated because of the write done in 2 and the event
       is consumed in 3.  Since the read operation done in 4 does not consume the
       whole buffer data, the call to epoll_wait(2) done in step 5 might block
       indefinitely.

       An application that employs the EPOLLET flag should use nonblocking file
       descriptors to avoid having a blocking read or write starve a task that is
       handling multiple file descriptors.  The suggested way to use epoll as an
       edge-triggered (EPOLLET) interface is as follows:

              i   with nonblocking file descriptors; and

              ii  by waiting for an event only after read(2) or write(2) return
                  EAGAIN.

       By contrast, when used as a level-triggered interface (the default, when
       EPOLLET is not specified), epoll is simply a faster poll(2), and can be
       used wherever the latter is used since it shares the same semantics.

       Since even with edge-triggered epoll, multiple events can be generated upon
       receipt of multiple chunks of data, the caller has the option to specify
       the EPOLLONESHOT flag, to tell epoll to disable the associated file
       descriptor after the receipt of an event with epoll_wait(2).  When the
       EPOLLONESHOT flag is specified, it is the caller's responsibility to rearm
       the file descriptor using epoll_ctl(2) with EPOLL_CTL_MOD.

/proc interfaces

       The following interfaces can be used to limit the amount of kernel memory
       consumed by epoll:

       /proc/sys/fs/epoll/max_user_watches (since Linux 2.6.28)
              This specifies a limit on the total number of file descriptors that
              a user can register across all epoll instances on the system.  The
              limit is per real user ID.  Each registered file descriptor costs
              roughly 90 bytes on a 32-bit kernel, and roughly 160 bytes on a
              64-bit kernel.  Currently, the default value for max_user_watches is
              1/25 (4%) of the available low memory, divided by the registration
              cost in bytes.

Example for Suggested Usage

       While the usage of epoll when employed as a level-triggered interface does
       have the same semantics as poll(2), the edge-triggered usage requires more
       clarification to avoid stalls in the application event loop.  In this
       example, listener is a nonblocking socket on which listen(2) has been
       called.  The function do_use_fd() uses the new ready file descriptor until
       EAGAIN is returned by either read(2) or write(2).  An event-driven state
       machine application should, after having received EAGAIN, record its
       current state so that at the next call to do_use_fd() it will continue to
       read(2) or write(2) from where it stopped before.

           #define MAX_EVENTS 10
           struct epoll_event ev, events[MAX_EVENTS];
           int listen_sock, conn_sock, nfds, epollfd;

           /* Set up listening socket, 'listen_sock' (socket(),
              bind(), listen()) */

           epollfd = epoll_create(10);
           if (epollfd == -1) {
               perror("epoll_create");
               exit(EXIT_FAILURE);
           }

           ev.events = EPOLLIN;
           ev.data.fd = listen_sock;
           if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {
               perror("epoll_ctl: listen_sock");
               exit(EXIT_FAILURE);
           }

           for (;;) {
               nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);
               if (nfds == -1) {
                   perror("epoll_pwait");
                   exit(EXIT_FAILURE);
               }

               for (n = 0; n < nfds; ++n) {
                   if (events[n].data.fd == listen_sock) {
                       conn_sock = accept(listen_sock,
                                       (struct sockaddr *) &local, &addrlen);
                       if (conn_sock == -1) {
                           perror("accept");
                           exit(EXIT_FAILURE);
                       }
                       setnonblocking(conn_sock);
                       ev.events = EPOLLIN | EPOLLET;
                       ev.data.fd = conn_sock;
                       if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,
                                   &ev) == -1) {
                           perror("epoll_ctl: conn_sock");
                           exit(EXIT_FAILURE);
                       }
                   } else {
                       do_use_fd(events[n].data.fd);
                   }
               }
           }

       When used as an edge-triggered interface, for performance reasons, it is
       possible to add the file descriptor inside the epoll interface
       (EPOLL_CTL_ADD) once by specifying (EPOLLIN|EPOLLOUT).  This allows you to
       avoid continuously switching between EPOLLIN and EPOLLOUT calling
       epoll_ctl(2) with EPOLL_CTL_MOD.

Questions and Answers

       Q0  What is the key used to distinguish the file descriptors registered in
           an epoll set?

       A0  The key is the combination of the file descriptor number and the open
           file description (also known as an "open file handle", the kernel's
           internal representation of an open file).

       Q1  What happens if you register the same file descriptor on an epoll
           instance twice?

       A1  You will probably get EEXIST.  However, it is possible to add a
           duplicate (dup(2), dup2(2), fcntl(2) F_DUPFD) descriptor to the same
           epoll instance.  This can be a useful technique for filtering events,
           if the duplicate file descriptors are registered with different events
           masks.

       Q2  Can two epoll instances wait for the same file descriptor?  If so, are
           events reported to both epoll file descriptors?

       A2  Yes, and events would be reported to both.  However, careful
           programming may be needed to do this correctly.

       Q3  Is the epoll file descriptor itself poll/epoll/selectable?

       A3  Yes.  If an epoll file descriptor has events waiting then it will
           indicate as being readable.

       Q4  What happens if one attempts to put an epoll file descriptor into its
           own file descriptor set?

       A4  The epoll_ctl(2) call will fail (EINVAL).  However, you can add an
           epoll file descriptor inside another epoll file descriptor set.

       Q5  Can I send an epoll file descriptor over a UNIX domain socket to
           another process?

       A5  Yes, but it does not make sense to do this, since the receiving process
           would not have copies of the file descriptors in the epoll set.

       Q6  Will closing a file descriptor cause it to be removed from all epoll
           sets automatically?

       A6  Yes, but be aware of the following point.  A file descriptor is a
           reference to an open file description (see open(2)).  Whenever a
           descriptor is duplicated via dup(2), dup2(2), fcntl(2) F_DUPFD, or
           fork(2), a new file descriptor referring to the same open file
           description is created.  An open file description continues to exist
           until all file descriptors referring to it have been closed.  A file
           descriptor is removed from an epoll set only after all the file
           descriptors referring to the underlying open file description have been
           closed (or before if the descriptor is explicitly removed using
           epoll_ctl(2) EPOLL_CTL_DEL).  This means that even after a file
           descriptor that is part of an epoll set has been closed, events may be
           reported for that file descriptor if other file descriptors referring
           to the same underlying file description remain open.

       Q7  If more than one event occurs between epoll_wait(2) calls, are they
           combined or reported separately?

       A7  They will be combined.

       Q8  Does an operation on a file descriptor affect the already collected but
           not yet reported events?

       A8  You can do two operations on an existing file descriptor.  Remove would
           be meaningless for this case.  Modify will reread available I/O.

       Q9  Do I need to continuously read/write a file descriptor until EAGAIN
           when using the EPOLLET flag (edge-triggered behavior) ?

       A9  Receiving an event from epoll_wait(2) should suggest to you that such
           file descriptor is ready for the requested I/O operation.  You must
           consider it ready until the next (nonblocking) read/write yields
           EAGAIN.  When and how you will use the file descriptor is entirely up
           to you.

           For packet/token-oriented files (e.g., datagram socket, terminal in
           canonical mode), the only way to detect the end of the read/write I/O
           space is to continue to read/write until EAGAIN.

           For stream-oriented files (e.g., pipe, FIFO, stream socket), the
           condition that the read/write I/O space is exhausted can also be
           detected by checking the amount of data read from / written to the
           target file descriptor.  For example, if you call read(2) by asking to
           read a certain amount of data and read(2) returns a lower number of
           bytes, you can be sure of having exhausted the read I/O space for the
           file descriptor.  The same is true when writing using write(2).  (Avoid
           this latter technique if you cannot guarantee that the monitored file
           descriptor always refers to a stream-oriented file.)

Possible Pitfalls and Ways to Avoid Them

       o Starvation (edge-triggered)

       If there is a large amount of I/O space, it is possible that by trying to
       drain it the other files will not get processed causing starvation.  (This
       problem is not specific to epoll.)

       The solution is to maintain a ready list and mark the file descriptor as
       ready in its associated data structure, thereby allowing the application to
       remember which files need to be processed but still round robin amongst all
       the ready files.  This also supports ignoring subsequent events you receive
       for file descriptors that are already ready.

       o If using an event cache...

       If you use an event cache or store all the file descriptors returned from
       epoll_wait(2), then make sure to provide a way to mark its closure
       dynamically (i.e., caused by a previous event's processing).  Suppose you
       receive 100 events from epoll_wait(2), and in event #47 a condition causes
       event #13 to be closed.  If you remove the structure and close(2) the file
       descriptor for event #13, then your event cache might still say there are
       events waiting for that file descriptor causing confusion.

       One solution for this is to call, during the processing of event 47,
       epoll_ctl(EPOLL_CTL_DEL) to delete file descriptor 13 and close(2), then
       mark its associated data structure as removed and link it to a cleanup
       list.  If you find another event for file descriptor 13 in your batch
       processing, you will discover the file descriptor had been previously
       removed and there will be no confusion.

VERSIONS top

       The epoll API was introduced in Linux kernel 2.5.44.  Support was added to
       glibc in version 2.3.2.

CONFORMING TO top

       The epoll API is Linux-specific.  Some other systems provide similar
       mechanisms, for example, FreeBSD has kqueue, and Solaris has /dev/poll.

SEE ALSO top

       epoll_create(2), epoll_create1(2), epoll_ctl(2), epoll_wait(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-17                            EPOLL(7)


epoll_create(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

EPOLL_CREATE(2)              Linux Programmer's Manual             EPOLL_CREATE(2)

NAME top

       epoll_create, epoll_create1 - open an epoll file descriptor

SYNOPSIS top

       #include <sys/epoll.h>

       int epoll_create(int size);
       int epoll_create1(int flags);

DESCRIPTION top

       epoll_create() creates an epoll(7) instance.  Since Linux 2.6.8, the size
       argument is ignored, but must be greater than zero; see NOTES below.

       epoll_create() returns a file descriptor referring to the new epoll
       instance.  This file descriptor is used for all the subsequent calls to the
       epoll interface.  When no longer required, the file descriptor returned by
       epoll_create() should be closed by using close(2).  When all file
       descriptors referring to an epoll instance have been closed, the kernel
       destroys the instance and releases the associated resources for reuse.

epoll_create1()

       If flags is 0, then, other than the fact that the obsolete size argument is
       dropped, epoll_create1() is the same as epoll_create().  The following
       value can be included in flags to obtain different behavior:

       EPOLL_CLOEXEC
              Set the close-on-exec (FD_CLOEXEC) flag on the new file descriptor.
              See the description of the O_CLOEXEC flag in open(2) for reasons why
              this may be useful.

RETURN VALUE top

       On success, these system calls return a nonnegative file descriptor.  On
       error, -1 is returned, and errno is set to indicate the error.

ERRORS top

       EINVAL size is not positive.

       EINVAL (epoll_create1()) Invalid value specified in flags.

       EMFILE The per-user limit on the number of epoll instances imposed by
              /proc/sys/fs/epoll/max_user_instances was encountered.  See epoll(7)
              for further details.

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

       ENOMEM There was insufficient memory to create the kernel object.

VERSIONS top

       epoll_create() was added to the kernel in version 2.6.  Library support is
       provided in glibc starting with version 2.3.2.

       epoll_create1() was added to the kernel in version 2.6.27.  Library support
       is provided in glibc starting with version 2.9.

CONFORMING TO top

       epoll_create() is Linux-specific.

NOTES top

       In the initial epoll_create() implementation, the size argument informed
       the kernel of the number of file descriptors that the caller expected to
       add to the epoll instance.  The kernel used this information as a hint for
       the amount of space to initially allocate in internal data structures
       describing events.  (If necessary, the kernel would allocate more space if
       the caller's usage exceeded the hint given in size.)  Nowadays, this hint
       is no longer required (the kernel dynamically sizes the required data
       structures without needing the hint), but size must still be greater than
       zero, in order to ensure backward compatibility when new epoll applications
       are run on older kernels.

SEE ALSO top

       close(2), epoll_ctl(2), epoll_wait(2), epoll(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-15                     EPOLL_CREATE(2)


epoll_ctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

EPOLL_CTL(2)                 Linux Programmer's Manual                EPOLL_CTL(2)

NAME top

       epoll_ctl - control interface for an epoll descriptor

SYNOPSIS top

       #include <sys/epoll.h>

       int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

DESCRIPTION top

       This system call performs control operations on the epoll(7) instance
       referred to by the file descriptor epfd.  It requests that the operation op
       be performed for the target file descriptor, fd.

       Valid values for the op argument are :

       EPOLL_CTL_ADD
              Register the target file descriptor fd on the epoll instance
              referred to by the file descriptor epfd and associate the event
              event with the internal file linked to fd.

       EPOLL_CTL_MOD
              Change the event event associated with the target file descriptor
              fd.

       EPOLL_CTL_DEL
              Remove (deregister) the target file descriptor fd from the epoll
              instance referred to by epfd.  The event is ignored and can be NULL
              (but see BUGS below).

       The event argument describes the object linked to the file descriptor fd.
       The struct epoll_event is defined as :

           typedef union epoll_data {
               void        *ptr;
               int          fd;
               uint32_t     u32;
               uint64_t     u64;
           } epoll_data_t;

           struct epoll_event {
               uint32_t     events;      /* Epoll events */
               epoll_data_t data;        /* User data variable */
           };

       The events member is a bit set composed using the following available event
       types:

       EPOLLIN
              The associated file is available for read(2) operations.

       EPOLLOUT
              The associated file is available for write(2) operations.

       EPOLLRDHUP (since Linux 2.6.17)
              Stream socket peer closed connection, or shut down writing half of
              connection.  (This flag is especially useful for writing simple code
              to detect peer shutdown when using Edge Triggered monitoring.)

       EPOLLPRI
              There is urgent data available for read(2) operations.

       EPOLLERR
              Error condition happened on the associated file descriptor.
              epoll_wait(2) will always wait for this event; it is not necessary
              to set it in events.

       EPOLLHUP
              Hang up happened on the associated file descriptor.  epoll_wait(2)
              will always wait for this event; it is not necessary to set it in
              events.

       EPOLLET
              Sets the Edge Triggered behavior for the associated file descriptor.
              The default behavior for epoll is Level Triggered.  See epoll(7) for
              more detailed information about Edge and Level Triggered event
              distribution architectures.

       EPOLLONESHOT (since Linux 2.6.2)
              Sets the one-shot behavior for the associated file descriptor.  This
              means that after an event is pulled out with epoll_wait(2) the
              associated file descriptor is internally disabled and no other
              events will be reported by the epoll interface.  The user must call
              epoll_ctl() with EPOLL_CTL_MOD to rearm the file descriptor with a
              new event mask.

RETURN VALUE top

       When successful, epoll_ctl() returns zero.  When an error occurs,
       epoll_ctl() returns -1 and errno is set appropriately.

ERRORS top

       EBADF  epfd or fd is not a valid file descriptor.

       EEXIST op was EPOLL_CTL_ADD, and the supplied file descriptor fd is already
              registered with this epoll instance.

       EINVAL epfd is not an epoll file descriptor, or fd is the same as epfd, or
              the requested operation op is not supported by this interface.

       ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not registered with
              this epoll instance.

       ENOMEM There was insufficient memory to handle the requested op control
              operation.

       ENOSPC The limit imposed by /proc/sys/fs/epoll/max_user_watches was
              encountered while trying to register (EPOLL_CTL_ADD) a new file
              descriptor on an epoll instance.  See epoll(7) for further details.

       EPERM  The target file fd does not support epoll.

VERSIONS top

       epoll_ctl() was added to the kernel in version 2.6.

CONFORMING TO top

       epoll_ctl() is Linux-specific.  Library support is provided in glibc
       starting with version 2.3.2.

NOTES top

       The epoll interface supports all file descriptors that support poll(2).

BUGS top

       In kernel versions before 2.6.9, the EPOLL_CTL_DEL operation required a
       non-NULL pointer in event, even though this argument is ignored.  Since
       Linux 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL.
       Applications that need to be portable to kernels before 2.6.9 should
       specify a non-NULL pointer in event.

SEE ALSO top

       epoll_create(2), epoll_wait(2), poll(2), epoll(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-15                        EPOLL_CTL(2)


epoll_wait(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

EPOLL_WAIT(2)                Linux Programmer's Manual               EPOLL_WAIT(2)

NAME top

       epoll_wait, epoll_pwait - wait for an I/O event on an epoll file descriptor

SYNOPSIS top

       #include <sys/epoll.h>

       int epoll_wait(int epfd, struct epoll_event *events,
                      int maxevents, int timeout);
       int epoll_pwait(int epfd, struct epoll_event *events,
                      int maxevents, int timeout,
                      const sigset_t *sigmask);

DESCRIPTION top

       The epoll_wait() system call waits for events on the epoll(7) instance
       referred to by the file descriptor epfd.  The memory area pointed to by
       events will contain the events that will be available for the caller.  Up
       to maxevents are returned by epoll_wait().  The maxevents argument must be
       greater than zero.

       The timeout argument specifies the minimum number of milliseconds that
       epoll_wait() will block.  (This interval will be rounded up to the system
       clock granularity, and kernel scheduling delays mean that the blocking
       interval may overrun by a small amount.)  Specifying a timeout of -1 causes
       epoll_wait() to block indefinitely, while specifying a timeout equal to
       zero cause epoll_wait() to return immediately, even if no events are
       available.

       The struct epoll_event is defined as :

           typedef union epoll_data {
               void    *ptr;
               int      fd;
               uint32_t u32;
               uint64_t u64;
           } epoll_data_t;

           struct epoll_event {
               uint32_t     events;    /* Epoll events */
               epoll_data_t data;      /* User data variable */
           };

       The data of each returned structure will contain the same data the user set
       with an epoll_ctl(2) (EPOLL_CTL_ADD,EPOLL_CTL_MOD) while the events member
       will contain the returned event bit field.

epoll_pwait()

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

       The following epoll_pwait() call:

           ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);

       is equivalent to atomically executing the following calls:

           sigset_t origmask;

           sigprocmask(SIG_SETMASK, &sigmask, &origmask);
           ready = epoll_wait(epfd, &events, maxevents, timeout);
           sigprocmask(SIG_SETMASK, &origmask, NULL);

       The sigmask argument may be specified as NULL, in which case epoll_pwait()
       is equivalent to epoll_wait().

RETURN VALUE top

       When successful, epoll_wait() returns the number of file descriptors ready
       for the requested I/O, or zero if no file descriptor became ready during
       the requested timeout milliseconds.  When an error occurs, epoll_wait()
       returns -1 and errno is set appropriately.

ERRORS top

       EBADF  epfd is not a valid file descriptor.

       EFAULT The memory area pointed to by events is not accessible with write
              permissions.

       EINTR  The call was interrupted by a signal handler before either any of
              the requested events occurred or the timeout expired; see signal(7).

       EINVAL epfd is not an epoll file descriptor, or maxevents is less than or
              equal to zero.

VERSIONS top

       epoll_wait() was added to the kernel in version 2.6.  Library support is
       provided in glibc starting with version 2.3.2.

       epoll_pwait() was added to Linux in kernel 2.6.19.  Library support is
       provided in glibc starting with version 2.6.

CONFORMING TO top

       epoll_wait() is Linux-specific.

NOTES top

       While one thread is blocked in a call to epoll_pwait(), it is possible for
       another thread to add a file descriptor to the waited-upon epoll instance.
       If the new file descriptor becomes ready, it will cause the epoll_wait()
       call to unblock.

       For a discussion of what may happen if a file descriptor in an epoll
       instance being monitored by epoll_wait() is closed in another thread, see
       select(2).

BUGS top

       In kernels before 2.6.37, a timeout value larger than approximately
       LONG_MAX / HZ milliseconds is treated as -1 (i.e., infinity).  Thus, for
       example, on a system where the sizeof(long) is 4 and the kernel HZ value is
       1000, this means that timeouts greater than 35.79 minutes are treated as
       infinity.

SEE ALSO top

       epoll_create(2), epoll_ctl(2), epoll(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-17                       EPOLL_WAIT(2)


erf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ERF(3)                       Linux Programmer's Manual                      ERF(3)

NAME top

       erf, erff, erfl, - error function

SYNOPSIS top

       #include <math.h>

       double erf(double x);
       float erff(float x);
       long double erfl(long double x);

       Link with -lm.

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

       erf():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       erff(), erfl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The erf() function returns the error function of x, defined as

           erf(x) = 2/sqrt(pi)* integral from 0 to x of exp(-t*t) dt

RETURN VALUE top

       On success, these functions return the error function of x, a value in the
       range [-1, 1].

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity (negative infinity), +1 (-1) is returned.

       If x is subnormal, a range error occurs, and the return value is
       2*x/sqrt(pi).

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result underflow (x is subnormal)
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

       These functions do not set errno.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD.

SEE ALSO top

       cerf(3), erfc(3), exp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                              ERF(3)


erfc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ERFC(3)                      Linux Programmer's Manual                     ERFC(3)

NAME top

       erfc, erfcf, erfcl - complementary error function

SYNOPSIS top

       #include <math.h>

       double erfc(double x);
       float erfcf(float x);
       long double erfcl(long double x);

       Link with -lm.

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

       erfc():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       erfcf(), erfcl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600|| _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The erfc() function returns the complementary error function of x, that is,
       1.0 - erf(x).

RETURN VALUE top

       On success, these functions return the complementary error function of x, a
       value in the range [0,2].

       If x is a NaN, a NaN is returned.

       If x is +0 or -0, 1 is returned.

       If x is positive infinity, +0 is returned.

       If x is negative infinity, +2 is returned.

       If the function result underflows and produces an unrepresentable value,
       the return value is 0.0.

       If the function result underflows but produces a representable (i.e.,
       subnormal) value, that value is returned, and a range error occurs.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result underflow (result is subnormal)
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

       These functions do not set errno.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD.

NOTES top

       The erfc() functions are provided to avoid the loss accuracy that would
       occur for the calculation 1-erf(x) for large values of x (for which the
       value of erf(x) approaches 1).

SEE ALSO top

       cerf(3), erf(3), exp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                             ERFC(3)


err(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

ERR(3)                       Linux Programmer's Manual                      ERR(3)

NAME top

       err,  verr,  errx, verrx, warn, vwarn, warnx, vwarnx - formatted error mes-
       sages

SYNOPSIS top

       #include <err.h>

       void err(int eval, const char *fmt, ...);

       void errx(int eval, const char *fmt, ...);

       void warn(const char *fmt, ...);

       void warnx(const char *fmt, ...);

       #include <stdarg.h>

       void verr(int eval, const char *fmt, va_list args);

       void verrx(int eval, const char *fmt, va_list args);

       void vwarn(const char *fmt, va_list args);

       void vwarnx(const char *fmt, va_list args);

DESCRIPTION top

       The err() and warn() family of functions display a formatted error message
       on the standard error output.  In all cases, the last component of the
       program name, a colon character, and a space are output.  If the fmt
       argument is not NULL, the printf(3)-like formatted error message is output.
       The output is terminated by a newline character.

       The err(), verr(), warn(), and vwarn() functions append an error message
       obtained from strerror(3) based on the global variable errno, preceded by
       another colon and space unless the fmt argument is NULL.

       The errx() and warnx() functions do not append an error message.

       The err(), verr(), errx(), and verrx() functions do not return, but exit
       with the value of the argument eval.

CONFORMING TO top

       These functions are nonstandard BSD extensions.

EXAMPLE top

       Display the current errno information string and exit:

           if ((p = malloc(size)) == NULL)
               err(1, NULL);
           if ((fd = open(file_name, O_RDONLY, 0)) == -1)
               err(1, "%s", file_name);

       Display an error message and exit:

           if (tm.tm_hour < START_TIME)
               errx(1, "too early, wait until %s", start_time_string);

       Warn of an error:

           if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
               warnx("%s: %s: trying the block device",
                       raw_device, strerror(errno));
           if ((fd = open(block_device, O_RDONLY, 0)) == -1)
               err(1, "%s", block_device);

SEE ALSO top

       error(3), exit(3), perror(3), printf(3), strerror(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-15                              ERR(3)


errno(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ERRNO(3)                     Linux Programmer's Manual                    ERRNO(3)

NAME top

       errno - number of last error

SYNOPSIS top

       #include <errno.h>

DESCRIPTION top

       The <errno.h> header file defines the integer variable errno, which is set
       by system calls and some library functions in the event of an error to
       indicate what went wrong.  Its value is significant only when the return
       value of the call indicated an error (i.e., -1 from most system calls; -1
       or NULL from most library functions); a function that succeeds is allowed
       to change errno.

       Valid error numbers are all nonzero; errno is never set to zero by any
       system call or library function.

       For some system calls and library functions (e.g., getpriority(2)), -1 is a
       valid return on success.  In such cases, a successful return can be
       distinguished from an error return by setting errno to zero before the
       call, and then, if the call returns a status that indicates that an error
       may have occurred, checking to see if errno has a nonzero value.

       errno is defined by the ISO C standard to be a modifiable lvalue of type
       int, and must not be explicitly declared; errno may be a macro.  errno is
       thread-local; setting it in one thread does not affect its value in any
       other thread.

       All the error names specified by POSIX.1 must have distinct values, with
       the exception of EAGAIN and EWOULDBLOCK, which may be the same.

       Below is a list of the symbolic error names that are defined on Linux.
       Some of these are marked POSIX.1, indicating that the name is defined by
       POSIX.1-2001, or C99, indicating that the name is defined by C99.

       E2BIG           Argument list too long (POSIX.1)

       EACCES          Permission denied (POSIX.1)

       EADDRINUSE      Address already in use (POSIX.1)

       EADDRNOTAVAIL   Address not available (POSIX.1)

       EAFNOSUPPORT    Address family not supported (POSIX.1)

       EAGAIN          Resource temporarily unavailable (may be the same value as
                       EWOULDBLOCK) (POSIX.1)

       EALREADY        Connection already in progress (POSIX.1)

       EBADE           Invalid exchange

       EBADF           Bad file descriptor (POSIX.1)

       EBADFD          File descriptor in bad state

       EBADMSG         Bad message (POSIX.1)

       EBADR           Invalid request descriptor

       EBADRQC         Invalid request code

       EBADSLT         Invalid slot

       EBUSY           Device or resource busy (POSIX.1)

       ECANCELED       Operation canceled (POSIX.1)

       ECHILD          No child processes (POSIX.1)

       ECHRNG          Channel number out of range

       ECOMM           Communication error on send

       ECONNABORTED    Connection aborted (POSIX.1)

       ECONNREFUSED    Connection refused (POSIX.1)

       ECONNRESET      Connection reset (POSIX.1)

       EDEADLK         Resource deadlock avoided (POSIX.1)

       EDEADLOCK       Synonym for EDEADLK

       EDESTADDRREQ    Destination address required (POSIX.1)

       EDOM            Mathematics argument out of domain of function (POSIX.1,
                       C99)

       EDQUOT          Disk quota exceeded (POSIX.1)

       EEXIST          File exists (POSIX.1)

       EFAULT          Bad address (POSIX.1)

       EFBIG           File too large (POSIX.1)

       EHOSTDOWN       Host is down

       EHOSTUNREACH    Host is unreachable (POSIX.1)

       EIDRM           Identifier removed (POSIX.1)

       EILSEQ          Illegal byte sequence (POSIX.1, C99)

       EINPROGRESS     Operation in progress (POSIX.1)

       EINTR           Interrupted function call (POSIX.1); see signal(7).

       EINVAL          Invalid argument (POSIX.1)

       EIO             Input/output error (POSIX.1)

       EISCONN         Socket is connected (POSIX.1)

       EISDIR          Is a directory (POSIX.1)

       EISNAM          Is a named type file

       EKEYEXPIRED     Key has expired

       EKEYREJECTED    Key was rejected by service

       EKEYREVOKED     Key has been revoked

       EL2HLT          Level 2 halted

       EL2NSYNC        Level 2 not synchronized

       EL3HLT          Level 3 halted

       EL3RST          Level 3 halted

       ELIBACC         Cannot access a needed shared library

       ELIBBAD         Accessing a corrupted shared library

       ELIBMAX         Attempting to link in too many shared libraries

       ELIBSCN         lib section in a.out corrupted

       ELIBEXEC        Cannot exec a shared library directly

       ELOOP           Too many levels of symbolic links (POSIX.1)

       EMEDIUMTYPE     Wrong medium type

       EMFILE          Too many open files (POSIX.1)

       EMLINK          Too many links (POSIX.1)

       EMSGSIZE        Message too long (POSIX.1)

       EMULTIHOP       Multihop attempted (POSIX.1)

       ENAMETOOLONG    Filename too long (POSIX.1)

       ENETDOWN        Network is down (POSIX.1)

       ENETRESET       Connection aborted by network (POSIX.1)

       ENETUNREACH     Network unreachable (POSIX.1)

       ENFILE          Too many open files in system (POSIX.1)

       ENOBUFS         No buffer space available (POSIX.1 (XSI STREAMS option))

       ENODATA         No message is available on the STREAM head read queue
                       (POSIX.1)

       ENODEV          No such device (POSIX.1)

       ENOENT          No such file or directory (POSIX.1)

       ENOEXEC         Exec format error (POSIX.1)

       ENOKEY          Required key not available

       ENOLCK          No locks available (POSIX.1)

       ENOLINK         Link has been severed (POSIX.1)

       ENOMEDIUM       No medium found

       ENOMEM          Not enough space (POSIX.1)

       ENOMSG          No message of the desired type (POSIX.1)

       ENONET          Machine is not on the network

       ENOPKG          Package not installed

       ENOPROTOOPT     Protocol not available (POSIX.1)

       ENOSPC          No space left on device (POSIX.1)

       ENOSR           No STREAM resources (POSIX.1 (XSI STREAMS option))

       ENOSTR          Not a STREAM (POSIX.1 (XSI STREAMS option))

       ENOSYS          Function not implemented (POSIX.1)

       ENOTBLK         Block device required

       ENOTCONN        The socket is not connected (POSIX.1)

       ENOTDIR         Not a directory (POSIX.1)

       ENOTEMPTY       Directory not empty (POSIX.1)

       ENOTSOCK        Not a socket (POSIX.1)

       ENOTSUP         Operation not supported (POSIX.1)

       ENOTTY          Inappropriate I/O control operation (POSIX.1)

       ENOTUNIQ        Name not unique on network

       ENXIO           No such device or address (POSIX.1)

       EOPNOTSUPP      Operation not supported on socket (POSIX.1)

                       (ENOTSUP and EOPNOTSUPP have the same value on Linux, but
                       according to POSIX.1 these error values should be
                       distinct.)

       EOVERFLOW       Value too large to be stored in data type (POSIX.1)

       EPERM           Operation not permitted (POSIX.1)

       EPFNOSUPPORT    Protocol family not supported

       EPIPE           Broken pipe (POSIX.1)

       EPROTO          Protocol error (POSIX.1)

       EPROTONOSUPPORT Protocol not supported (POSIX.1)

       EPROTOTYPE      Protocol wrong type for socket (POSIX.1)

       ERANGE          Result too large (POSIX.1, C99)

       EREMCHG         Remote address changed

       EREMOTE         Object is remote

       EREMOTEIO       Remote I/O error

       ERESTART        Interrupted system call should be restarted

       EROFS           Read-only file system (POSIX.1)

       ESHUTDOWN       Cannot send after transport endpoint shutdown

       ESPIPE          Invalid seek (POSIX.1)

       ESOCKTNOSUPPORT Socket type not supported

       ESRCH           No such process (POSIX.1)

       ESTALE          Stale file handle (POSIX.1)

                       This error can occur for NFS and for other file systems

       ESTRPIPE        Streams pipe error

       ETIME           Timer expired (POSIX.1 (XSI STREAMS option))

                       (POSIX.1 says "STREAM ioctl(2) timeout")

       ETIMEDOUT       Connection timed out (POSIX.1)

       ETXTBSY         Text file busy (POSIX.1)

       EUCLEAN         Structure needs cleaning

       EUNATCH         Protocol driver not attached

       EUSERS          Too many users

       EWOULDBLOCK     Operation would block (may be same value as EAGAIN)
                       (POSIX.1)

       EXDEV           Improper link (POSIX.1)

       EXFULL          Exchange full

NOTES top

       A common mistake is to do

           if (somecall() == -1) {
               printf("somecall() failed\n");
               if (errno == ...) { ... }
           }

       where errno no longer needs to have the value it had upon return from
       somecall() (i.e., it may have been changed by the printf(3)).  If the value
       of errno should be preserved across a library call, it must be saved:

           if (somecall() == -1) {
               int errsv = errno;
               printf("somecall() failed\n");
               if (errsv == ...) { ... }
           }

       It was common in traditional C to declare errno manually (i.e., extern int
       errno) instead of including <errno.h>.  Do not do this.  It will not work
       with modern versions of the C library.  However, on (very) old UNIX
       systems, there may be no <errno.h> and the declaration is needed.

SEE ALSO top

       err(3), error(3), perror(3), strerror(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-07-09                            ERRNO(3)


error(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ERROR(3)                     Linux Programmer's Manual                    ERROR(3)

NAME top

       error,      error_at_line,     error_message_count,     error_one_per_line,
       error_print_progname - glibc error reporting functions

SYNOPSIS top

       #include <error.h>

       void error(int status, int errnum, const char *format, ...);

       void error_at_line(int status, int errnum, const char *[22mfilename,[0m
                          unsigned int linenum, const char *format, ...);

       extern unsigned int error_message_count;

       extern int error_one_per_line;

       extern void (* error_print_progname) (void);

DESCRIPTION top

       error() is a general error-reporting function.  It flushes stdout, and then
       outputs to stderr the program name, a colon and a space, the message
       specified by the printf(3)-style format string format, and, if errnum is
       nonzero, a second colon and a space followed by the string given by
       strerror(errnum).  Any arguments required for format should follow format
       in the argument list.  The output is terminated by a newline character.

       The program name printed by error() is the value of the global variable
       program_invocation_name(3).  program_invocation_name initially has the same
       value as main()'s argv[0].  The value of this variable can be modified to
       change the output of error().

       If status has a nonzero value, then error() calls exit(3) to terminate the
       program using the given value as the exit status.

       The error_at_line() function is exactly the same as error(), except for the
       addition of the arguments filename and linenum.  The output produced is as
       for error(), except that after the program name are written: a colon, the
       value of filename, a colon, and the value of linenum.  The preprocessor
       values __LINE__ and __FILE__ may be useful when calling error_at_line(),
       but other values can also be used.  For example, these arguments could
       refer to a location in an input file.

       If the global variable error_one_per_line is set nonzero, a sequence of
       error_at_line() calls with the same value of filename and linenum will
       result in only one message (the first) being output.

       The global variable error_message_count counts the number of messages that
       have been output by error() and error_at_line().

       If the global variable error_print_progname is assigned the address of a
       function (i.e., is not NULL), then that function is called instead of
       prefixing the message with the program name and colon.  The function should
       print a suitable string to stderr.

CONFORMING TO top

       These functions and variables are GNU extensions, and should not be used in
       programs intended to be portable.

SEE ALSO top

       err(3), errno(3), exit(3), perror(3), program_invocation_name(3),
       strerror(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-08-29                            ERROR(3)


ether_aton(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

ETHER_ATON(3)                Linux Programmer's Manual               ETHER_ATON(3)

NAME top

       ether_aton,    ether_ntoa,    ether_ntohost,   ether_hostton,   ether_line,
       ether_ntoa_r, ether_aton_r - Ethernet address manipulation routines

SYNOPSIS top

       #include <netinet/ether.h>

       char *ether_ntoa(const struct ether_addr *addr);

       struct ether_addr *ether_aton(const char *asc);

       int ether_ntohost(char *hostname, const struct ether_addr *addr);

       int ether_hostton(const char *hostname, struct ether_addr *addr);

       int ether_line(const char *line, struct ether_addr *addr,
                      char *hostname);

       /* GNU extensions */
       char *ether_ntoa_r(const struct ether_addr *addr, char *buf);

       struct ether_addr *ether_aton_r(const char *asc,
                                       struct ether_addr *addr);

DESCRIPTION top

       ether_aton() converts the 48-bit Ethernet host address asc from the
       standard hex-digits-and-colons notation into binary data in network byte
       order and returns a pointer to it in a statically allocated buffer, which
       subsequent calls will overwrite.  ether_aton() returns NULL if the address
       is invalid.

       The ether_ntoa() function converts the Ethernet host address addr given in
       network byte order to a string in standard hex-digits-and-colons notation,
       omitting leading zeros.  The string is returned in a statically allocated
       buffer, which subsequent calls will overwrite.

       The ether_ntohost() function maps an Ethernet address to the corresponding
       hostname in /etc/ethers and returns nonzero if it cannot be found.

       The ether_hostton() function maps a hostname to the corresponding Ethernet
       address in /etc/ethers and returns nonzero if it cannot be found.

       The ether_line() function parses a line in /etc/ethers format (ethernet
       address followed by whitespace followed by hostname; '#' introduces a
       comment) and returns an address and hostname pair, or nonzero if it cannot
       be parsed.  The buffer pointed to by hostname must be sufficiently long,
       for example, have the same length as line.

       The functions ether_ntoa_r() and ether_aton_r() are reentrant thread-safe
       versions of ether_ntoa() and ether_aton() respectively, and do not use
       static buffers.

       The structure ether_addr is defined in <net/ethernet.h> as:

           struct ether_addr {
               uint8_t ether_addr_octet[6];
           }

CONFORMING TO top

       4.3BSD, SunOS.

BUGS top

       The glibc 2.2.5 implementation of ether_line() is broken.

SEE ALSO top

       ethers(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2002-07-20                       ETHER_ATON(3)


eventfd(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

EVENTFD(2)                   Linux Programmer's Manual                  EVENTFD(2)

NAME top

       eventfd - create a file descriptor for event notification

SYNOPSIS top

       #include <sys/eventfd.h>

       int eventfd(unsigned int initval, int flags);

DESCRIPTION top

       eventfd() creates an "eventfd object" that can be used as an event
       wait/notify mechanism by user-space applications, and by the kernel to
       notify user-space applications of events.  The object contains an unsigned
       64-bit integer (uint64_t) counter that is maintained by the kernel.  This
       counter is initialized with the value specified in the argument initval.

       The following values may be bitwise ORed in flags to change the behaviour
       of eventfd():

       EFD_CLOEXEC (since Linux 2.6.27)
              Set the close-on-exec (FD_CLOEXEC) flag on the new file descriptor.
              See the description of the O_CLOEXEC flag in open(2) for reasons why
              this may be useful.

       EFD_NONBLOCK (since Linux 2.6.27)
              Set the O_NONBLOCK file status flag on the new open file
              description.  Using this flag saves extra calls to fcntl(2) to
              achieve the same result.

       EFD_SEMAPHORE (since Linux 2.6.30)
              Provide semaphore-like semantics for reads from the new file
              descriptor.  See below.

       In Linux up to version 2.6.26, the flags argument is unused, and must be
       specified as zero.

       As its return value, eventfd() returns a new file descriptor that can be
       used to refer to the eventfd object.  The following operations can be
       performed on the file descriptor:

       read(2)
              Each successful read(2) returns an 8-byte integer.  A read(2) will
              fail with the error EINVAL if the size of the supplied buffer is
              less than 8 bytes.

              The value returned by read(2) is in host byte order, i.e., the
              native byte order for integers on the host machine.

              The semantics of read(2) depend on whether the eventfd counter
              currently has a nonzero value and whether the EFD_SEMAPHORE flag was
              specified when creating the eventfd file descriptor:

              *  If EFD_SEMAPHORE was not specified and the eventfd counter has a
                 nonzero value, then a read(2) returns 8 bytes containing that
                 value, and the counter's value is reset to zero.

              *  If EFD_SEMAPHORE was specified and the eventfd counter has a
                 nonzero value, then a read(2) returns 8 bytes containing the
                 value 1, and the counter's value is decremented by 1.

              *  If the eventfd counter is zero at the time of the call to
                 read(2), then the call either blocks until the counter becomes
                 nonzero (at which time, the read(2) proceeds as described above)
                 or fails with the error EAGAIN if the file descriptor has been
                 made nonblocking.

       write(2)
              A write(2) call adds the 8-byte integer value supplied in its buffer
              to the counter.  The maximum value that may be stored in the counter
              is the largest unsigned 64-bit value minus 1 (i.e.,
              0xfffffffffffffffe).  If the addition would cause the counter's
              value to exceed the maximum, then the write(2) either blocks until a
              read(2) is performed on the file descriptor, or fails with the error
              EAGAIN if the file descriptor has been made nonblocking.

              A write(2) will fail with the error EINVAL if the size of the
              supplied buffer is less than 8 bytes, or if an attempt is made to
              write the value 0xffffffffffffffff.

       poll(2), select(2) (and similar)
              The returned file descriptor supports poll(2) (and analogously
              epoll(7)) and select(2), as follows:

              *  The file descriptor is readable (the select(2) readfds argument;
                 the poll(2) POLLIN flag) if the counter has a value greater than
                 0.

              *  The file descriptor is writable (the select(2) writefds argument;
                 the poll(2) POLLOUT flag) if it is possible to write a value of
                 at least "1" without blocking.

              *  If an overflow of the counter value was detected, then select(2)
                 indicates the file descriptor as being both readable and
                 writable, and poll(2) returns a POLLERR event.  As noted above,
                 write(2) can never overflow the counter.  However an overflow can
                 occur if 2^64 eventfd "signal posts" were performed by the KAIO
                 subsystem (theoretically possible, but practically unlikely).  If
                 an overflow has occurred, then read(2) will return that maximum
                 uint64_t value (i.e., 0xffffffffffffffff).

              The eventfd file descriptor also supports the other file-descriptor
              multiplexing APIs: pselect(2), ppoll(2), and epoll(7).

       close(2)
              When the file descriptor is no longer required it should be closed.
              When all file descriptors associated with the same eventfd object
              have been closed, the resources for object are freed by the kernel.

       A copy of the file descriptor created by eventfd() is inherited by the
       child produced by fork(2).  The duplicate file descriptor is associated
       with the same eventfd object.  File descriptors created by eventfd() are
       preserved across execve(2), unless the close-on-exec flag has been set.

RETURN VALUE top

       On success, eventfd() returns a new eventfd file descriptor.  On error, -1
       is returned and errno is set to indicate the error.

ERRORS top

       EINVAL An unsupported value was specified in flags.

       EMFILE The per-process limit on open file descriptors has been reached.

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

       ENODEV Could not mount (internal) anonymous inode device.

       ENOMEM There was insufficient memory to create a new eventfd file
              descriptor.

VERSIONS top

       eventfd() is available on Linux since kernel 2.6.22.  Working support is
       provided in glibc since version 2.8.  The eventfd2() system call (see
       NOTES) is available on Linux since kernel 2.6.27.  Since version 2.9, the
       glibc eventfd() wrapper will employ the eventfd2() system call, if it is
       supported by the kernel.

CONFORMING TO top

       eventfd() and eventfd2() are Linux-specific.

NOTES top

       Applications can use an eventfd file descriptor instead of a pipe (see
       pipe(2)) in all cases where a pipe is used simply to signal events.  The
       kernel overhead of an eventfd file descriptor is much lower than that of a
       pipe, and only one file descriptor is required (versus the two required for
       a pipe).

       When used in the kernel, an eventfd file descriptor can provide a bridge
       from kernel to user space, allowing, for example, functionalities like KAIO
       (kernel AIO) to signal to a file descriptor that some operation is
       complete.

       A key point about an eventfd file descriptor is that it can be monitored
       just like any other file descriptor using select(2), poll(2), or epoll(7).
       This means that an application can simultaneously monitor the readiness of
       "traditional" files and the readiness of other kernel mechanisms that
       support the eventfd interface.  (Without the eventfd() interface, these
       mechanisms could not be multiplexed via select(2), poll(2), or epoll(7).)

Underlying Linux system calls

       There are two underlying Linux system calls: eventfd() and the more recent
       eventfd2().  The former system call does not implement a flags argument.
       The latter system call implements the flags values described above.  The
       glibc wrapper function will use eventfd2() where it is available.

Additional glibc features

       The GNU C library defines an additional type, and two functions that
       attempt to abstract some of the details of reading and writing on an
       eventfd file descriptor:

           typedef uint64_t eventfd_t;

           int eventfd_read(int fd, eventfd_t *value);
           int eventfd_write(int fd, eventfd_t value);

       The functions perform the read and write operations on an eventfd file
       descriptor, returning 0 if the correct number of bytes was transferred, or
       -1 otherwise.

EXAMPLE top

       The following program creates an eventfd file descriptor and then forks to
       create a child process.  While the parent briefly sleeps, the child writes
       each of the integers supplied in the program's command-line arguments to
       the eventfd file descriptor.  When the parent has finished sleeping, it
       reads from the eventfd file descriptor.

       The following shell session shows a sample run of the program:

           $ ./a.out 1 2 4 7 14
           Child writing 1 to efd
           Child writing 2 to efd
           Child writing 4 to efd
           Child writing 7 to efd
           Child writing 14 to efd
           Child completed write loop
           Parent about to read
           Parent read 28 (0x1c) from efd

Program source

       #include <sys/eventfd.h>
       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <stdint.h>             /* Definition of uint64_t */

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

       int
       main(int argc, char *argv[])
       {
           int efd, j;
           uint64_t u;
           ssize_t s;

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

           efd = eventfd(0, 0);
           if (efd == -1)
               handle_error("eventfd");

           switch (fork()) {
           case 0:
               for (j = 1; j < argc; j++) {
                   printf("Child writing %s to efd\n", argv[j]);
                   u = strtoull(argv[j], NULL, 0);
                           /* strtoull() allows various bases */
                   s = write(efd, &u, sizeof(uint64_t));
                   if (s != sizeof(uint64_t))
                       handle_error("write");
               }
               printf("Child completed write loop\n");

               exit(EXIT_SUCCESS);

           default:
               sleep(2);

               printf("Parent about to read\n");
               s = read(efd, &u, sizeof(uint64_t));
               if (s != sizeof(uint64_t))
                   handle_error("read");
               printf("Parent read %llu (0x%llx) from efd\n",
                       (unsigned long long) u, (unsigned long long) u);
               exit(EXIT_SUCCESS);

           case -1:
               handle_error("fork");
           }
       }

SEE ALSO top

       futex(2), pipe(2), poll(2), read(2), select(2), signalfd(2),
       timerfd_create(2), write(2), epoll(7), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-08-30                          EVENTFD(2)


exec(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

EXEC(3)                      Linux Programmer's Manual                     EXEC(3)

NAME top

       execl, execlp, execle, execv, execvp, execvpe - execute a file

SYNOPSIS top

       #include <unistd.h>

       extern char **environ;

       int execl(const char *path, const char *arg, ...);
       int execlp(const char *file, const char *arg, ...);
       int execle(const char *path, const char *arg,
                  ..., char * const envp[]);
       int execv(const char *path, char *const argv[]);
       int execvp(const char *file, char *const argv[]);
       int execvpe(const char *file, char *const argv[],
                   char *const envp[]);

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

       execvpe(): _GNU_SOURCE

DESCRIPTION top

       The exec() family of functions replaces the current process image with a
       new process image.  The functions described in this manual page are front-
       ends for execve(2).  (See the manual page for execve(2) for further details
       about the replacement of the current process image.)

       The initial argument for these functions is the name of a file that is to
       be executed.

       The const char *arg and subsequent ellipses in the execl(), execlp(), and
       execle() functions can be thought of as arg0, arg1, ..., argn.  Together
       they describe a list of one or more pointers to null-terminated strings
       that represent the argument list available to the executed program.  The
       first argument, by convention, should point to the filename associated with
       the file being executed.  The list of arguments must be terminated by a
       NULL pointer, and, since these are variadic functions, this pointer must be
       cast (char *) NULL.

       The execv(), execvp(), and execvpe() functions provide an array of pointers
       to null-terminated strings that represent the argument list available to
       the new program.  The first argument, by convention, should point to the
       filename associated with the file being executed.  The array of pointers
       must be terminated by a NULL pointer.

       The execle() and execvpe() functions allow the caller to specify the
       environment of the executed program via the argument envp.  The envp
       argument is an array of pointers to null-terminated strings and must be
       terminated by a NULL pointer.  The other functions take the environment for
       the new process image from the external variable environ in the calling
       process.

Special semantics for execlp() and execvp()

       The execlp(), execvp(), and execvpe() functions duplicate the actions of
       the shell in searching for an executable file if the specified filename
       does not contain a slash (/) character.  The file is sought in the colon-
       separated list of directory pathnames specified in the PATH environment
       variable.  If this variable isn't defined, the path list defaults to the
       current directory followed by the list of directories returned by
       confstr(_CS_PATH).  (This confstr(3) call typically returns the value
       "/bin:/usr/bin".)

       If the specified filename includes a slash character, then PATH is ignored,
       and the file at the specified pathname is executed.

       In addition, certain errors are treated specially.

       If permission is denied for a file (the attempted execve(2) failed with the
       error EACCES), these functions will continue searching the rest of the
       search path.  If no other file is found, however, they will return with
       errno set to EACCES.

       If the header of a file isn't recognized (the attempted execve(2) failed
       with the error ENOEXEC), these functions will execute the shell (/bin/sh)
       with the path of the file as its first argument.  (If this attempt fails,
       no further searching is done.)

RETURN VALUE top

       The exec() functions only return if an error has have occurred.  The return
       value is -1, and errno is set to indicate the error.

ERRORS top

       All of these functions may fail and set errno for any of the errors
       specified for execve(2).

VERSIONS top

       The execvpe() function first appeared in glibc 2.11.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

       The execvpe() function is a GNU extension.

NOTES top

       On some other systems, the default path (used when the environment does not
       contain the variable PATH) has the current working directory listed after
       /bin and /usr/bin, as an anti-Trojan-horse measure.  Linux uses here the
       traditional "current directory first" default path.

       The behavior of execlp() and execvp() when errors occur while attempting to
       execute the file is historic practice, but has not traditionally been
       documented and is not specified by the POSIX standard.  BSD (and possibly
       other systems) do an automatic sleep and retry if ETXTBSY is encountered.
       Linux treats it as a hard error and returns immediately.

       Traditionally, the functions execlp() and execvp() ignored all errors
       except for the ones described above and ENOMEM and E2BIG, upon which they
       returned.  They now return if any error other than the ones described above
       occurs.

SEE ALSO top

       sh(1), execve(2), fork(2), ptrace(2), fexecve(3), environ(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-25                             EXEC(3)


execve(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

EXECVE(2)                    Linux Programmer's Manual                   EXECVE(2)

NAME top

       execve - execute program

SYNOPSIS top

       #include <unistd.h>

       int execve(const char *filename, char *const argv[],
                  char *const envp[]);

DESCRIPTION top

       execve() executes the program pointed to by filename.  filename must be
       either a binary executable, or a script starting with a line of the form:

           #! interpreter [optional-arg]

       For details of the latter case, see "Interpreter scripts" below.

       argv is an array of argument strings passed to the new program.  By
       convention, the first of these strings should contain the filename
       associated with the file being executed.  envp is an array of strings,
       conventionally of the form key=value, which are passed as environment to
       the new program.  Both argv and envp must be terminated by a NULL pointer.
       The argument vector and environment can be accessed by the called program's
       main function, when it is defined as:

           int main(int argc, char *argv[], char *envp[])

       execve() does not return on success, and the text, data, bss, and stack of
       the calling process are overwritten by that of the program loaded.

       If the current program is being ptraced, a SIGTRAP is sent to it after a
       successful execve().

       If the set-user-ID bit is set on the program file pointed to by filename,
       and the underlying file system is not mounted nosuid (the MS_NOSUID flag
       for mount(2)), and the calling process is not being ptraced, then the
       effective user ID of the calling process is changed to that of the owner of
       the program file.  Similarly, when the set-group-ID bit of the program file
       is set the effective group ID of the calling process is set to the group of
       the program file.

       The effective user ID of the process is copied to the saved set-user-ID;
       similarly, the effective group ID is copied to the saved set-group-ID.
       This copying takes place after any effective ID changes that occur because
       of the set-user-ID and set-group-ID permission bits.

       If the executable is an a.out dynamically linked binary executable
       containing shared-library stubs, the Linux dynamic linker ld.so(8) is
       called at the start of execution to bring needed shared libraries into
       memory and link the executable with them.

       If the executable is a dynamically linked ELF executable, the interpreter
       named in the PT_INTERP segment is used to load the needed shared libraries.
       This interpreter is typically /lib/ld-linux.so.2 for binaries linked with
       glibc 2.  (For binaries linked with the old Linux libc5, the interpreter
       was typically /lib/ld-linux.so.1.)

       All process attributes are preserved during an execve(), except the
       following:

       *  The dispositions of any signals that are being caught are reset to the
          default (signal(7)).

       *  Any alternate signal stack is not preserved (sigaltstack(2)).

       *  Memory mappings are not preserved (mmap(2)).

       *  Attached System V shared memory segments are detached (shmat(2)).

       *  POSIX shared memory regions are unmapped (shm_open(3)).

       *  Open POSIX message queue descriptors are closed (mq_overview(7)).

       *  Any open POSIX named semaphores are closed (sem_overview(7)).

       *  POSIX timers are not preserved (timer_create(2)).

       *  Any open directory streams are closed (opendir(3)).

       *  Memory locks are not preserved (mlock(2), mlockall(2)).

       *  Exit handlers are not preserved (atexit(3), on_exit(3)).

       *  The floating-point environment is reset to the default (see fenv(3)).

       The process attributes in the preceding list are all specified in
       POSIX.1-2001.  The following Linux-specific process attributes are also not
       preserved during an execve():

       *  The prctl(2) PR_SET_DUMPABLE flag is set, unless a set-user-ID or set-
          group ID program is being executed, in which case it is cleared.

       *  The prctl(2) PR_SET_KEEPCAPS flag is cleared.

       *  (Since Linux 2.4.36 / 2.6.23) If a set-user-ID or set-group-ID program
          is being executed, then the parent death signal set by prctl(2)
          PR_SET_PDEATHSIG flag is cleared.

       *  The process name, as set by prctl(2) PR_SET_NAME (and displayed by ps -o
          comm), is reset to the name of the new executable file.

       *  The SECBIT_KEEP_CAPS securebits flag is cleared.  See capabilities(7).

       *  The termination signal is reset to SIGCHLD (see clone(2)).

       Note the following further points:

       *  All threads other than the calling thread are destroyed during an
          execve().  Mutexes, condition variables, and other pthreads objects are
          not preserved.

       *  The equivalent of setlocale(LC_ALL, "C") is executed at program start-
          up.

       *  POSIX.1-2001 specifies that the dispositions of any signals that are
          ignored or set to the default are left unchanged.  POSIX.1-2001
          specifies one exception: if SIGCHLD is being ignored, then an
          implementation may leave the disposition unchanged or reset it to the
          default; Linux does the former.

       *  Any outstanding asynchronous I/O operations are canceled (aio_read(3),
          aio_write(3)).

       *  For the handling of capabilities during execve(), see capabilities(7).

       *  By default, file descriptors remain open across an execve().  File
          descriptors that are marked close-on-exec are closed; see the
          description of FD_CLOEXEC in fcntl(2).  (If a file descriptor is closed,
          this will cause the release of all record locks obtained on the
          underlying file by this process.  See fcntl(2) for details.)
          POSIX.1-2001 says that if file descriptors 0, 1, and 2 would otherwise
          be closed after a successful execve(), and the process would gain
          privilege because the set-user_ID or set-group_ID permission bit was set
          on the executed file, then the system may open an unspecified file for
          each of these file descriptors.  As a general principle, no portable
          program, whether privileged or not, can assume that these three file
          descriptors will remain closed across an execve().

Interpreter scripts

       An interpreter script is a text file that has execute permission enabled
       and whose first line is of the form:

           #! interpreter [optional-arg]

       The interpreter must be a valid pathname for an executable which is not
       itself a script.  If the filename argument of execve() specifies an
       interpreter script, then interpreter will be invoked with the following
       arguments:

           interpreter [optional-arg] filename arg...

       where arg...  is the series of words pointed to by the argv argument of
       execve().

       For portable use, optional-arg should either be absent, or be specified as
       a single word (i.e., it should not contain white space); see NOTES below.

Limits on size of arguments and environment

       Most UNIX implementations impose some limit on the total size of the
       command-line argument (argv) and environment (envp) strings that may be
       passed to a new program.  POSIX.1 allows an implementation to advertise
       this limit using the ARG_MAX constant (either defined in <limits.h> or
       available at run time using the call sysconf(_SC_ARG_MAX)).

       On Linux prior to kernel 2.6.23, the memory used to store the environment
       and argument strings was limited to 32 pages (defined by the kernel
       constant MAX_ARG_PAGES).  On architectures with a 4-kB page size, this
       yields a maximum size of 128 kB.

       On kernel 2.6.23 and later, most architectures support a size limit derived
       from the soft RLIMIT_STACK resource limit (see getrlimit(2)) that is in
       force at the time of the execve() call.  (Architectures with no memory
       management unit are excepted: they maintain the limit that was in effect
       before kernel 2.6.23.)  This change allows programs to have a much larger
       argument and/or environment list.  For these architectures, the total size
       is limited to 1/4 of the allowed stack size.  (Imposing the 1/4-limit
       ensures that the new program always has some stack space.)  Since Linux
       2.6.25, the kernel places a floor of 32 pages on this size limit, so that,
       even when RLIMIT_STACK is set very low, applications are guaranteed to have
       at least as much argument and environment space as was provided by Linux
       2.6.23 and earlier.  (This guarantee was not provided in Linux 2.6.23 and
       2.6.24.)  Additionally, the limit per string is 32 pages (the kernel
       constant MAX_ARG_STRLEN), and the maximum number of strings is 0x7FFFFFFF.

RETURN VALUE top

       On success, execve() does not return, on error -1 is returned, and errno is
       set appropriately.

ERRORS top

       E2BIG  The total number of bytes in the environment (envp) and argument
              list (argv) is too large.

       EACCES Search permission is denied on a component of the path prefix of
              filename or the name of a script interpreter.  (See also
              path_resolution(7).)

       EACCES The file or a script interpreter is not a regular file.

       EACCES Execute permission is denied for the file or a script or ELF
              interpreter.

       EACCES The file system is mounted noexec.

       EFAULT filename points outside your accessible address space.

       EINVAL An ELF executable had more than one PT_INTERP segment (i.e., tried
              to name more than one interpreter).

       EIO    An I/O error occurred.

       EISDIR An ELF interpreter was a directory.

       ELIBBAD
              An ELF interpreter was not in a recognized format.

       ELOOP  Too many symbolic links were encountered in resolving filename or
              the name of a script or ELF interpreter.

       EMFILE The process has the maximum number of files open.

       ENAMETOOLONG
              filename is too long.

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

       ENOENT The file filename or a script or ELF interpreter does not exist, or
              a shared library needed for file or interpreter cannot be found.

       ENOEXEC
              An executable is not in a recognized format, is for the wrong
              architecture, or has some other format error that means it cannot be
              executed.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of the path prefix of filename or a script or ELF
              interpreter is not a directory.

       EPERM  The file system is mounted nosuid, the user is not the superuser,
              and the file has the set-user-ID or set-group-ID bit set.

       EPERM  The process is being traced, the user is not the superuser and the
              file has the set-user-ID or set-group-ID bit set.

       ETXTBSY
              Executable was open for writing by one or more processes.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  POSIX.1-2001 does not document the #!
       behavior but is otherwise compatible.

NOTES top

       Set-user-ID and set-group-ID processes can not be ptrace(2)d.

       Linux ignores the set-user-ID and set-group-ID bits on scripts.

       The result of mounting a file system nosuid varies across Linux kernel
       versions: some will refuse execution of set-user-ID and set-group-ID
       executables when this would give the user powers she did not have already
       (and return EPERM), some will just ignore the set-user-ID and set-group-ID
       bits and exec() successfully.

       A maximum line length of 127 characters is allowed for the first line in a
       #! executable shell script.

       The semantics of the optional-arg argument of an interpreter script vary
       across implementations.  On Linux, the entire string following the
       interpreter name is passed as a single argument to the interpreter, and
       this string can include white space.  However, behavior differs on some
       other systems.  Some systems use the first white space to terminate
       optional-arg.  On some systems, an interpreter script can have multiple
       arguments, and white spaces in optional-arg are used to delimit the
       arguments.

       On Linux, argv can be specified as NULL, which has the same effect as
       specifying this argument as a pointer to a list containing a single NULL
       pointer.  Do not take advantage of this misfeature!  It is nonstandard and
       nonportable: on most other UNIX systems doing this will result in an error
       (EFAULT).

       POSIX.1-2001 says that values returned by sysconf(3) should be invariant
       over the lifetime of a process.  However, since Linux 2.6.23, if the
       RLIMIT_STACK resource limit changes, then the value reported by _SC_ARG_MAX
       will also change, to reflect the fact that the limit on space for holding
       command-line arguments and environment variables has changed.

Historical

       With UNIX V6 the argument list of an exec() call was ended by 0, while the
       argument list of main was ended by -1.  Thus, this argument list was not
       directly usable in a further exec() call.  Since UNIX V7 both are NULL.

EXAMPLE top

       The following program is designed to be execed by the second program below.
       It just echoes its command-line one per line.

           /* myecho.c */

           #include <stdio.h>
           #include <stdlib.h>

           int
           main(int argc, char *argv[])
           {
               int j;

               for (j = 0; j < argc; j++)
                   printf("argv[%d]: %s\n", j, argv[j]);

               exit(EXIT_SUCCESS);
           }

       This program can be used to exec the program named in its command-line
       argument:

           /* execve.c */

           #include <stdio.h>
           #include <stdlib.h>
           #include <unistd.h>

           int
           main(int argc, char *argv[])
           {
               char *newargv[] = { NULL, "hello", "world", NULL };
               char *newenviron[] = { NULL };

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

               newargv[0] = argv[1];

               execve(argv[1], newargv, newenviron);
               perror("execve");   /* execve() only returns on error */
               exit(EXIT_FAILURE);
           }

       We can use the second program to exec the first as follows:

           $ cc myecho.c -o myecho
           $ cc execve.c -o execve
           $ ./execve ./myecho
           argv[0]: ./myecho
           argv[1]: hello
           argv[2]: world

       We can also use these programs to demonstrate the use of a script
       interpreter.  To do this we create a script whose "interpreter" is our
       myecho program:

           $ cat > script.sh
           #! ./myecho script-arg
           ^D
           $ chmod +x script.sh

       We can then use our program to exec the script:

           $ ./execve ./script.sh
           argv[0]: ./myecho
           argv[1]: script-arg
           argv[2]: ./script.sh
           argv[3]: hello
           argv[4]: world

SEE ALSO top

       chmod(2), fork(2), ptrace(2), execl(3), fexecve(3), getopt(3),
       credentials(7), environ(7), path_resolution(7), ld.so(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-27                           EXECVE(2)


_exit(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

_EXIT(2)                     Linux Programmer's Manual                    _EXIT(2)

NAME top

       _exit, _Exit - terminate the calling process

SYNOPSIS top

       #include <unistd.h>

       void _exit(int status);

       #include <stdlib.h>

       void _Exit(int status);

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

       _Exit():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The function _exit() terminates the calling process "immediately".  Any
       open file descriptors belonging to the process are closed; any children of
       the process are inherited by process 1, init, and the process's parent is
       sent a SIGCHLD signal.

       The value status is returned to the parent process as the process's exit
       status, and can be collected using one of the wait(2) family of calls.

       The function _Exit() is equivalent to _exit().

RETURN VALUE top

       These functions do not return.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD.  The function _Exit() was introduced by C99.

NOTES top

       For a discussion on the effects of an exit, the transmission of exit
       status, zombie processes, signals sent, and so on, see exit(3).

       The function _exit() is like exit(3), but does not call any functions
       registered with atexit(3) or on_exit(3).  Whether it flushes standard I/O
       buffers and removes temporary files created with tmpfile(3) is
       implementation-dependent.  On the other hand, _exit() does close open file
       descriptors, and this may cause an unknown delay, waiting for pending
       output to finish.  If the delay is undesired, it may be useful to call
       functions like tcflush(3) before calling _exit().  Whether any pending I/O
       is canceled, and which pending I/O may be canceled upon _exit(), is
       implementation-dependent.

       In glibc up to version 2.3, the _exit() wrapper function invoked the kernel
       system call of the same name.  Since glibc 2.3, the wrapper function
       invokes exit_group(2), in order to terminate all of the threads in a
       process.

SEE ALSO top

       execve(2), exit_group(2), fork(2), kill(2), wait(2), wait4(2), waitpid(2),
       atexit(3), exit(3), on_exit(3), termios(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                            _EXIT(2)


exit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

EXIT(3)                      Linux Programmer's Manual                     EXIT(3)

NAME top

       exit - cause normal process termination

SYNOPSIS top

       #include <stdlib.h>

       void exit(int status);

DESCRIPTION top

       The exit() function causes normal process termination and the value of
       status & 0377 is returned to the parent (see wait(2)).

       All functions registered with atexit(3) and on_exit(3) are called, in the
       reverse order of their registration.  (It is possible for one of these
       functions to use atexit(3) or on_exit(3) to register an additional function
       to be executed during exit processing; the new registration is added to the
       front of the list of functions that remain to be called.)  If one of these
       functions does not return (e.g., it calls _exit(2), or kills itself with a
       signal), then none of the remaining functions is called, and further exit
       processing (in particular, flushing of stdio(3) streams) is abandoned.  If
       a function has been registered multiple times using atexit(3) or
       on_exit(3), then it is called as many times as it was registered.

       All open stdio(3) streams are flushed and closed.  Files created by
       tmpfile(3) are removed.

       The C standard specifies two constants, EXIT_SUCCESS and EXIT_FAILURE, that
       may be passed to exit() to indicate successful or unsuccessful termination,
       respectively.

RETURN VALUE top

       The exit() function does not return.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001, C89, C99.

NOTES top

       It is undefined what happens if one of the functions registered using
       atexit(3) and on_exit(3) calls either exit() or longjmp(3).

       The use of EXIT_SUCCESS and EXIT_FAILURE is slightly more portable (to non-
       UNIX environments) than the use of 0 and some nonzero value like 1 or -1.
       In particular, VMS uses a different convention.

       BSD has attempted to standardize exit codes; see the file <sysexits.h>.

       After exit(), the exit status must be transmitted to the parent process.
       There are three cases.  If the parent has set SA_NOCLDWAIT, or has set the
       SIGCHLD handler to SIG_IGN, the status is discarded.  If the parent was
       waiting on the child it is notified of the exit status.  In both cases the
       exiting process dies immediately.  If the parent has not indicated that it
       is not interested in the exit status, but is not waiting, the exiting
       process turns into a "zombie" process (which is nothing but a container for
       the single byte representing the exit status) so that the parent can learn
       the exit status when it later calls one of the wait(2) functions.

       If the implementation supports the SIGCHLD signal, this signal is sent to
       the parent.  If the parent has set SA_NOCLDWAIT, it is undefined whether a
       SIGCHLD signal is sent.

       If the process is a session leader and its controlling terminal is the
       controlling terminal of the session, then each process in the foreground
       process group of this controlling terminal is sent a SIGHUP signal, and the
       terminal is disassociated from this session, allowing it to be acquired by
       a new controlling process.

       If the exit of the process causes a process group to become orphaned, and
       if any member of the newly orphaned process group is stopped, then a SIGHUP
       signal followed by a SIGCONT signal will be sent to each process in this
       process group.  See setpgid(2) for an explanation of orphaned process
       groups.

SEE ALSO top

       _exit(2), setpgid(2), wait(2), atexit(3), on_exit(3), tmpfile(3)

COLOPHON top

       This page is part of release 3.45 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                               2009-09-20                             EXIT(3)


exit_group(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

EXIT_GROUP(2)                Linux Programmer's Manual               EXIT_GROUP(2)

NAME top

       exit_group - exit all threads in a process

SYNOPSIS top

       #include <linux/unistd.h>

       void exit_group(int status);

DESCRIPTION top

       This system call is equivalent to exit(2) except that it terminates not
       only the calling thread, but all threads in the calling process's thread
       group.

RETURN VALUE top

       This system call does not return.

VERSIONS top

       This call is present since Linux 2.5.35.

CONFORMING TO top

       This call is Linux-specific.

NOTES top

       Since glibc 2.3, this is the system call invoked when the exit(2) wrapper
       function is called.

SEE ALSO top

       exit(2)

COLOPHON top

       This page is part of release 3.45 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                       EXIT_GROUP(2)


exp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

EXP(3)                       Linux Programmer's Manual                      EXP(3)

NAME top

       exp, expf, expl - base-e exponential function

SYNOPSIS top

       #include <math.h>

       double exp(double x);
       float expf(float x);
       long double expl(long double x);

       Link with -lm.

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

       expf(), expl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The exp() function returns the value of e (the base of natural logarithms)
       raised to the power of x.

RETURN VALUE top

       On success, these functions return the exponential value of x.

       If x is a NaN, a NaN is returned.

       If x is positive infinity, positive infinity is returned.

       If x is negative infinity, +0 is returned.

       If the result underflows, a range error occurs, and zero is returned.

       If the result overflows, a range error occurs, and the functions return
       +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL, respectively.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error, overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

       Range error, underflow
              errno is set to ERANGE.  An underflow floating-point exception
              (FE_UNDERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       cbrt(3), cexp(3), exp10(3), exp2(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                              EXP(3)


exp10(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

EXP10(3)                     Linux Programmer's Manual                    EXP10(3)

NAME top

       exp10, exp10f, exp10l - base-10 exponential function

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <math.h>

       double exp10(double x);
       float exp10f(float x);
       long double exp10l(long double x);

       Link with -lm.

DESCRIPTION top

       The exp10() function returns the value of 10 raised to the power of x.

RETURN VALUE top

       On success, these functions return the base-10 exponential value of x.

       For various special cases, including the handling of infinity and NaN, as
       well as overflows and underflows, see exp(3).

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       For a discussion of the errors that can occur for these functions, see
       exp(3).

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       These functions are GNU extensions.

SEE ALSO top

       cbrt(3), exp(3), exp2(3), log10(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-11                            EXP10(3)


exp2(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

EXP2(3)                      Linux Programmer's Manual                     EXP2(3)

NAME top

       exp2, exp2f, exp2l - base-2 exponential function

SYNOPSIS top

       #include <math.h>

       double exp2(double x);
       float exp2f(float x);
       long double exp2l(long double x);

       Link with -lm.

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

       exp2(), exp2f(), exp2l():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The exp2() function returns the value of 2 raised to the power of x.

RETURN VALUE top

       On success, these functions return the base-2 exponential value of x.

       For various special cases, including the handling of infinity and NaN, as
       well as overflows and underflows, see exp(3).

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       For a discussion of the errors that can occur for these functions, see
       exp(3).

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       cbrt(3), cexp2(3), exp(3), exp10(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             EXP2(3)


expm1(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

EXPM1(3)                     Linux Programmer's Manual                    EXPM1(3)

NAME top

       expm1, expm1f, expm1l - exponential minus 1

SYNOPSIS top

       #include <math.h>

       double expm1(double x);
       float expm1f(float x);
       long double expm1l(long double x);

       Link with -lm.

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

       expm1():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       expm1f(), expm1l():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       expm1(x) returns a value equivalent to

           exp(x) - 1

       It is computed in a way that is accurate even if the value of x is near
       zero--a case where exp(x) - 1 would be inaccurate due to subtraction of two
       numbers that are nearly equal.

RETURN VALUE top

       On success, these functions return exp(x) - 1.

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity, positive infinity is returned.

       If x is negative infinity, -1 is returned.

       If the result overflows, a range error occurs, and the functions return
       -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL, respectively.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error, overflow
              errno is set to ERANGE (but see BUGS).  An overflow floating-point
              exception (FE_OVERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.

BUGS top

       For some large negative x values (where the function result approaches -1),
       expm1() raises a bogus underflow floating-point exception.

       For some large positive x values, expm1() raises a bogus invalid floating-
       point exception in addition to the expected overflow exception, and returns
       a NaN instead of positive infinity.

       Before version 2.11, the glibc implementation did not set errno to ERANGE
       when a range error occurred.

SEE ALSO top

       exp(3), log(3), log1p(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-12                            EXPM1(3)


fabs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FABS(3)                      Linux Programmer's Manual                     FABS(3)

NAME top

       fabs, fabsf, fabsl - absolute value of floating-point number

SYNOPSIS top

       #include <math.h>

       double fabs(double x);
       float fabsf(float x);
       long double fabsl(long double x);

       Link with -lm.

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

       fabsf(), fabsl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The fabs() functions return the absolute value of the floating-point number
       x.

RETURN VALUE top

       These functions return the absolute value of x.

       If x is a NaN, a NaN is returned.

       If x is -0, +0 is returned.

       If x is negative infinity or positive infinity, positive infinity is
       returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       abs(3), cabs(3), ceil(3), floor(3), labs(3), rint(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             FABS(3)


faccessat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FACCESSAT(2)                 Linux Programmer's Manual                FACCESSAT(2)

NAME top

       faccessat - check user's permissions of a file relative to a directory file
       descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <unistd.h>

       int faccessat(int dirfd, const char *pathname, int mode, int flags);

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

       faccessat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The faccessat() system call operates in exactly the same way as access(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by access(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like access(2)).

       If pathname is absolute, then dirfd is ignored.

       flags is constructed by ORing together zero or more of the following
       values:

       AT_EACCESS
              Perform access checks using the effective user and group IDs.  By
              default, faccessat() uses the real IDs (like access(2)).

       AT_SYMLINK_NOFOLLOW
              If pathname is a symbolic link, do not dereference it: instead
              return information about the link itself.

RETURN VALUE top

       On success, (all requested permissions granted) faccessat() returns 0.  On
       error, -1 is returned and errno is set to indicate the error.

ERRORS top

       The same errors that occur for access(2) can also occur for faccessat().
       The following additional errors can occur for faccessat():

       EBADF  dirfd is not a valid file descriptor.

       EINVAL Invalid flag specified in flags.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       faccessat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for faccessat().

       Warning: faccessat() is subject to the same kinds of races as access(2) and
       euidaccess(3).

Glibc Notes

       The AT_EACCESS and AT_SYMLINK_NOFOLLOW flags are actually implemented
       within the glibc wrapper function for faccessat().  If either of these
       flags are specified, then the wrapper function employs fstatat(2) to
       determine access permissions.

SEE ALSO top

       access(2), openat(2), euidaccess(3), credentials(7), path_resolution(7),
       symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                        FACCESSAT(2)


fallocate(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FALLOCATE(2)                 Linux Programmer's Manual                FALLOCATE(2)

NAME top

       fallocate - manipulate file space

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <fcntl.h>

       int fallocate(int fd, int mode, off_t offset, off_t len);

DESCRIPTION top

       This is a nonportable, Linux-specific system call.  For the portable,
       POSIX.1-specified method of ensuring that space is allocated for a file,
       see posix_fallocate(3).

       fallocate() allows the caller to directly manipulate the allocated disk
       space for the file referred to by fd for the byte range starting at offset
       and continuing for len bytes.

       The mode argument determines the operation to be performed on the given
       range.  Details of the supported operations are given in the subsections
       below.

Allocating disk space

       The default operation (i.e., mode is zero) of fallocate() allocates and
       initializes to zero the disk space within the range specified by offset and
       len.  The file size (as reported by stat(2)) will be changed if offset+len
       is greater than the file size.  This default behavior closely resembles the
       behavior of the posix_fallocate(3) library function, and is intended as a
       method of optimally implementing that function.

       After a successful call, subsequent writes into the range specified by
       offset and len are guaranteed not to fail because of lack of disk space.

       If the FALLOC_FL_KEEP_SIZE flag is specified in mode, the behavior of the
       call is similar, but the file size will not be changed even if offset+len
       is greater than the file size.  Preallocating zeroed blocks beyond the end
       of the file in this manner is useful for optimizing append workloads.

       Because allocation is done in block size chunks, fallocate() may allocate a
       larger range of disk space than was specified.

Deallocating file space

       Specifying the FALLOC_FL_PUNCH_HOLE flag (available since Linux 2.6.38) in
       mode deallocates space (i.e., creates a hole) in the byte range starting at
       offset and continuing for len bytes.  Within the specified range, partial
       file system blocks are zeroed, and whole file system blocks are removed
       from the file.  After a successful call, subsequent reads from this range
       will return zeroes.

       The FALLOC_FL_PUNCH_HOLE flag must be ORed with FALLOC_FL_KEEP_SIZE in
       mode; in other words, even when punching off the end of the file, the file
       size (as reported by stat(2)) does not change.

       Not all file systems support FALLOC_FL_PUNCH_HOLE; if a file system doesn't
       support the operation, an error is returned.

RETURN VALUE top

       fallocate() returns zero on success, and -1 on failure.

ERRORS top

       EBADF  fd is not a valid file descriptor, or is not opened for writing.

       EFBIG  offset+len exceeds the maximum file size.

       EINTR  A signal was caught during execution.

       EINVAL offset was less than 0, or len was less than or equal to 0.

       EIO    An I/O error occurred while reading from or writing to a file
              system.

       ENODEV fd does not refer to a regular file or a directory.  (If fd is a
              pipe or FIFO, a different error results.)

       ENOSPC There is not enough space left on the device containing the file
              referred to by fd.

       ENOSYS This kernel does not implement fallocate().

       EOPNOTSUPP
              The file system containing the file referred to by fd does not
              support this operation; or the mode is not supported by the file
              system containing the file referred to by fd.

       EPERM  The file referred to by fd is marked immutable (see chattr(1)).  Or:
              mode specifies FALLOC_FL_PUNCH_HOLE and the file referred to by fd
              is marked append-only (see chattr(1)).

       ESPIPE fd refers to a pipe or FIFO.

VERSIONS top

       fallocate() is available on Linux since kernel 2.6.23.  Support is provided
       by glibc since version 2.10.

CONFORMING TO top

       fallocate() is Linux-specific.

SEE ALSO top

       ftruncate(2), posix_fadvise(3), posix_fallocate(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-23                        FALLOCATE(2)


fchmodat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FCHMODAT(2)                  Linux Programmer's Manual                 FCHMODAT(2)

NAME top

       fchmodat  -  change  permissions  of  a  file  relative to a directory file
       descriptor

SYNOPSIS top

       #include <fcntl.h>           /* Definition of AT_* constants */
       #include <sys/stat.h>

       int fchmodat(int dirfd, const char *pathname, mode_t mode, int flags);

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

       fchmodat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The fchmodat() system call operates in exactly the same way as chmod(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by chmod(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like chmod(2)).

       If pathname is absolute, then dirfd is ignored.

       flags can either be 0, or include the following flag:

       AT_SYMLINK_NOFOLLOW
              If pathname is a symbolic link, do not dereference it: instead
              operate on the link itself.  This flag is not currently implemented.

RETURN VALUE top

       On success, fchmodat() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for chmod(2) can also occur for fchmodat().  The
       following additional errors can occur for fchmodat():

       EBADF  dirfd is not a valid file descriptor.

       EINVAL Invalid flag specified in flags.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

       ENOTSUP
              flags specified AT_SYMLINK_NOFOLLOW, which is not supported.

VERSIONS top

       fchmodat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for fchmodat().

       The GNU C library wrapper function implements the POSIX-specified interface
       described in this page.  This interface differs from the underlying Linux
       system call, which does not have a flags argument.

SEE ALSO top

       chmod(2), openat(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-22                         FCHMODAT(2)


fchownat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FCHOWNAT(2)                  Linux Programmer's Manual                 FCHOWNAT(2)

NAME top

       fchownat - change ownership of a file relative to a directory file descrip-
       tor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <unistd.h>

       int fchownat(int dirfd, const char *pathname,
                    uid_t owner, gid_t group, int flags);

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

       fchownat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The fchownat() system call operates in exactly the same way as chown(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by chown(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like chown(2)).

       If pathname is absolute, then dirfd is ignored.

       flags can either be 0, or include the following flag:

       AT_SYMLINK_NOFOLLOW
              If pathname is a symbolic link, do not dereference it: instead
              operate on the link itself, like lchown(2).  (By default, fchownat()
              dereferences symbolic links, like chown(2).)

RETURN VALUE top

       On success, fchownat() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for chown(2) can also occur for fchownat().  The
       following additional errors can occur for fchownat():

       EBADF  dirfd is not a valid file descriptor.

       EINVAL Invalid flag specified in flags.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       fchownat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.  A similar system call exists on Solaris.

NOTES top

       See openat(2) for an explanation of the need for fchownat().

SEE ALSO top

       chown(2), openat(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                         FCHOWNAT(2)


fclose(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FCLOSE(3)                    Linux Programmer's Manual                   FCLOSE(3)

NAME top

       fclose - close a stream

SYNOPSIS top

       #include <stdio.h>

       int fclose(FILE *fp);

DESCRIPTION top

       The fclose() function flushes the stream pointed to by fp (writing any
       buffered output data using fflush(3)) and closes the underlying file
       descriptor.

RETURN VALUE top

       Upon successful completion 0 is returned.  Otherwise, EOF is returned and
       errno is set to indicate the error.  In either case any further access
       (including another call to fclose()) to the stream results in undefined
       behavior.

ERRORS top

       EBADF  The file descriptor underlying fp is not valid.

       The fclose() function may also fail and set errno for any of the errors
       specified for the routines close(2), write(2) or fflush(3).

CONFORMING TO top

       C89, C99.

NOTES top

       Note that fclose() only flushes the user space buffers provided by the C
       library.  To ensure that the data is physically stored on disk the kernel
       buffers must be flushed too, for example, with sync(2) or fsync(2).

SEE ALSO top

       close(2), fcloseall(3), fflush(3), fopen(3), setbuf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-02-23                           FCLOSE(3)


fcloseall(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FCLOSEALL(3)                 Linux Programmer's Manual                FCLOSEALL(3)

NAME top

       fcloseall - close all open streams

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <stdio.h>

       int fcloseall(void);

DESCRIPTION top

       The fcloseall() function closes all of the calling process's open streams.
       Buffered output for each stream is written before it is closed (as for
       fflush(3)); buffered input is discarded.

       The standard streams, stdin, stdout, and stderr are also closed.

RETURN VALUE top

       This function returns 0 if all files were successfully closed; on error,
       EOF is returned.

CONFORMING TO top

       This function is a GNU extension.

SEE ALSO top

       close(2), fclose(3), fflush(3), fopen(3), setbuf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2006-12-27                        FCLOSEALL(3)


fcntl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

FCNTL(2)                     Linux Programmer's Manual                    FCNTL(2)

NAME top

       fcntl - manipulate file descriptor

SYNOPSIS top

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

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

DESCRIPTION top

       fcntl() performs one of the operations described below on the open file
       descriptor fd.  The operation is determined 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
       int, 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 (int)
              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 (int; 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 (int)
              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)
              Get the file access mode and the file status flags; arg is ignored.

       F_SETFL (int)
              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 change only 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 negative, 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 processes 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 existing 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 terminates 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.

       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_GETOWN_EX, F_SETOWN_EX, 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 signals for events on file
              descriptor fd.  Process IDs are returned as positive values; process
              group IDs are returned as negative values (but see BUGS below).  arg
              is ignored.

       F_SETOWN (int)
              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".)

              The following was true in 2.6.x kernels up to and including kernel
              2.6.11:

                     If a nonzero value is given to F_SETSIG in a multithreaded
                     process running with a threading library that supports thread
                     groups (e.g., NPTL), then a positive value given to F_SETOWN
                     has a different meaning: instead of being a process ID
                     identifying a whole process, it is a thread ID identifying a
                     specific thread within a process.  Consequently, it may be
                     necessary to pass F_SETOWN the result of gettid(2) instead of
                     getpid(2) to get sensible results when F_SETSIG is used.  (In
                     current Linux threading implementations, a main thread's
                     thread ID is the same as its process ID.  This means that a
                     single-threaded program can equally use gettid(2) or
                     getpid(2) in this scenario.)  Note, however, that the
                     statements in this paragraph do not apply to the SIGURG
                     signal generated for out-of-band data on a socket: this
                     signal is always sent to either a process or a process group,
                     depending on the value given to F_SETOWN.

              The above behavior was accidentally dropped in Linux 2.6.12, and
              won't be restored.  From Linux 2.6.32 onward, use F_SETOWN_EX to
              target SIGIO and SIGURG signals at a particular thread.

       F_GETOWN_EX (struct f_owner_ex *) (since Linux 2.6.32)
              Return the current file descriptor owner settings as defined by a
              previous F_SETOWN_EX operation.  The information is returned in the
              structure pointed to by arg, which has the following form:

                  struct f_owner_ex {
                      int   type;
                      pid_t pid;
                  };

              The type field will have one of the values F_OWNER_TID, F_OWNER_PID,
              or F_OWNER_PGRP.  The pid field is a positive integer representing a
              thread ID, process ID, or process group ID.  See F_SETOWN_EX for
              more details.

       F_SETOWN_EX (struct f_owner_ex *) (since Linux 2.6.32)
              This operation performs a similar task to F_SETOWN.  It allows the
              caller to direct I/O availability signals to a specific thread,
              process, or process group.  The caller specifies the target of
              signals via arg, which is a pointer to a f_owner_ex structure.  The
              type field has one of the following values, which define how pid is
              interpreted:

              F_OWNER_TID
                     Send the signal to the thread whose thread ID (the value
                     returned by a call to clone(2) or gettid(2)) is specified in
                     pid.

              F_OWNER_PID
                     Send the signal to the process whose ID is specified in pid.

              F_OWNER_PGRP
                     Send the signal to the process group whose ID is specified in
                     pid.  (Note that, unlike with F_SETOWN, a process group ID is
                     specified as a positive value here.)

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

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

              By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for
              the signal handler (see sigaction(2)), extra information about I/O
              events is passed to the handler in a siginfo_t structure.  If the
              si_code field indicates the source is SI_SIGIO, the si_fd field
              gives the file descriptor associated with the event.  Otherwise,
              there is no indication which file descriptors are pending, and you
              should use the usual mechanisms (select(2), poll(2), read(2) with
              O_NONBLOCK set etc.) to determine which file descriptors are
              available for I/O.

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

              Note that Linux imposes a limit on the number of real-time signals
              that may be queued to a process (see getrlimit(2) and signal(7)) and
              if this limit is reached, then the kernel reverts to delivering
              SIGIO, and this signal is delivered to the entire process rather
              than to a specific thread.

       Using these mechanisms, a program can implement fully asynchronous I/O
       without using select(2) or poll(2) most of the time.

       The use of O_ASYNC, F_GETOWN, F_SETOWN is specific to BSD and Linux.
       F_GETOWN_EX, F_SETOWN_EX, F_GETSIG, and F_SETSIG are Linux-specific.  POSIX
       has asynchronous I/O and the aio_sigevent structure to achieve similar
       things; these are also available in Linux as part of the GNU C Library
       (Glibc).

Leases

       F_SETLEASE and F_GETLEASE (Linux 2.4 onward) 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
       mechanism whereby the process holding the lease (the "lease holder") is
       notified (via delivery of a signal) when a process (the "lease breaker")
       tries to open(2) or truncate(2) the file referred to by that file
       descriptor.

       F_SETLEASE (int)
              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 reading 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 a lease break has been initiated, F_GETLEASE returns the target lease
       type (either F_RDLCK or F_UNLCK, depending on what would be compatible with
       the lease breaker) until the lease holder voluntarily downgrades or removes
       the lease or the kernel forcibly does so after the lease break timer
       expires.

       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 (int)
              (Linux 2.4 onward) 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 before including any header files.)

              Directory notifications are normally "one-shot", and the application
              must reregister 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 monitored.  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).

Changing the capacity of a pipe

       F_SETPIPE_SZ (int; since Linux 2.6.35)
              Change the capacity of the pipe referred to by fd to be at least arg
              bytes.  An unprivileged process can adjust the pipe capacity to any
              value between the system page size and the limit defined in
              /proc/sys/fs/pipe-max-size (see proc(5)).  Attempts to set the pipe
              capacity below the page size are silently rounded up to the page
              size.  Attempts by an unprivileged process to set the pipe capacity
              above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM;
              a privileged process (CAP_SYS_RESOURCE) can override the limit.
              When allocating the buffer for the pipe, the kernel may use a
              capacity larger than arg, if that is convenient for the
              implementation.  The F_GETPIPE_SZ operation returns the actual size
              used.  Attempting to set the pipe capacity smaller than the amount
              of buffer space currently used to store data produces the error
              EBUSY.

       F_GETPIPE_SZ (void; since Linux 2.6.35)
              Return (as the function result) the capacity of the pipe referred to
              by fd.

RETURN VALUE top

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

       F_DUPFD  The new descriptor.

       F_GETFD  Value of file descriptor flags.

       F_GETFL  Value of file status 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.

       F_GETPIPE_SZ
                The pipe capacity.

       All other commands
                Zero.

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

ERRORS top

       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 top

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

       F_GETOWN and F_SETOWN are specified in POSIX.1-2001.  (To get their
       definitions, define BSD_SOURCE, or _XOPEN_SOURCE with the value 500 or
       greater, or define _POSIX_C_SOURCE with the value 200809L or greater.)

       F_DUPFD_CLOEXEC is specified in POSIX.1-2008.  (To get this definition,
       define _POSIX_C_SOURCE with the value 200809L or greater, or _XOPEN_SOURCE
       with the value 700 or greater.)

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

NOTES top

       The original Linux fcntl() system call was not designed to handle large
       file offsets (in the flock structure).  Consequently, an fcntl64() system
       call was added in Linux 2.4.  The newer system call employs a different
       structure for file locking, flock64, and corresponding commands, F_GETLK64,
       F_SETLK64, and F_SETLKW64.  However, these details can be ignored by
       applications using glibc, whose fcntl() wrapper function transparently
       employs the more recent system call where it is available.

       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 top

       A limitation of the Linux system call conventions on some architectures
       (notably i386) means that if a (negative) process group ID to be returned
       by F_GETOWN falls in the range -1 to -4095, then the return value is
       wrongly interpreted by glibc as an error in the system call; that is, the
       return value of fcntl() will be -1, and errno will contain the (positive)
       process group ID.  The Linux-specific F_GETOWN_EX operation avoids this
       problem.  Since glibc version 2.11, glibc makes the kernel F_GETOWN problem
       invisible by implementing F_GETOWN using F_GETOWN_EX.

       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 mandatory locking.

SEE ALSO top

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

       locks.txt, mandatory-locking.txt, and dnotify.txt in the Linux kernel
       source directory Documentation/filesystems/ (on older kernels, these files
       are directly under the Documentation/ directory, and mandatory-locking.txt
       is called mandatory.txt)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-15                            FCNTL(2)


fd(4) - Linux manual page

NAME | CONFIGURATION | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FD(4)                        Linux Programmer's Manual                       FD(4)

NAME top

       fd - floppy disk device

CONFIGURATION top

       Floppy  drives  are  block devices with major number 2.  Typically they are
       owned by root.floppy (i.e., user root, group floppy) and have  either  mode
       0660  (access  checking  via  group membership) or mode 0666 (everybody has
       access).  The minor numbers encode the device type, drive number, and  con-
       troller  number.  For each device type (that is, combination of density and
       track count) there is a base minor number.  To this base  number,  add  the
       drive's  number  on its controller and 128 if the drive is on the secondary
       controller.  In the following device tables, n represents the drive number.

       Warning: If you use formats with more tracks than supported by your  drive,
       you  may  cause  it mechanical damage.  Trying once if more tracks than the
       usual 40/80 are supported should not damage it, but no  warranty  is  given
       for  that.  If you are not sure, don't create device entries for those for-
       mats, so as to prevent their usage.

       Drive-independent device files which automatically detect the media  format
       and capacity:

       Name   Base minor #
       --------------------
       fdn    0

       5.25 inch double density device files:

       Name         Capac.   Cyl.   Sect.   Heads   Base minor #
       ----------------------------------------------------------
       fdnd360      360K     40     9       2       4

       5.25 inch high density device files:

       Name         Capac.   Cyl.   Sect.   Heads   Base minor #
       ----------------------------------------------------------
       fdnh360      360K     40     9       2       20
       fdnh410      410K     41     10      2       48
       fdnh420      420K     42     10      2       64
       fdnh720      720K     80     9       2       24
       fdnh880      880K     80     11      2       80
       fdnh1200     1200K    80     15      2       8
       fdnh1440     1440K    80     18      2       40
       fdnh1476     1476K    82     18      2       56
       fdnh1494     1494K    83     18      2       72
       fdnh1600     1600K    80     20      2       92

       3.5 inch double density device files:

       Name         Capac.   Cyl.   Sect.   Heads   Base minor #
       ----------------------------------------------------------
       fdnD360      360K     80     9       1       12
       fdnD720      720K     80     9       2       16
       fdnD800      800K     80     10      2       120
       fdnD1040     1040K    80     13      2       84
       fdnD1120     1120K    80     14      2       88

       3.5 inch high density device files:

       Name         Capac.   Cyl.   Sect.   Heads   Base minor #
       ----------------------------------------------------------

       fdnH360      360K     40     9       2       12
       fdnH720      720K     80     9       2       16
       fdnH820      820K     82     10      2       52
       fdnH830      830K     83     10      2       68
       fdnH1440     1440K    80     18      2       28
       fdnH1600     1600K    80     20      2       124
       fdnH1680     1680K    80     21      2       44
       fdnH1722     1722K    82     21      2       60
       fdnH1743     1743K    83     21      2       76
       fdnH1760     1760K    80     22      2       96
       fdnH1840     1840K    80     23      2       116
       fdnH1920     1920K    80     24      2       100

       3.5 inch extra density device files:

       Name         Capac.   Cyl.   Sect.   Heads   Base minor #
       ----------------------------------------------------------
       fdnE2880     2880K    80     36      2       32
       fdnCompaQ    2880K    80     36      2       36
       fdnE3200     3200K    80     40      2       104
       fdnE3520     3520K    80     44      2       108
       fdnE3840     3840K    80     48      2       112

DESCRIPTION top

       fd special files access the floppy disk drives in raw mode.  The following
       ioctl(2) calls are supported by fd devices:

       FDCLRPRM
              clears the media information of a drive (geometry of disk in drive).

       FDSETPRM
              sets the media information of a drive.  The media information will
              be lost when the media is changed.

       FDDEFPRM
              sets the media information of a drive (geometry of disk in drive).
              The media information will not be lost when the media is changed.
              This will disable autodetection.  In order to reenable
              autodetection, you have to issue an FDCLRPRM.

       FDGETDRVTYP
              returns the type of a drive (name parameter).  For formats which
              work in several drive types, FDGETDRVTYP returns a name which is
              appropriate for the oldest drive type which supports this format.

       FDFLUSH
              invalidates the buffer cache for the given drive.

       FDSETMAXERRS
              sets the error thresholds for reporting errors, aborting the
              operation, recalibrating, resetting, and reading sector by sector.

       FDSETMAXERRS
              gets the current error thresholds.

       FDGETDRVTYP
              gets the internal name of the drive.

       FDWERRORCLR
              clears the write error statistics.

       FDWERRORGET
              reads the write error statistics.  These include the total number of
              write errors, the location and disk of the first write error, and
              the location and disk of the last write error.  Disks are identified
              by a generation number which is incremented at (almost) each disk
              change.

       FDTWADDLE
              Switch the drive motor off for a few microseconds.  This might be
              needed in order to access a disk whose sectors are too close
              together.

       FDSETDRVPRM
              sets various drive parameters.

       FDGETDRVPRM
              reads these parameters back.

       FDGETDRVSTAT
              gets the cached drive state (disk changed, write protected et al.)

       FDPOLLDRVSTAT
              polls the drive and return its state.

       FDGETFDCSTAT
              gets the floppy controller state.

       FDRESET
              resets the floppy controller under certain conditions.

       FDRAWCMD
              sends a raw command to the floppy controller.

       For more precise information, consult also the <linux/fd.h> and
       <linux/fdreg.h> include files, as well as the floppycontrol(1) manual page.

FILES top

       /dev/fd*

NOTES top

       The various formats permit reading and writing many types of disks.
       However, if a floppy is formatted with an inter-sector gap that is too
       small, performance may drop, to the point of needing a few seconds to
       access an entire track.  To prevent this, use interleaved formats.

       It is not possible to read floppies which are formatted using GCR (group
       code recording), which is used by Apple II and Macintosh computers (800k
       disks).

       Reading floppies which are hard sectored (one hole per sector, with the
       index hole being a little skewed) is not supported.  This used to be common
       with older 8-inch floppies.

SEE ALSO top

       chown(1), floppycontrol(1), getfdprm(1), mknod(1), superformat(1),
       mount(8), setfdprm(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-08-29                               FD(4)


fsync(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | AVAILABILITY | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FSYNC(2)                     Linux Programmer's Manual                    FSYNC(2)

NAME top

       fsync, fdatasync - synchronize a file's in-core state with storage device

SYNOPSIS top

       #include <unistd.h>

       int fsync(int fd);

       int fdatasync(int fd);

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

       fsync(): _BSD_SOURCE || _XOPEN_SOURCE
                || /* since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
       fdatasync(): _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500

DESCRIPTION top

       fsync() transfers ("flushes") all modified in-core data of (i.e., modified
       buffer cache pages for) the file referred to by the file descriptor fd to
       the disk device (or other permanent storage device) so that all changed
       information can be retrieved even after the system crashed or was rebooted.
       This includes writing through or flushing a disk cache if present.  The
       call blocks until the device reports that the transfer has completed.  It
       also flushes metadata information associated with the file (see stat(2)).

       Calling fsync() does not necessarily ensure that the entry in the directory
       containing the file has also reached disk.  For that an explicit fsync() on
       a file descriptor for the directory is also needed.

       fdatasync() is similar to fsync(), but does not flush modified metadata
       unless that metadata is needed in order to allow a subsequent data
       retrieval to be correctly handled.  For example, changes to st_atime or
       st_mtime (respectively, time of last access and time of last modification;
       see stat(2)) do not require flushing because they are not necessary for a
       subsequent data read to be handled correctly.  On the other hand, a change
       to the file size (st_size, as made by say ftruncate(2)), would require a
       metadata flush.

       The aim of fdatasync() is to reduce disk activity for applications that do
       not require all metadata to be synchronized with the disk.

RETURN VALUE top

       On success, these system calls return zero.  On error, -1 is returned, and
       errno is set appropriately.

ERRORS top

       EBADF  fd is not a valid open file descriptor.

       EIO    An error occurred during synchronization.

       EROFS, EINVAL
              fd is bound to a special file which does not support
              synchronization.

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

AVAILABILITY top

       On POSIX systems on which fdatasync() is available, _POSIX_SYNCHRONIZED_IO
       is defined in <unistd.h> to a value greater than 0.  (See also sysconf(3).)

NOTES top

       On some UNIX systems (but not Linux), fd must be a writable file
       descriptor.

       In Linux 2.2 and earlier, fdatasync() is equivalent to fsync(), and so has
       no performance advantage.

       The fsync() implementations in older kernels and lesser used filesystems
       does not know how to flush disk caches.  In these cases disk caches need to
       be disabled using hdparm(8) or sdparm(8) to guarantee safe operation.

SEE ALSO top

       bdflush(2), open(2), sync(2), sync_file_range(2), hdparm(8), mount(8),
       sync(8), update(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-02-27                            FSYNC(2)


fdim(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FDIM(3)                      Linux Programmer's Manual                     FDIM(3)

NAME top

       fdim, fdimf, fdiml - positive difference

SYNOPSIS top

       #include <math.h>

       double fdim(double x, double y);
       float fdimf(float x, float y);
       long double fdiml(long double x, long double y);

       Link with -lm.

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

       fdimf(), fdiml():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions return the positive difference, max(x-y,0), between their
       arguments.

RETURN VALUE top

       On success, these functions return the positive difference.

       If x or y is a NaN, a NaN is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result overflow
              An overflow floating-point exception (FE_OVERFLOW) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       fmax(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             FDIM(3)


fopen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

FOPEN(3)                     Linux Programmer's Manual                    FOPEN(3)

NAME top

       fopen, fdopen, freopen - stream open functions

SYNOPSIS top

       #include <stdio.h>

       FILE *fopen(const char *path, const char *mode);

       FILE *fdopen(int fd, const char *mode);

       FILE *freopen(const char *path, const char *mode, FILE *stream);

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

       fdopen(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The fopen() function opens the file whose name is the string pointed to by
       path and associates a stream with it.

       The argument mode points to a string beginning with one of the following
       sequences (possibly followed by additional characters, as described below):

       r      Open text file for reading.  The stream is positioned at the
              beginning of the file.

       r+     Open for reading and writing.  The stream is positioned at the
              beginning of the file.

       w      Truncate file to zero length or create text file for writing.  The
              stream is positioned at the beginning of the file.

       w+     Open for reading and writing.  The file is created if it does not
              exist, otherwise it is truncated.  The stream is positioned at the
              beginning of the file.

       a      Open for appending (writing at end of file).  The file is created if
              it does not exist.  The stream is positioned at the end of the file.

       a+     Open for reading and appending (writing at end of file).  The file
              is created if it does not exist.  The initial file position for
              reading is at the beginning of the file, but output is always
              appended to the end of the file.

       The mode string can also include the letter 'b' either as a last character
       or as a character between the characters in any of the two-character
       strings described above.  This is strictly for compatibility with C89 and
       has no effect; the 'b' is ignored on all POSIX conforming systems,
       including Linux.  (Other systems may treat text files and binary files
       differently, and adding the 'b' may be a good idea if you do I/O to a
       binary file and expect that your program may be ported to non-UNIX
       environments.)

       See NOTES below for details of glibc extensions for mode.

       Any created files will have mode S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP |
       S_IROTH | S_IWOTH (0666), as modified by the process's umask value (see
       umask(2)).

       Reads and writes may be intermixed on read/write streams in any order.
       Note that ANSI C requires that a file positioning function intervene
       between output and input, unless an input operation encounters end-of-file.
       (If this condition is not met, then a read is allowed to return the result
       of writes other than the most recent.)  Therefore it is good practice (and
       indeed sometimes necessary under Linux) to put an fseek(3) or fgetpos(3)
       operation between write and read operations on such a stream.  This
       operation may be an apparent no-op (as in fseek(..., 0L, SEEK_CUR) called
       for its synchronizing side effect.

       Opening a file in append mode (a as the first character of mode) causes all
       subsequent write operations to this stream to occur at end-of-file, as if
       preceded the call:

           fseek(stream, 0, SEEK_END);

       The fdopen() function associates a stream with the existing file
       descriptor, fd.  The mode of the stream (one of the values "r", "r+", "w",
       "w+", "a", "a+") must be compatible with the mode of the file descriptor.
       The file position indicator of the new stream is set to that belonging to
       fd, and the error and end-of-file indicators are cleared.  Modes "w" or
       "w+" do not cause truncation of the file.  The file descriptor is not
       dup'ed, and will be closed when the stream created by fdopen() is closed.
       The result of applying fdopen() to a shared memory object is undefined.

       The freopen() function opens the file whose name is the string pointed to
       by path and associates the stream pointed to by stream with it.  The
       original stream (if it exists) is closed.  The mode argument is used just
       as in the fopen() function.  The primary use of the freopen() function is
       to change the file associated with a standard text stream (stderr, stdin,
       or stdout).

RETURN VALUE top

       Upon successful completion fopen(), fdopen() and freopen() return a FILE
       pointer.  Otherwise, NULL is returned and errno is set to indicate the
       error.

ERRORS top

       EINVAL The mode provided to fopen(), fdopen(), or freopen() was invalid.

       The fopen(), fdopen() and freopen() functions may also fail and set errno
       for any of the errors specified for the routine malloc(3).

       The fopen() function may also fail and set errno for any of the errors
       specified for the routine open(2).

       The fdopen() function may also fail and set errno for any of the errors
       specified for the routine fcntl(2).

       The freopen() function may also fail and set errno for any of the errors
       specified for the routines open(2), fclose(3) and fflush(3).

CONFORMING TO top

       The fopen() and freopen() functions conform to C89.  The fdopen() function
       conforms to POSIX.1-1990.

NOTES top

Glibc Notes

       The GNU C library allows the following extensions for the string specified
       in mode:

       c (since glibc 2.3.3)
              Do not make the open operation, or subsequent read and write
              operations, thread cancellation points.  This flag is ignored for
              fdopen().

       e (since glibc 2.7)
              Open the file with the O_CLOEXEC flag.  See open(2) for more
              information.  This flag is ignored for fdopen().

       m (since glibc 2.3)
              Attempt to access the file using mmap(2), rather than I/O system
              calls (read(2), write(2)).  Currently, use of mmap(2) is only
              attempted for a file opened for reading.

       x      Open the file exclusively (like the O_EXCL flag of open(2)).  If the
              file already exists, fopen() fails, and sets errno to EEXIST.  This
              flag is ignored for fdopen().

       In addition to the above characters, fopen() and freopen() support the
       following syntax in mode:

           ,ccs=[22mstring[0m

       The given string is taken as the name of a coded character set and the
       stream is marked as wide-oriented.  Thereafter, internal conversion
       functions convert I/O to and from the character set string.  If the
       ,ccs=string syntax is not specified, then the wide-orientation of the
       stream is determined by the first file operation.  If that operation is a
       wide-character operation, the stream is marked wide-oriented, and functions
       to convert to the coded character set are loaded.

BUGS          top
       When parsing for individual flag characters in mode (i.e., the characters
       preceding the "ccs" specification), the glibc implementation of fopen() and
       freopen() limits the number of characters examined in mode to 7 (or, in
       glibc versions before 2.14, to 6, which was not enough to include possible
       specifications such as "rb+cmxe").  The current implementation of fdopen()
       parses at most 5 characters in mode.

SEE ALSO          top
       open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3)

COLOPHON          top
       This page is part of release 3.45 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/.

GNU                                 2012-04-22                            FOPEN(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


opendir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

OPENDIR(3)                   Linux Programmer's Manual                  OPENDIR(3)

NAME top

       opendir, fdopendir - open a directory

SYNOPSIS top

       #include <sys/types.h>
       #include <dirent.h>

       DIR *opendir(const char *name);
       DIR *fdopendir(int fd);

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

       fdopendir():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The opendir() function opens a directory stream corresponding to the
       directory name, and returns a pointer to the directory stream.  The stream
       is positioned at the first entry in the directory.

       The fdopendir() function is like opendir(), but returns a directory stream
       for the directory referred to by the open file descriptor fd.  After a
       successful call to fdopendir(), fd is used internally by the
       implementation, and should not otherwise be used by the application.

RETURN VALUE top

       The opendir() and fdopendir() functions return a pointer to the directory
       stream.  On error, NULL is returned, and errno is set appropriately.

ERRORS top

       EACCES Permission denied.

       EBADF  fd is not a valid file descriptor opened for reading.

       EMFILE Too many file descriptors in use by process.

       ENFILE Too many files are currently open in the system.

       ENOENT Directory does not exist, or name is an empty string.

       ENOMEM Insufficient memory to complete the operation.

       ENOTDIR
              name is not a directory.

VERSIONS top

       fdopendir() is available in glibc since version 2.4.

CONFORMING TO top

       opendir() is present on SVr4, 4.3BSD, and specified in POSIX.1-2001.
       fdopendir() is specified in POSIX.1-2008.

NOTES top

       The underlying file descriptor of the directory stream can be obtained
       using dirfd(3).

       The opendir() function sets the close-on-exec flag for the file descriptor
       underlying the DIR *.  The fdopendir() function leaves the setting of the
       close-on-exec flag unchanged for the file descriptor, fd.  POSIX.1-200x
       leaves it unspecified whether a successful call to fdopendir() will set the
       close-on-exec flag for the file descriptor, fd.

SEE ALSO top

       open(2), closedir(3), dirfd(3), readdir(3), rewinddir(3), scandir(3),
       seekdir(3), telldir(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-06-20                          OPENDIR(3)


select(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SELECT(2)                    Linux Programmer's Manual                   SELECT(2)

NAME top

       select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O multi-
       plexing

SYNOPSIS top

       /* According to POSIX.1-2001 */
       #include <sys/select.h>

       /* According to earlier standards */
       #include <sys/time.h>
       #include <sys/types.h>
       #include <unistd.h>

       int select(int nfds, fd_set *readfds, fd_set *writefds,
                  fd_set *exceptfds, struct timeval *timeout);

       void FD_CLR(int fd, fd_set *set);
       int  FD_ISSET(int fd, fd_set *set);
       void FD_SET(int fd, fd_set *set);
       void FD_ZERO(fd_set *set);

       #include <sys/select.h>

       int pselect(int nfds, fd_set *readfds, fd_set *writefds,
                   fd_set *exceptfds, const struct timespec *timeout,
                   const sigset_t *sigmask);

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

       pselect(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       select() and pselect() allow a program to monitor multiple file
       descriptors, waiting until one or more of the file descriptors become
       "ready" for some class of I/O operation (e.g., input possible).  A file
       descriptor is considered ready if it is possible to perform the
       corresponding I/O operation (e.g., read(2)) without blocking.

       The operation of select() and pselect() is identical, other than these
       three differences:

       (i)    select() uses a timeout that is a struct timeval (with seconds and
              microseconds), while pselect() uses a struct timespec (with seconds
              and nanoseconds).

       (ii)   select() may update the timeout argument to indicate how much time
              was left.  pselect() does not change this argument.

       (iii)  select() has no sigmask argument, and behaves as pselect() called
              with NULL sigmask.

       Three independent sets of file descriptors are watched.  Those listed in
       readfds will be watched to see if characters become available for reading
       (more precisely, to see if a read will not block; in particular, a file
       descriptor is also ready on end-of-file), those in writefds will be watched
       to see if a write will not block, and those in exceptfds will be watched
       for exceptions.  On exit, the sets are modified in place to indicate which
       file descriptors actually changed status.  Each of the three file
       descriptor sets may be specified as NULL if no file descriptors are to be
       watched for the corresponding class of events.

       Four macros are provided to manipulate the sets.  FD_ZERO() clears a set.
       FD_SET() and FD_CLR() respectively add and remove a given file descriptor
       from a set.  FD_ISSET() tests to see if a file descriptor is part of the
       set; this is useful after select() returns.

       nfds is the highest-numbered file descriptor in any of the three sets, plus
       1.

       The timeout argument specifies the minimum interval that select() should
       block waiting for a file descriptor to become ready.  (This interval will
       be rounded up to the system clock granularity, and kernel scheduling delays
       mean that the blocking interval may overrun by a small amount.)  If both
       fields of the timeval structure are zero, then select() returns
       immediately.  (This is useful for polling.)  If timeout is NULL (no
       timeout), select() can block indefinitely.

       sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is not
       NULL, then pselect() first replaces the current signal mask by the one
       pointed to by sigmask, then does the "select" function, and then restores
       the original signal mask.

       Other than the difference in the precision of the timeout argument, the
       following pselect() call:

           ready = pselect(nfds, &readfds, &writefds, &exceptfds,
                           timeout, &sigmask);

       is equivalent to atomically executing the following calls:

           sigset_t origmask;

           pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
           ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
           pthread_sigmask(SIG_SETMASK, &origmask, NULL);

       The reason that pselect() is needed is that if one wants to wait for either
       a signal or for a file descriptor to become ready, then an atomic test is
       needed to prevent race conditions.  (Suppose the signal handler sets a
       global flag and returns.  Then a test of this global flag followed by a
       call of select() could hang indefinitely if the signal arrived just after
       the test but just before the call.  By contrast, pselect() allows one to
       first block signals, handle the signals that have come in, then call
       pselect() with the desired sigmask, avoiding the race.)

The timeout

       The time structures involved are defined in <sys/time.h> and look like

           struct timeval {
               long    tv_sec;         /* seconds */
               long    tv_usec;        /* microseconds */
           };

       and

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

       (However, see below on the POSIX.1-2001 versions.)

       Some code calls select() with all three sets empty, nfds zero, and a non-
       NULL timeout as a fairly portable way to sleep with subsecond precision.

       On Linux, select() modifies timeout to reflect the amount of time not
       slept; most other implementations do not do this.  (POSIX.1-2001 permits
       either behavior.)  This causes problems both when Linux code which reads
       timeout is ported to other operating systems, and when code is ported to
       Linux that reuses a struct timeval for multiple select()s in a loop without
       reinitializing it.  Consider timeout to be undefined after select()
       returns.

RETURN VALUE top

       On success, select() and pselect() return the number of file descriptors
       contained in the three returned descriptor sets (that is, the total number
       of bits that are set in readfds, writefds, exceptfds) which may be zero if
       the timeout expires before anything interesting happens.  On error, -1 is
       returned, and errno is set appropriately; the sets and timeout become
       undefined, so do not rely on their contents after an error.

ERRORS top

       EBADF  An invalid file descriptor was given in one of the sets.  (Perhaps a
              file descriptor that was already closed, or one on which an error
              has occurred.)

       EINTR  A signal was caught; see signal(7).

       EINVAL nfds is negative or the value contained within timeout is invalid.

       ENOMEM unable to allocate memory for internal tables.

VERSIONS top

       pselect() was added to Linux in kernel 2.6.16.  Prior to this, pselect()
       was emulated in glibc (but see BUGS).

CONFORMING TO top

       select() conforms to POSIX.1-2001 and 4.4BSD (select() first appeared in
       4.2BSD).  Generally portable to/from non-BSD systems supporting clones of
       the BSD socket layer (including System V variants).  However, note that the
       System V variant typically sets the timeout variable before exit, but the
       BSD variant does not.

       pselect() is defined in POSIX.1g, and in POSIX.1-2001.

NOTES top

       An fd_set is a fixed size buffer.  Executing FD_CLR() or FD_SET() with a
       value of fd that is negative or is equal to or larger than FD_SETSIZE will
       result in undefined behavior.  Moreover, POSIX requires fd to be a valid
       file descriptor.

       Concerning the types involved, the classical situation is that the two
       fields of a timeval structure are typed as long (as shown above), and the
       structure is defined in <sys/time.h>.  The POSIX.1-2001 situation is

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

       where the structure is defined in <sys/select.h> and the data types time_t
       and suseconds_t are defined in <sys/types.h>.

       Concerning prototypes, the classical situation is that one should include
       <time.h> for select().  The POSIX.1-2001 situation is that one should
       include <sys/select.h> for select() and pselect().

       Libc4 and libc5 do not have a <sys/select.h> header; under glibc 2.0 and
       later this header exists.  Under glibc 2.0 it unconditionally gives the
       wrong prototype for pselect().  Under glibc 2.1 to 2.2.1 it gives pselect()
       when _GNU_SOURCE is defined.  Since glibc 2.2.2 the requirements are as
       shown in the SYNOPSIS.

Multithreaded applications

       If a file descriptor being monitored by select() is closed in another
       thread, the result is unspecified.  On some UNIX systems, select() unblocks
       and returns, with an indication that the file descriptor is ready (a
       subsequent I/O operation will likely fail with an error, unless another the
       file descriptor reopened between the time select() returned and the I/O
       operations was performed).  On Linux (and some other systems), closing the
       file descriptor in another thread has no effect on select().  In summary,
       any application that relies on a particular behavior in this scenario must
       be considered buggy.

Linux Notes

       The pselect() interface described in this page is implemented by glibc.
       The underlying Linux system call is named pselect6().  This system call has
       somewhat different behavior from the glibc wrapper function.

       The Linux pselect6() 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 pselect() function does not modify its timeout argument; this is the
       behavior required by POSIX.1-2001.

       The final argument of the pselect6() system call is not a sigset_t *
       pointer, but is instead a structure of the form:

           struct {
               const sigset_t *ss;     /* Pointer to signal set */
               size_t          ss_len; /* Size (in bytes) of object pointed
                                          to by 'ss' */
           };

       This allows the system call to obtain both a pointer to the signal set and
       its size, while allowing for the fact that most architectures support a
       maximum of 6 arguments to a system call.

BUGS top

       Glibc 2.0 provided a version of pselect() that did not take a sigmask
       argument.

       Starting with version 2.1, glibc provided an emulation of pselect() that
       was implemented using sigprocmask(2) and select().  This implementation
       remained vulnerable to the very race condition that pselect() was designed
       to prevent.  Modern versions of glibc use the (race-free) pselect() system
       call on kernels where it is provided.

       On systems that lack pselect(), reliable (and more portable) signal
       trapping can be achieved using the self-pipe trick.  In this technique, a
       signal handler writes a byte to a pipe whose other end is monitored by
       select() in the main program.  (To avoid possibly blocking when writing to
       a pipe that may be full or reading from a pipe that may be empty,
       nonblocking I/O is used when reading from and writing to the pipe.)

       Under Linux, select() may report a socket file descriptor as "ready for
       reading", while nevertheless a subsequent read blocks.  This could for
       example happen when data has arrived but upon examination has wrong
       checksum and is discarded.  There may be other circumstances in which a
       file descriptor is spuriously reported as ready.  Thus it may be safer to
       use O_NONBLOCK on sockets that should not block.

       On Linux, select() also modifies timeout if the call is interrupted by a
       signal handler (i.e., the EINTR error return).  This is not permitted by
       POSIX.1-2001.  The Linux pselect() system call has the same behavior, but
       the glibc wrapper hides this behavior by internally copying the timeout to
       a local variable and passing that variable to the system call.

EXAMPLE top

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

       int
       main(void)
       {
           fd_set rfds;
           struct timeval tv;
           int retval;

           /* Watch stdin (fd 0) to see when it has input. */
           FD_ZERO(&rfds);
           FD_SET(0, &rfds);

           /* Wait up to five seconds. */
           tv.tv_sec = 5;
           tv.tv_usec = 0;

           retval = select(1, &rfds, NULL, NULL, &tv);
           /* Don't rely on the value of tv now! */

           if (retval == -1)
               perror("select()");
           else if (retval)
               printf("Data is available now.\n");
               /* FD_ISSET(0, &rfds) will be true. */
           else
               printf("No data within five seconds.\n");

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       accept(2), connect(2), poll(2), read(2), recv(2), send(2), sigprocmask(2),
       write(2), epoll(7), time(7)

       For a tutorial with discussion and examples, see select_tut(2).

COLOPHON top

       This page is part of release 3.45 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                               2012-08-17                           SELECT(2)


feature_test_macros(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FEATURE_TEST_MACROS(7)       Linux Programmer's Manual      FEATURE_TEST_MACROS(7)

NAME top

       feature_test_macros - feature test macros

SYNOPSIS top

       #include <features.h>

DESCRIPTION top

       Feature test macros allow the programmer to control the definitions that
       are exposed by system header files when a program is compiled.

       NOTE: In order to be effective, a feature test macro must be defined before
       including any header files.  This can be done either in the compilation
       command (cc -DMACRO=value) or by defining the macro within the source code
       before including any headers.

       Some feature test macros are useful for creating portable applications, by
       preventing nonstandard definitions from being exposed.  Other macros can be
       used to expose nonstandard definitions that are not exposed by default.
       The precise effects of each of the feature test macros described below can
       be ascertained by inspecting the <features.h> header file.

Specification of feature test macro requirements in manual pages

       When a function requires that a feature test macro is defined, the manual
       page SYNOPSIS typically includes a note of the following form (this example
       from the acct(2) manual page):

               #include <unistd.h>

               int acct(const char *filename);

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

               acct(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

       The || means that in order to obtain the declaration of acct(2) from
       <unistd.h>, either of the following macro definitions must be made before
       including any header files:

              #define _BSD_SOURCE
              #define _XOPEN_SOURCE        /* or any value < 500 */

       Alternatively, equivalent definitions can be included in the compilation
       command:

              cc -D_BSD_SOURCE
              cc -D_XOPEN_SOURCE           # Or any value < 500

       Note that, as described below, some feature test macros are defined by
       default, so that it may not always be necessary to explicitly specify the
       feature test macro(s) shown in the SYNOPSIS.

       In a few cases, manual pages use a shorthand for expressing the feature
       test macro requirements (this example from readahead(2)):

              #define _GNU_SOURCE
              #include <fcntl.h>

              ssize_t readahead(int fd, off64_t *offset, size_t count);

       This format is employed in cases where only a single feature test macro can
       be used to expose the function declaration, and that macro is not defined
       by default.

Feature test macros understood by glibc

       The following paragraphs explain how feature test macros are handled in
       Linux glibc 2.x, x > 0.

       Linux glibc understands the following feature test macros:

       __STRICT_ANSI__
              ISO Standard C.  This macro is implicitly defined by gcc(1) when
              invoked with, for example, the -std=c99 or -ansi flag.

       _POSIX_C_SOURCE
              Defining this macro causes header files to expose definitions as
              follows:

              +o  The value 1 exposes definitions conforming to POSIX.1-1990 and
                 ISO C (1990).

              +o  The value 2 or greater additionally exposes definitions for
                 POSIX.2-1992.

              +o  The value 199309L or greater additionally exposes definitions for
                 POSIX.1b (real-time extensions).

              +o  The value 199506L or greater additionally exposes definitions for
                 POSIX.1c (threads).

              +o  (Since glibc 2.3.3) The value 200112L or greater exposes
                 definitions corresponding to the POSIX.1-2001 base specification
                 (excluding the XSI extension).

              +o  (Since glibc 2.10) The value 200809L or greater exposes
                 definitions corresponding to the POSIX.1-2008 base specification
                 (excluding the XSI extension).

       _POSIX_SOURCE
              Defining this obsolete macro with any value is equivalent to
              defining _POSIX_C_SOURCE with the value 1.

       _XOPEN_SOURCE
              Defining this macro causes header files to expose definitions as
              follows:

              +o  Defining with any value exposes definitions conforming to
                 POSIX.1, POSIX.2, and XPG4.

              +o  The value 500 or greater additionally exposes definitions for
                 SUSv2 (UNIX 98).

              +o  (Since glibc 2.2) The value 600 or greater additionally exposes
                 definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base
                 specification plus the XSI extension) and C99 definitions.

              +o  (Since glibc 2.10) The value 700 or greater additionally exposes
                 definitions for SUSv4 (i.e., the POSIX.1-2008 base specification
                 plus the XSI extension).

       _XOPEN_SOURCE_EXTENDED
              If this macro is defined, and _XOPEN_SOURCE is defined, then expose
              definitions corresponding to the XPG4v2 (SUSv1) UNIX extensions
              (UNIX 95).  This macro is also implicitly defined if _XOPEN_SOURCE
              is defined with a value of 500 or more.

       _ISOC95_SOURCE
              Exposes ISO C (1990) Amendment 1 definitions (also known as C95).
              This macro is recognized since glibc 2.12.  The primary change in
              C95 was support for international character sets.  The C95 changes
              were included in the subsequent C99 standard (in other words,
              _ISOC99_SOURCE implies _ISOC95_SOURCE).

       _ISOC99_SOURCE
              Exposes C99 extensions to ISO C (1990).  This macro is recognized
              since glibc 2.1.3; earlier glibc 2.1.x versions recognized an
              equivalent macro named _ISOC9X_SOURCE (because the C99 standard had
              not then been finalized).  Although the use of the latter macro is
              obsolete, glibc continues to recognize it for backward
              compatibility.

       _ISOC11_SOURCE
              Exposes declarations consistent with the ISO C11 standard.  This
              macro is recognized since glibc 2.16.

       _LARGEFILE64_SOURCE
              Expose definitions for the alternative API specified by the LFS
              (Large File Summit) as a "transitional extension" to the Single UNIX
              Specification.  (See <http://opengroup.org/platform/lfs.html>) The
              alternative API consists of a set of new objects (i.e., functions
              and types) whose names are suffixed with "64" (e.g., off64_t versus
              off_t, lseek64() versus lseek(), etc.).  New programs should not
              employ this interface; instead _FILE_OFFSET_BITS=64 should be
              employed.

       _FILE_OFFSET_BITS
              Defining this macro with the value 64 automatically converts refer-
              ences to 32-bit functions and data types related to file I/O and
              file system operations into references to their 64-bit counterparts.
              This is useful for performing I/O on large files (> 2 Gigabytes) on
              32-bit systems.  (Defining this macro permits correctly written pro-
              grams to use large files with only a recompilation being required.)
              64-bit systems naturally permit file sizes greater than 2 Gigabytes,
              and on those systems this macro has no effect.

       _BSD_SOURCE
              Defining this macro with any value causes header files to expose
              BSD-derived definitions.  Defining this macro also causes BSD defi-
              nitions to be preferred in some situations where standards conflict,
              unless one or more of _SVID_SOURCE, _POSIX_SOURCE, _POSIX_C_SOURCE,
              _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED, or _GNU_SOURCE is defined, in
              which case BSD definitions are disfavored.

       _SVID_SOURCE
              Defining this macro with any value causes header files to expose
              System V-derived definitions.  (SVID == System V Interface Defini-
              tion; see standards(7).)

       _ATFILE_SOURCE (since glibc 2.4)
              Defining this macro with any value causes header files to expose
              declarations of a range of functions with the suffix "at"; see ope-
              nat(2).  Since glibc 2.10, this macro is also implicitly defined if
              _POSIX_C_SOURCE is defined with a value greater than or equal to
              200809L.

       _GNU_SOURCE
              Defining this macro (with any value) is equivalent to defining
              _BSD_SOURCE, _SVID_SOURCE, _ATFILE_SOURCE, _LARGEFILE64_SOURCE,
              _ISOC99_SOURCE, _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE,
              _POSIX_C_SOURCE with the value 200809L (200112L in glibc versions
              before 2.10; 199506L in glibc versions before 2.5; 199309L in glibc
              versions before 2.1) and _XOPEN_SOURCE with the value 700 (600 in
              glibc versions before 2.10; 500 in glibc versions before 2.2).  In
              addition, various GNU-specific extensions are also exposed.  Where
              standards conflict, BSD definitions are disfavored.

       _REENTRANT
              Defining this macro exposes definitions of certain reentrant func-
              tions.  For multithreaded programs, use cc -pthread instead.

       _THREAD_SAFE
              Synonym for _REENTRANT, provided for compatibility with some other
              implementations.

       _FORTIFY_SOURCE (since glibc 2.3.4)
              Defining this macro causes some lightweight checks to be performed
              to detect some buffer overflow errors when employing various string
              and memory manipulation functions.  Not all buffer overflows are
              detected, just some common cases.  In the current implementation
              checks are added for calls to memcpy(3), mempcpy(3), memmove(3),
              memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3), strncat(3),
              sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3), and gets(3).  If
              _FORTIFY_SOURCE is set to 1, with compiler optimization level 1
              (gcc -O1) and above, checks that shouldn't change the behavior of
              conforming programs are performed.  With _FORTIFY_SOURCE set to 2
              some more checking is added, but some conforming programs might
              fail.  Some of the checks can be performed at compile time, and
              result in compiler warnings; other checks take place at run time,
              and result in a run-time error if the check fails.  Use of this
              macro requires compiler support, available with gcc(1) since version
              4.0.

Default definitions, implicit definitions, and combining definitions

       If no feature test macros are explicitly defined, then the following fea-
       ture test macros are defined by default: _BSD_SOURCE, _SVID_SOURCE,
       _POSIX_SOURCE, and _POSIX_C_SOURCE=200809L (200112L in glibc versions
       before 2.10; 199506L in glibc versions before 2.4; 199309L in glibc ver-
       sions before 2.1).

       If any of __STRICT_ANSI__, _ISOC99_SOURCE, _POSIX_SOURCE, _POSIX_C_SOURCE,
       _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED, _BSD_SOURCE, or _SVID_SOURCE is
       explicitly defined, then _BSD_SOURCE, and _SVID_SOURCE are not defined by
       default.

       If _POSIX_SOURCE and _POSIX_C_SOURCE are not explicitly defined, and either
       __STRICT_ANSI__ is not defined or _XOPEN_SOURCE is defined with a value of
       500 or more, then

          *  _POSIX_SOURCE is defined with the value 1; and

          *  _POSIX_C_SOURCE is defined with one of the following values:

                +o  2, if XOPEN_SOURCE is defined with a value less than 500;

                +o  199506L, if XOPEN_SOURCE is defined with a value greater than
                   or equal to 500 and less than 600; or

                +o  (since glibc 2.4) 200112L, if XOPEN_SOURCE is defined with a
                   value greater than or equal to 600 and less than 700.

                +o  (Since glibc 2.10) 200809L, if XOPEN_SOURCE is defined with a
                   value greater than or equal to 700.

                +o  Older versions of glibc do not know about the values 200112L
                   and 200809L for _POSIX_C_SOURCE, and the setting of this macro
                   will depend on the glibc version.

                +o  If _XOPEN_SOURCE is undefined, then the setting of
                   _POSIX_C_SOURCE depends on the glibc version: 199506L, in glibc
                   versions before 2.4; 200112L, in glibc 2.4 to 2.9; and 200809L,
                   since glibc 2.10.

       Multiple macros can be defined; the results are additive.

CONFORMING TO top

       POSIX.1 specifies _POSIX_C_SOURCE, _POSIX_SOURCE, and _XOPEN_SOURCE.
       _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1).

       _FILE_OFFSET_BITS is not specified by any standard, but is employed on some
       other implementations.

       _BSD_SOURCE, _SVID_SOURCE, _ATFILE_SOURCE, _GNU_SOURCE, _FORTIFY_SOURCE,
       _REENTRANT, and _THREAD_SAFE are specific to Linux (glibc).

NOTES top

       <features.h> is a Linux/glibc-specific header file.  Other systems have an
       analogous file, but typically with a different name.  This header file is
       automatically included by other header files as required: it is not neces-
       sary to explicitly include it in order to employ feature test macros.

       According to which of the above feature test macros are defined, <fea-
       tures.h> internally defines various other macros that are checked by other
       glibc header files.  These macros have names prefixed by two underscores
       (e.g., __USE_MISC).  Programs should never define these macros directly:
       instead, the appropriate feature test macro(s) from the list above should
       be employed.

EXAMPLE top

       The program below can be used to explore how the various feature test
       macros are set depending on the glibc version and what feature test macros
       are explicitly set.  The following shell session, on a system with glibc
       2.10, shows some examples of what we would see:

           $ cc ftm.c
           $ ./a.out
           _POSIX_SOURCE defined
           _POSIX_C_SOURCE defined: 200809L
           _BSD_SOURCE defined
           _SVID_SOURCE defined
           _ATFILE_SOURCE defined
           $ cc -D_XOPEN_SOURCE=500 ftm.c
           $ ./a.out
           _POSIX_SOURCE defined
           _POSIX_C_SOURCE defined: 199506L
           _XOPEN_SOURCE defined: 500
           $ cc -D_GNU_SOURCE ftm.c
           $ ./a.out
           _POSIX_SOURCE defined
           _POSIX_C_SOURCE defined: 200809L
           _ISOC99_SOURCE defined
           _XOPEN_SOURCE defined: 700
           _XOPEN_SOURCE_EXTENDED defined
           _LARGEFILE64_SOURCE defined
           _BSD_SOURCE defined
           _SVID_SOURCE defined
           _ATFILE_SOURCE defined
           _GNU_SOURCE defined

Program source

       /* ftm.c */

       #include <stdio.h>
       #include <unistd.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
       #ifdef _POSIX_SOURCE
           printf("_POSIX_SOURCE defined\n");
       #endif

       #ifdef _POSIX_C_SOURCE
           printf("_POSIX_C_SOURCE defined: %ldL\n", (long) _POSIX_C_SOURCE);
       #endif

       #ifdef _ISOC99_SOURCE
           printf("_ISOC99_SOURCE defined\n");
       #endif

       #ifdef _XOPEN_SOURCE
           printf("_XOPEN_SOURCE defined: %d\n", _XOPEN_SOURCE);
       #endif

       #ifdef _XOPEN_SOURCE_EXTENDED
           printf("_XOPEN_SOURCE_EXTENDED defined\n");
       #endif

       #ifdef _LARGEFILE64_SOURCE
           printf("_LARGEFILE64_SOURCE defined\n");
       #endif

       #ifdef _FILE_OFFSET_BITS
           printf("_FILE_OFFSET_BITS defined: %d\n", _FILE_OFFSET_BITS);
       #endif

       #ifdef _BSD_SOURCE
           printf("_BSD_SOURCE defined\n");
       #endif

       #ifdef _SVID_SOURCE
           printf("_SVID_SOURCE defined\n");
       #endif

       #ifdef _ATFILE_SOURCE
           printf("_ATFILE_SOURCE defined\n");
       #endif

       #ifdef _GNU_SOURCE
           printf("_GNU_SOURCE defined\n");
       #endif

       #ifdef _REENTRANT
           printf("_REENTRANT defined\n");
       #endif

       #ifdef _THREAD_SAFE
           printf("_THREAD_SAFE defined\n");
       #endif

       #ifdef _FORTIFY_SOURCE
           printf("_FORTIFY_SOURCE defined\n");
       #endif

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       libc(7), standards(7)

       The section "Feature Test Macros" under info libc.

       /usr/include/features.h

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05              FEATURE_TEST_MACROS(7)


fenv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

FENV(3)                      Linux Programmer's Manual                     FENV(3)

NAME top

       feclearexcept,  fegetexceptflag,  feraiseexcept, fesetexceptflag, fetestex-
       cept, fegetenv, fegetround,  feholdexcept,  fesetround,  fesetenv,  feupda-
       teenv, feenableexcept, fedisableexcept, fegetexcept - floating-point round-
       ing and exception handling

SYNOPSIS top

       #include <fenv.h>

       int feclearexcept(int excepts);
       int fegetexceptflag(fexcept_t *flagp, int excepts);
       int feraiseexcept(int excepts);
       int fesetexceptflag(const fexcept_t *flagp, int excepts);
       int fetestexcept(int excepts);

       int fegetround(void);
       int fesetround(int rounding_mode);

       int fegetenv(fenv_t *envp);
       int feholdexcept(fenv_t *envp);
       int fesetenv(const fenv_t *envp);
       int feupdateenv(const fenv_t *envp);

       Link with -lm.

DESCRIPTION top

       These eleven functions were defined in C99, and describe the handling of
       floating-point rounding and exceptions (overflow, zero-divide, etc.).

Exceptions

       The divide-by-zero exception occurs when an operation on finite numbers
       produces infinity as exact answer.

       The overflow exception occurs when a result has to be represented as a
       floating-point number, but has (much) larger absolute value than the
       largest (finite) floating-point number that is representable.

       The underflow exception occurs when a result has to be represented as a
       floating-point number, but has smaller absolute value than the smallest
       positive normalized floating-point number (and would lose much accuracy
       when represented as a denormalized number).

       The inexact exception occurs when the rounded result of an operation is not
       equal to the infinite precision result.  It may occur whenever overflow or
       underflow occurs.

       The invalid exception occurs when there is no well-defined result for an
       operation, as for 0/0 or infinity - infinity or sqrt(-1).

Exception handling

       Exceptions are represented in two ways: as a single bit (exception
       present/absent), and these bits correspond in some implementation-defined
       way with bit positions in an integer, and also as an opaque structure that
       may contain more information about the exception (perhaps the code address
       where it occurred).

       Each of the macros FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW,
       FE_UNDERFLOW is defined when the implementation supports handling of the
       corresponding exception, and if so then defines the corresponding bit(s),
       so that one can call exception handling functions, for example, using the
       integer argument FE_OVERFLOW|FE_UNDERFLOW.  Other exceptions may be
       supported.  The macro FE_ALL_EXCEPT is the bitwise OR of all bits
       corresponding to supported exceptions.

       The feclearexcept() function clears the supported exceptions represented by
       the bits in its argument.

       The fegetexceptflag() function stores a representation of the state of the
       exception flags represented by the argument excepts in the opaque object
       *flagp.

       The feraiseexcept() function raises the supported exceptions represented by
       the bits in excepts.

       The fesetexceptflag() function sets the complete status for the exceptions
       represented by excepts to the value *flagp.  This value must have been
       obtained by an earlier call of fegetexceptflag() with a last argument that
       contained all bits in excepts.

       The fetestexcept() function returns a word in which the bits are set that
       were set in the argument excepts and for which the corresponding exception
       is currently set.

Rounding mode

       The rounding mode determines how the result of floating-point operations is
       treated when the result cannot be exactly represented in the significand.
       Various rounding modes may be provided: round to nearest (the default),
       round up (toward positive infinity), round down (toward negative infinity),
       and round toward zero.

       Each of the macros FE_TONEAREST, FE_UPWARD, FE_DOWNWARD, and FE_TOWARDZERO
       is defined when the implementation supports getting and setting the
       corresponding rounding direction.

       The fegetround() function returns the macro corresponding to the current
       rounding mode.

       The fesetround() function sets the rounding mode as specified by its
       argument and returns zero when it was successful.

       C99 and POSIX.1-2008 specify an identifier, FLT_ROUNDS, defined in
       <float.h>, which indicates the implementation-defined rounding behavior for
       floating-point addition.  This identifier has one of the following values:

       -1     The rounding mode is not determinable.

       0      Rounding is toward 0.

       1      Rounding is toward nearest number.

       2      Rounding is toward positive infinity.

       3      Rounding is toward negative infinity.

       Other values represent machine-dependent, nonstandard rounding modes.

       The value of FLT_ROUNDS should reflect the current rounding mode as set by
       fesetround() (but see BUGS).

Floating-point environment

       The entire floating-point environment, including control modes and status
       flags, can be handled as one opaque object, of type fenv_t.  The default
       environment is denoted by FE_DFL_ENV (of type const fenv_t *).  This is the
       environment setup at program start and it is defined by ISO C to have round
       to nearest, all exceptions cleared and a nonstop (continue on exceptions)
       mode.

       The fegetenv() function saves the current floating-point environment in the
       object *envp.

       The feholdexcept() function does the same, then clears all exception flags,
       and sets a nonstop (continue on exceptions) mode, if available.  It returns
       zero when successful.

       The fesetenv() function restores the floating-point environment from the
       object *envp.  This object must be known to be valid, for example, the
       result of a call to fegetenv() or feholdexcept() or equal to FE_DFL_ENV.
       This call does not raise exceptions.

       The feupdateenv() function installs the floating-point environment
       represented by the object *envp, except that currently raised exceptions
       are not cleared.  After calling this function, the raised exceptions will
       be a bitwise OR of those previously set with those in *envp.  As before,
       the object *envp must be known to be valid.

RETURN VALUE top

       These functions return zero on success and nonzero if an error occurred.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.

NOTES top

Glibc Notes

       If possible, the GNU C Library defines a macro FE_NOMASK_ENV which
       represents an environment where every exception raised causes a trap to
       occur.  You can test for this macro using #ifdef.  It is only defined if
       _GNU_SOURCE is defined.  The C99 standard does not define a way to set
       individual bits in the floating-point mask, for example, to trap on
       specific flags.  Since version 2.2, glibc supports the functions
       feenableexcept() and fedisableexcept() to set individual floating-point
       traps, and fegetexcept() to query the state.

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <fenv.h>

       int feenableexcept(int excepts);
       int fedisableexcept(int excepts);
       int fegetexcept(void);

       The feenableexcept() and fedisableexcept() functions enable (disable) traps
       for each of the exceptions represented by excepts and return the previous
       set of enabled exceptions when successful, and -1 otherwise.  The
       fegetexcept() function returns the set of all currently enabled exceptions.

BUGS          top
       C99 specifies that the value of FLT_ROUNDS should reflect changes to the
       current rounding mode, as set by fesetround().  Currently, this does not
       occur: FLT_ROUNDS always has the value 1.

SEE ALSO          top
       math_error(7)

COLOPHON          top
       This page is part of release 3.45 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                               2010-10-31                             FENV(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


fexecve(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FEXECVE(3)                   Linux Programmer's Manual                  FEXECVE(3)

NAME top

       fexecve - execute program specified via file descriptor

SYNOPSIS top

       #include <unistd.h>

       int fexecve(int fd, char *const argv[], char *const envp[]);

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

       fexecve():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       fexecve() performs the same task as execve(2), with the difference that the
       file to be executed is specified via a file descriptor, fd, rather than via
       a pathname.  The file descriptor fd must be opened read-only, and the
       caller must have permission to execute the file that it refers to.

RETURN VALUE top

       A successful call to fexecve() never returns.  On error, the function
       returns, with a result value of -1, and errno is set appropriately.

ERRORS top

       Errors are as for execve(2), with the following additions:

       EINVAL fd is not a valid file descriptor, or argv is NULL, or envp is NULL.

       ENOSYS The /proc file system could not be accessed.

VERSIONS top

       fexecve() is implemented since glibc 2.3.2.

CONFORMING TO top

       POSIX.1-2008.  This function is not specified in POSIX.1-2001, and is not
       widely available on other systems.

NOTES top

       On Linux, fexecve() is implemented using the proc(5) file system, so /proc
       needs to be mounted and available at the time of the call.

SEE ALSO top

       execve(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-15                          FEXECVE(3)


fflush(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FFLUSH(3)                    Linux Programmer's Manual                   FFLUSH(3)

NAME top

       fflush - flush a stream

SYNOPSIS top

       #include <stdio.h>

       int fflush(FILE *stream);

DESCRIPTION top

       For output streams, fflush() forces a write of all user-space buffered data
       for the given output or update stream via the stream's underlying write
       function.  For input streams, fflush() discards any buffered data that has
       been fetched from the underlying file, but has not been consumed by the
       application.  The open status of the stream is unaffected.

       If the stream argument is NULL, fflush() flushes all open output streams.

       For a nonlocking counterpart, see unlocked_stdio(3).

RETURN VALUE top

       Upon successful completion 0 is returned.  Otherwise, EOF is returned and
       errno is set to indicate the error.

ERRORS top

       EBADF  Stream is not an open stream, or is not open for writing.

       The function fflush() may also fail and set errno for any of the errors
       specified for write(2).

CONFORMING TO top

       C89, C99, POSIX.1-2001, POSIX.1-2008.

       The standards do not specify the behavior for input streams.  Most other
       implementations behave the same as Linux.

NOTES top

       Note that fflush() only flushes the user space buffers provided by the C
       library.  To ensure that the data is physically stored on disk the kernel
       buffers must be flushed too, for example, with sync(2) or fsync(2).

SEE ALSO top

       fsync(2), sync(2), write(2), fclose(3), fopen(3), setbuf(3),
       unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-09-06                           FFLUSH(3)


ffs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FFS(3)                       Linux Programmer's Manual                      FFS(3)

NAME top

       ffs, ffsl, ffsll - find first bit set in a word

SYNOPSIS top

       #include <strings.h>

       int ffs(int i);

       #include <string.h>

       int ffsl(long int i);

       int ffsll(long long int i);

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

       ffs():
           Since glibc 2.12:
               _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE >= 200809L ||
               _XOPEN_SOURCE >= 700 ||
           Before glibc 2.12:
               none
       ffsl(), ffsll():
           _GNU_SOURCE

DESCRIPTION top

       The ffs() function returns the position of the first (least significant)
       bit set in the word i.  The least significant bit is position 1 and the
       most significant position is, for example, 32 or 64.  The functions ffsll()
       and ffsl() do the same but take arguments of possibly different size.

RETURN VALUE top

       These functions return the position of the first bit set, or 0 if no bits
       are set in i.

CONFORMING TO top

       ffs(): 4.3BSD, POSIX.1-2001.

       The ffsl() and ffsll() functions are glibc extensions.

NOTES top

       BSD systems have a prototype in <string.h>.

SEE ALSO top

       memchr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                              FFS(3)


gets(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETS(3)                      Linux Programmer's Manual                     GETS(3)

NAME top

       fgetc, fgets, getc, getchar, gets, ungetc - input of characters and strings

SYNOPSIS top

       #include <stdio.h>

       int fgetc(FILE *stream);

       char *fgets(char *s, int size, FILE *stream);

       int getc(FILE *stream);

       int getchar(void);

       char *gets(char *s);

       int ungetc(int c, FILE *stream);

DESCRIPTION top

       fgetc() reads the next character from stream and returns it as an unsigned
       char cast to an int, or EOF on end of file or error.

       getc() is equivalent to fgetc() except that it may be implemented as a
       macro which evaluates stream more than once.

       getchar() is equivalent to getc(stdin).

       gets() reads a line from stdin into the buffer pointed to by s until either
       a terminating newline or EOF, which it replaces with a null byte ('\0').
       No check for buffer overrun is performed (see BUGS below).

       fgets() reads in at most one less than size characters from stream and
       stores them into the buffer pointed to by s.  Reading stops after an EOF or
       a newline.  If a newline is read, it is stored into the buffer.  A
       terminating null byte ('\0') is stored after the last character in the
       buffer.

       ungetc() pushes c back to stream, cast to unsigned char, where it is
       available for subsequent read operations.  Pushed-back characters will be
       returned in reverse order; only one pushback is guaranteed.

       Calls to the functions described here can be mixed with each other and with
       calls to other input functions from the stdio library for the same input
       stream.

       For nonlocking counterparts, see unlocked_stdio(3).

RETURN VALUE top

       fgetc(), getc() and getchar() return the character read as an unsigned char
       cast to an int or EOF on end of file or error.

       gets() and fgets() return s on success, and NULL on error or when end of
       file occurs while no characters have been read.

       ungetc() returns c on success, or EOF on error.

CONFORMING TO top

       C89, C99, POSIX.1-2001.

       LSB deprecates gets().  POSIX.1-2008 marks gets() obsolescent.  ISO C11
       removes the specification of gets() from the C language, and since version
       2.16, glibc header files don't expose the function declaration if the
       _ISOC11_SOURCE feature test macro is defined.

BUGS top

       Never use gets().  Because it is impossible to tell without knowing the
       data in advance how many characters gets() will read, and because gets()
       will continue to store characters past the end of the buffer, it is
       extremely dangerous to use.  It has been used to break computer security.
       Use fgets() instead.

       It is not advisable to mix calls to input functions from the stdio library
       with low-level calls to read(2) for the file descriptor associated with the
       input stream; the results will be undefined and very probably not what you
       want.

SEE ALSO top

       read(2), write(2), ferror(3), fgetwc(3), fgetws(3), fopen(3), fread(3),
       fseek(3), getline(3), getwchar(3), puts(3), scanf(3), ungetwc(3),
       unlocked_stdio(3), feature_test_macros(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-01-18                             GETS(3)


fgetgrent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FGETGRENT(3)                 Linux Programmer's Manual                FGETGRENT(3)

NAME top

       fgetgrent - get group file entry

SYNOPSIS top

       #include <stdio.h>
       #include <sys/types.h>
       #include <grp.h>

       struct group *fgetgrent(FILE *stream);

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

       fgetgrent(): _SVID_SOURCE

DESCRIPTION top

       The fgetgrent() function returns a pointer to a structure containing the
       group information from the file referred to by stream.  The first time it
       is called it returns the first entry; thereafter, it returns successive
       entries.  The file referred to by stream must have the same format as
       /etc/group (see group(5)).

       The group structure is defined in <grp.h> as follows:

           struct group {
               char   *gr_name;        /* group name */
               char   *gr_passwd;      /* group password */
               gid_t   gr_gid;         /* group ID */
               char  **gr_mem;         /* group members */
           };

RETURN VALUE top

       The fgetgrent() function returns a pointer to a group structure, or NULL if
       there are no more entries or an error occurs.

ERRORS top

       ENOMEM Insufficient memory to allocate group structure.

CONFORMING TO top

       SVr4.

SEE ALSO top

       endgrent(3), fgetgrent_r(3), fopen(3), getgrent(3), getgrgid(3),
       getgrnam(3), putgrent(3), setgrent(3), group(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-07-10                        FGETGRENT(3)


getgrent_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETGRENT_R(3)                Linux Programmer's Manual               GETGRENT_R(3)

NAME top

       getgrent_r, fgetgrent_r - get group file entry reentrantly

SYNOPSIS top

       #include <grp.h>

       int getgrent_r(struct group *gbuf, char *buf,
                      size_t buflen, struct group **gbufp);

       int fgetgrent_r(FILE *fp, struct group *gbuf, char *buf,
                       size_t buflen, struct group **gbufp);

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

       getgrent_r(): _GNU_SOURCE
       fgetgrent_r(): _SVID_SOURCE

DESCRIPTION top

       The functions getgrent_r() and fgetgrent_r() are the reentrant versions of
       getgrent(3) and fgetgrent(3).  The former reads the next group entry from
       the stream initialized by setgrent(3).  The latter reads the next group
       entry from the stream fp.

       The group structure is defined in <grp.h> as follows:

           struct group {
               char    *gr_name;     /* group name */
               char    *gr_passwd;   /* group password */
               gid_t    gr_gid;      /* group ID */
               char   **gr_mem;      /* group members */
           };

       For more information about the fields of this structure, see group(5).

       The nonreentrant functions return a pointer to static storage, where this
       static storage contains further pointers to group name, password and
       members.  The reentrant functions described here return all of that in
       caller-provided buffers.  First of all there is the buffer gbuf that can
       hold a struct group.  And next the buffer buf of size buflen that can hold
       additional strings.  The result of these functions, the struct group read
       from the stream, is stored in the provided buffer *gbuf, and a pointer to
       this struct group is returned in *gbufp.

RETURN VALUE top

       On success, these functions return 0 and *gbufp is a pointer to the struct
       group.  On error, these functions return an error value and *gbufp is NULL.

ERRORS top

       ENOENT No more entries.

       ERANGE Insufficient buffer space supplied.  Try again with larger buffer.

CONFORMING TO top

       These functions are GNU extensions, done in a style resembling the POSIX
       version of functions like getpwnam_r(3).  Other systems use prototype

           struct group *getgrent_r(struct group *grp, char *buf,
                                    int buflen);

       or, better,

           int getgrent_r(struct group *grp, char *buf, int buflen,
                          FILE **gr_fp);

NOTES top

       The function getgrent_r() is not really reentrant since it shares the
       reading position in the stream with all other threads.

EXAMPLE top

       #define _GNU_SOURCE
       #include <grp.h>
       #include <stdio.h>
       #include <stdlib.h>
       #define BUFLEN 4096

       int
       main(void)
       {
           struct group grp, *grpp;
           char buf[BUFLEN];
           int i;

           setgrent();
           while (1) {
               i = getgrent_r(&grp, buf, BUFLEN, &grpp);
               if (i)
                   break;
               printf("%s (%d):", grpp->gr_name, grpp->gr_gid);
               for (i = 0; ; i++) {
                   if (grpp->gr_mem[i] == NULL)
                       break;
                   printf(" %s", grpp->gr_mem[i]);
               }
               printf("\n");
           }
           endgrent();
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fgetgrent(3), getgrent(3), getgrgid(3), getgrnam(3), putgrent(3), group(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-21                       GETGRENT_R(3)


fseek(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FSEEK(3)                     Linux Programmer's Manual                    FSEEK(3)

NAME top

       fgetpos, fseek, fsetpos, ftell, rewind - reposition a stream

SYNOPSIS top

       #include <stdio.h>

       int fseek(FILE *stream, long offset, int whence);

       long ftell(FILE *stream);

       void rewind(FILE *stream);

       int fgetpos(FILE *stream, fpos_t *pos);
       int fsetpos(FILE *stream, fpos_t *pos);

DESCRIPTION top

       The fseek() function sets the file position indicator for the stream
       pointed to by stream.  The new position, measured in bytes, is obtained by
       adding offset bytes to the position specified by whence.  If whence is set
       to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of
       the file, the current position indicator, or end-of-file, respectively.  A
       successful call to the fseek() function clears the end-of-file indicator
       for the stream and undoes any effects of the ungetc(3) function on the same
       stream.

       The ftell() function obtains the current value of the file position
       indicator for the stream pointed to by stream.

       The rewind() function sets the file position indicator for the stream
       pointed to by stream to the beginning of the file.  It is equivalent to:

              (void) fseek(stream, 0L, SEEK_SET)

       except that the error indicator for the stream is also cleared (see
       clearerr(3)).

       The fgetpos() and fsetpos() functions are alternate interfaces equivalent
       to ftell() and fseek() (with whence set to SEEK_SET), setting and storing
       the current value of the file offset into or from the object referenced by
       pos.  On some non-UNIX systems an fpos_t object may be a complex object and
       these routines may be the only way to portably reposition a text stream.

RETURN VALUE top

       The rewind() function returns no value.  Upon successful completion,
       fgetpos(), fseek(), fsetpos() return 0, and ftell() returns the current
       offset.  Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS top

       EBADF  The stream specified is not a seekable stream.

       EINVAL The whence argument to fseek() was not SEEK_SET, SEEK_END, or
              SEEK_CUR.

       The functions fgetpos(), fseek(), fsetpos(), and ftell() may also fail and
       set errno for any of the errors specified for the routines fflush(3),
       fstat(2), lseek(2), and malloc(3).

CONFORMING TO top

       C89, C99.

SEE ALSO top

       lseek(2), fseeko(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-11-29                            FSEEK(3)


fgetpwent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FGETPWENT(3)                 Linux Programmer's Manual                FGETPWENT(3)

NAME top

       fgetpwent - get password file entry

SYNOPSIS top

       #include <stdio.h>
       #include <sys/types.h>
       #include <pwd.h>

       struct passwd *fgetpwent(FILE *stream);

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

       fgetpwent(): _SVID_SOURCE

DESCRIPTION top

       The fgetpwent() function returns a pointer to a structure containing the
       broken out fields of a line in the file stream.  The first time it is
       called it returns the first entry; thereafter, it returns successive
       entries.  The file referred to by stream must have the same format as
       /etc/passwd (see passwd(5)).

       The passwd structure is defined in <pwd.h> as follows:

           struct passwd {
               char   *pw_name;       /* username */
               char   *pw_passwd;     /* user password */
               uid_t   pw_uid;        /* user ID */
               gid_t   pw_gid;        /* group ID */
               char   *pw_gecos;      /* real name */
               char   *pw_dir;        /* home directory */
               char   *pw_shell;      /* shell program */
           };

RETURN VALUE top

       The fgetpwent() function returns a pointer to a passwd structure, or NULL
       if there are no more entries or an error occurs.

ERRORS top

       ENOMEM Insufficient memory to allocate passwd structure.

FILES top

       /etc/passwd
              password database file

CONFORMING TO top

       SVr4.

SEE ALSO top

       endpwent(3), fgetpwent_r(3), fopen(3), getpw(3), getpwent(3), getpwnam(3),
       getpwuid(3), putpwent(3), setpwent(3), passwd(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-07-10                        FGETPWENT(3)


getpwent_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETPWENT_R(3)                Linux Programmer's Manual               GETPWENT_R(3)

NAME top

       getpwent_r, fgetpwent_r - get passwd file entry reentrantly

SYNOPSIS top

       #include <pwd.h>

       int getpwent_r(struct passwd *pwbuf, char *buf,
                      size_t buflen, struct passwd **pwbufp);

       int fgetpwent_r(FILE *fp, struct passwd *pwbuf, char *buf,
                       size_t buflen, struct passwd **pwbufp);

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

       getpwent_r(), _BSD_SOURCE || _SVID_SOURCE
       fgetpwent_r(): _SVID_SOURCE

DESCRIPTION top

       The functions getpwent_r() and fgetpwent_r() are the reentrant versions of
       getpwent(3) and fgetpwent(3).  The former reads the next passwd entry from
       the stream initialized by setpwent(3).  The latter reads the next passwd
       entry from the stream fp.

       The passwd structure is defined in <pwd.h> as follows:

           struct passwd {
               char    *pw_name;      /* username */
               char    *pw_passwd;    /* user password */
               uid_t    pw_uid;       /* user ID */
               gid_t    pw_gid;       /* group ID */
               char    *pw_gecos;     /* user information */
               char    *pw_dir;       /* home directory */
               char    *pw_shell;     /* shell program */
           };

       For more information about the fields of this structure, see passwd(5).

       The nonreentrant functions return a pointer to static storage, where this
       static storage contains further pointers to user name, password, gecos
       field, home directory and shell.  The reentrant functions described here
       return all of that in caller-provided buffers.  First of all there is the
       buffer pwbuf that can hold a struct passwd.  And next the buffer buf of
       size buflen that can hold additional strings.  The result of these
       functions, the struct passwd read from the stream, is stored in the
       provided buffer *pwbuf, and a pointer to this struct passwd is returned in
       *pwbufp.

RETURN VALUE top

       On success, these functions return 0 and *pwbufp is a pointer to the struct
       passwd.  On error, these functions return an error value and *pwbufp is
       NULL.

ERRORS top

       ENOENT No more entries.

       ERANGE Insufficient buffer space supplied.  Try again with larger buffer.

CONFORMING TO top

       These functions are GNU extensions, done in a style resembling the POSIX
       version of functions like getpwnam_r(3).  Other systems use prototype

           struct passwd *
           getpwent_r(struct passwd *pwd, char *buf, int buflen);

       or, better,

           int
           getpwent_r(struct passwd *pwd, char *buf, int buflen,
                      FILE **pw_fp);

NOTES top

       The function getpwent_r() is not really reentrant since it shares the
       reading position in the stream with all other threads.

EXAMPLE top

       #define _GNU_SOURCE
       #include <pwd.h>
       #include <stdio.h>
       #define BUFLEN 4096

       int
       main(void)
       {
           struct passwd pw, *pwp;
           char buf[BUFLEN];
           int i;

           setpwent();
           while (1) {
               i = getpwent_r(&pw, buf, BUFLEN, &pwp);
               if (i)
                   break;
               printf("%s (%d)\tHOME %s\tSHELL %s\n", pwp->pw_name,
                      pwp->pw_uid, pwp->pw_dir, pwp->pw_shell);
           }
           endpwent();
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fgetpwent(3), getpw(3), getpwent(3), getpwnam(3), getpwuid(3), putpwent(3),
       passwd(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-21                       GETPWENT_R(3)


fgetwc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FGETWC(3)                    Linux Programmer's Manual                   FGETWC(3)

NAME top

       fgetwc, getwc - read a wide character from a FILE stream

SYNOPSIS top

       #include <stdio.h>
       #include <wchar.h>

       wint_t fgetwc(FILE *stream);
       wint_t getwc(FILE *stream);

DESCRIPTION top

       The fgetwc() function is the wide-character equivalent of the fgetc(3)
       function.  It reads a wide character from stream and returns it.  If the
       end of stream is reached, or if ferror(stream) becomes true, it returns
       WEOF.  If a wide-character conversion error occurs, it sets errno to EILSEQ
       and returns WEOF.

       The getwc() function or macro functions identically to fgetwc().  It may be
       implemented as a macro, and may evaluate its argument more than once.
       There is no reason ever to use it.

       For nonlocking counterparts, see unlocked_stdio(3).

RETURN VALUE top

       The fgetwc() function returns the next wide-character from the stream, or
       WEOF.

ERRORS top

       Apart from the usual ones, there is

       EILSEQ The data obtained from the input stream does not form a valid
              character.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The behavior of fgetwc() depends on the LC_CTYPE category of the current
       locale.

       In the absence of additional information passed to the fopen(3) call, it is
       reasonable to expect that fgetwc() will actually read a multibyte sequence
       from the stream and then convert it to a wide character.

SEE ALSO top

       fgetws(3), fputwc(3), ungetwc(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           FGETWC(3)


fgetws(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FGETWS(3)                    Linux Programmer's Manual                   FGETWS(3)

NAME top

       fgetws - read a wide-character string from a FILE stream

SYNOPSIS top

       #include <wchar.h>

       wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);

DESCRIPTION top

       The fgetws() function is the wide-character equivalent of the fgets(3)
       function.  It reads a string of at most n-1 wide characters into the wide-
       character array pointed to by ws, and adds a terminating null wide
       character (L'\0').  It stops reading wide characters after it has
       encountered and stored a newline wide character.  It also stops when end of
       stream is reached.

       The programmer must ensure that there is room for at least n wide
       characters at ws.

       For a nonlocking counterpart, see unlocked_stdio(3).

RETURN VALUE top

       The fgetws() function, if successful, returns ws.  If end of stream was
       already reached or if an error occurred, it returns NULL.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The behavior of fgetws() depends on the LC_CTYPE category of the current
       locale.

       In the absence of additional information passed to the fopen(3) call, it is
       reasonable to expect that fgetws() will actually read a multibyte string
       from the stream and then convert it to a wide-character string.

       This function is unreliable, because it does not permit to deal properly
       with null wide characters that may be present in the input.

SEE ALSO top

       fgetwc(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           FGETWS(3)


getxattr(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETXATTR(2)                  Linux Programmer's Manual                 GETXATTR(2)

NAME top

       getxattr, lgetxattr, fgetxattr - retrieve an extended attribute value

SYNOPSIS top

       #include <sys/types.h>
       #include <attr/xattr.h>

       ssize_t getxattr(const char *path, const char *name,
                        void *value, size_t size);
       ssize_t lgetxattr(const char *path, const char *name,
                        void *value, size_t size);
       ssize_t fgetxattr(int fd, const char *name,
                        void *value, size_t size);

DESCRIPTION top

       Extended attributes are name:value pairs associated with inodes (files,
       directories, symbolic links, etc.).  They are extensions to the normal
       attributes which are associated with all inodes in the system (i.e., the
       stat(2) data).  A complete overview of extended attributes concepts can be
       found in attr(5).

       getxattr() retrieves the value of the extended attribute identified by name
       and associated with the given path in the file system.  The length of the
       attribute value is returned.

       lgetxattr() is identical to getxattr(), except in the case of a symbolic
       link, where the link itself is interrogated, not the file that it refers
       to.

       fgetxattr() is identical to getxattr(), only the open file referred to by
       fd (as returned by open(2)) is interrogated in place of path.

       An extended attribute name is a simple null-terminated string.  The name
       includes a namespace prefix; there may be several, disjoint namespaces
       associated with an individual inode.  The value of an extended attribute is
       a chunk of arbitrary textual or binary data of specified length.

       An empty buffer of size zero can be passed into these calls to return the
       current size of the named extended attribute, which can be used to estimate
       the size of a buffer which is sufficiently large to hold the value
       associated with the extended attribute.

       The interface is designed to allow guessing of initial buffer sizes, and to
       enlarge buffers when the return value indicates that the buffer provided
       was too small.

RETURN VALUE top

       On success, a positive number is returned indicating the size of the
       extended attribute value.  On failure, -1 is returned and errno is set
       appropriately.

       If the named attribute does not exist, or the process has no access to this
       attribute, errno is set to ENOATTR.

       If the size of the value buffer is too small to hold the result, errno is
       set to ERANGE.

       If extended attributes are not supported by the file system, or are
       disabled, errno is set to ENOTSUP.

       The errors documented for the stat(2) system call are also applicable here.

VERSIONS top

       These system calls have been available on Linux since kernel 2.4; glibc
       support is provided since version 2.3.

CONFORMING TO top

       These system calls are Linux-specific.

SEE ALSO top

       getfattr(1), setfattr(1), listxattr(2), open(2), removexattr(2),
       setxattr(2), stat(2), attr(5), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2001-12-01                         GETXATTR(2)


fifo(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FIFO(7)                      Linux Programmer's Manual                     FIFO(7)

NAME top

       fifo - first-in first-out special file, named pipe

DESCRIPTION top

       A FIFO special file (a named pipe) is similar to a pipe, except that it is
       accessed as part of the file system.  It can be opened by multiple
       processes for reading or writing.  When processes are exchanging data via
       the FIFO, the kernel passes all data internally without writing it to the
       file system.  Thus, the FIFO special file has no contents on the file
       system; the file system entry merely serves as a reference point so that
       processes can access the pipe using a name in the file system.

       The kernel maintains exactly one pipe object for each FIFO special file
       that is opened by at least one process.  The FIFO must be opened on both
       ends (reading and writing) before data can be passed.  Normally, opening
       the FIFO blocks until the other end is opened also.

       A process can open a FIFO in nonblocking mode.  In this case, opening for
       read only will succeed even if no-one has opened on the write side yet,
       opening for write only will fail with ENXIO (no such device or address)
       unless the other end has already been opened.

       Under Linux, opening a FIFO for read and write will succeed both in
       blocking and nonblocking mode.  POSIX leaves this behavior undefined.  This
       can be used to open a FIFO for writing while there are no readers
       available.  A process that uses both ends of the connection in order to
       communicate with itself should be very careful to avoid deadlocks.

NOTES top

       When a process tries to write to a FIFO that is not opened for read on the
       other side, the process is sent a SIGPIPE signal.

       FIFO special files can be created by mkfifo(3), and are indicated by ls -l
       with the file type 'p'.

SEE ALSO top

       mkfifo(1), open(2), pipe(2), sigaction(2), signal(2), socketpair(2),
       mkfifo(3), pipe(7)

COLOPHON top

       This page is part of release 3.45 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-03                             FIFO(7)


filesystems(5) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

FILESYSTEMS(5)               Linux Programmer's Manual              FILESYSTEMS(5)

NAME top

       filesystems  -  Linux  file-system  types:  minix,  ext,  ext2, ext3, ext4,
       Reiserfs, XFS, JFS, xia, msdos, umsdos, vfat,  ntfs,  proc,  nfs,  iso9660,
       hpfs, sysv, smb, ncpfs

DESCRIPTION top

       When, as is customary, the proc file system is mounted on /proc, you can
       find in the file /proc/filesystems which file systems your kernel currently
       supports.  If you need a currently unsupported one, insert the
       corresponding module or recompile the kernel.

       In order to use a file system, you have to mount it; see mount(8).

       Below a short description of a few of the available file systems.

       minix     is the file system used in the Minix operating system, the first
                 to run under Linux.  It has a number of shortcomings: a 64MB
                 partition size limit, short filenames, a single timestamp, etc.
                 It remains useful for floppies and RAM disks.

       ext       is an elaborate extension of the minix file system.  It has been
                 completely superseded by the second version of the extended file
                 system (ext2) and has been removed from the kernel (in 2.1.21).

       ext2      is the high performance disk file system used by Linux for fixed
                 disks as well as removable media.  The second extended file
                 system was designed as an extension of the extended file system
                 (ext).  ext2 offers the best performance (in terms of speed and
                 CPU usage) of the file systems supported under Linux.

       ext3      is a journaling version of the ext2 file system.  It is easy to
                 switch back and forth between ext2 and ext3.

       ext4      is a set of upgrades to ext3 including substantial performance
                 and reliability enhancements, plus large increases in volume,
                 file, and directory size limits.

       Reiserfs  is a journaling file system, designed by Hans Reiser, that was
                 integrated into Linux in kernel 2.4.1.

       XFS       is a journaling file system, developed by SGI, that was
                 integrated into Linux in kernel 2.4.20.

       JFS       is a journaling file system, developed by IBM, that was
                 integrated into Linux in kernel 2.4.24.

       xiafs     was designed and implemented to be a stable, safe file system by
                 extending the Minix file system code.  It provides the basic most
                 requested features without undue complexity.  The xia file system
                 is no longer actively developed or maintained.  It was removed
                 from the kernel in 2.1.21.

       msdos     is the file system used by DOS, Windows, and some OS/2 computers.
                 msdos filenames can be no longer than 8 characters, followed by
                 an optional period and 3 character extension.

       umsdos    is an extended DOS file system used by Linux.  It adds capability
                 for long filenames, UID/GID, POSIX permissions, and special files
                 (devices, named pipes, etc.)  under the DOS file system, without
                 sacrificing compatibility with DOS.

       vfat      is an extended DOS file system used by Microsoft Windows95 and
                 Windows NT.  VFAT adds the capability to use long filenames under
                 the MSDOS file system.

       ntfs      replaces Microsoft Window's FAT file systems (VFAT, FAT32).  It
                 has reliability, performance, and space-utilization enhancements
                 plus features like ACLs, journaling, encryption, and so on.

       proc      is a pseudo file system which is used as an interface to kernel
                 data structures rather than reading and interpreting /dev/kmem.
                 In particular, its files do not take disk space.  See proc(5).

       iso9660   is a CD-ROM file system type conforming to the ISO 9660 standard.

                 High Sierra
                        Linux supports High Sierra, the precursor to the ISO 9660
                        standard for CD-ROM file systems.  It is automatically
                        recognized within the iso9660 file-system support under
                        Linux.

                 Rock Ridge
                        Linux also supports the System Use Sharing Protocol
                        records specified by the Rock Ridge Interchange Protocol.
                        They are used to further describe the files in the iso9660
                        file system to a UNIX host, and provide information such
                        as long filenames, UID/GID, POSIX permissions, and
                        devices.  It is automatically recognized within the
                        iso9660 file-system support under Linux.

       hpfs      is the High Performance Filesystem, used in OS/2.  This file
                 system is read-only under Linux due to the lack of available
                 documentation.

       sysv      is an implementation of the SystemV/Coherent file system for
                 Linux.  It implements all of Xenix FS, SystemV/386 FS, and
                 Coherent FS.

       nfs       is the network file system used to access disks located on remote
                 computers.

       smb       is a network file system that supports the SMB protocol, used by
                 Windows for Workgroups, Windows NT, and Lan Manager.

                 To use smb fs, you need a special mount program, which can be
                 found in the ksmbfs package, found at <ftp://sunsite.unc.edu/pub
                 /Linux/system/Filesystems/smbfs>.

       ncpfs     is a network file system that supports the NCP protocol, used by
                 Novell NetWare.

                 To use ncpfs, you need special programs, which can be found at
                 <ftp://linux01.gwdg.de/pub/ncpfs>.

SEE ALSO top

       proc(5), fsck(8), mkfs(8), mount(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                      FILESYSTEMS(5)


finite(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FINITE(3)                    Linux Programmer's Manual                   FINITE(3)

NAME top

       finite,  finitef,  finitel,  isinf, isinff, isinfl, isnan, isnanf, isnanl -
       BSD floating-point classification functions

SYNOPSIS top

       #include <math.h>

       int finite(double x);
       int finitef(float x);
       int finitel(long double x);

       int isinf(double x);
       int isinff(float x);
       int isinfl(long double x);

       int isnan(double x);
       int isnanf(float x);
       int isnanl(long double x);

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

       finite(), finitef(), finitel():
           _BSD_SOURCE || _SVID_SOURCE
       isinf():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE;
           or cc -std=c99
       isinff(), isinfl():
           _BSD_SOURCE || _SVID_SOURCE
       isnan():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE || _ISOC99_SOURCE;
           or cc -std=c99
       isnanf(), isnanl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600

DESCRIPTION top

       The finite() functions return a nonzero value if x is neither infinite nor
       a "not-a-number" (NaN) value, and 0 otherwise.

       The isnan() functions return a nonzero value if x is a NaN value, and 0
       otherwise.

       The isinf() functions return 1 if x is positive infinity, -1 if x is
       negative infinity, and 0 otherwise.

NOTES top

       Note that these functions are obsolete.  C99 defines macros isfinite(),
       isinf(), and isnan() (for all types) replacing them.  Further note that the
       C99 isinf() has weaker guarantees on the return value.  See fpclassify(3).

SEE ALSO top

       fpclassify(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-05                           FINITE(3)


listxattr(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LISTXATTR(2)                 Linux Programmer's Manual                LISTXATTR(2)

NAME top

       listxattr, llistxattr, flistxattr - list extended attribute names

SYNOPSIS top

       #include <sys/types.h>
       #include <attr/xattr.h>

       ssize_t listxattr(const char *path, char *list, size_t size);
       ssize_t llistxattr(const char *path, char *list, size_t size);
       ssize_t flistxattr(int fd, char *list, size_t size);

DESCRIPTION top

       Extended attributes are name:value pairs associated with inodes (files,
       directories, symbolic links, etc.).  They are extensions to the normal
       attributes which are associated with all inodes in the system (i.e., the
       stat(2) data).  A complete overview of extended attributes concepts can be
       found in attr(5).

       listxattr() retrieves the list of extended attribute names associated with
       the given path in the file system.  The list is the set of (null-
       terminated) names, one after the other.  Names of extended attributes to
       which the calling process does not have access may be omitted from the
       list.  The length of the attribute name list is returned.

       llistxattr() is identical to listxattr(), except in the case of a symbolic
       link, where the list of names of extended attributes associated with the
       link itself is retrieved, not the file that it refers to.

       flistxattr() is identical to listxattr(), only the open file referred to by
       fd (as returned by open(2)) is interrogated in place of path.

       A single extended attribute name is a simple null-terminated string.  The
       name includes a namespace prefix; there may be several, disjoint namespaces
       associated with an individual inode.

       An empty buffer of size zero can be passed into these calls to return the
       current size of the list of extended attribute names, which can be used to
       estimate the size of a buffer which is sufficiently large to hold the list
       of names.

Example

       The list of names is returned as an unordered array of null-terminated
       character strings (attribute names are separated by null bytes ('\0')),
       like this:

              user.name1\0system.name1\0user.name2\0

       Filesystems like ext2, ext3 and XFS which implement POSIX ACLs using
       extended attributes, might return a list like this:

              system.posix_acl_access\0system.posix_acl_default\0

RETURN VALUE top

       On success, a positive number is returned indicating the size of the
       extended attribute name list.  On failure, -1 is returned and errno is set
       appropriately.

       If the size of the list buffer is too small to hold the result, errno is
       set to ERANGE.

       If extended attributes are not supported by the file system, or are
       disabled, errno is set to ENOTSUP.

       The errors documented for the stat(2) system call are also applicable here.

VERSIONS top

       These system calls have been available on Linux since kernel 2.4; glibc
       support is provided since version 2.3.

CONFORMING TO top

       These system calls are Linux-specific.

SEE ALSO top

       getfattr(1), setfattr(1), getxattr(2), open(2), removexattr(2),
       setxattr(2), stat(2), attr(5), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2001-12-01                        LISTXATTR(2)


flock(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FLOCK(2)                     Linux Programmer's Manual                    FLOCK(2)

NAME top

       flock - apply or remove an advisory lock on an open file

SYNOPSIS top

       #include <sys/file.h>

       int flock(int fd, int operation);

DESCRIPTION top

       Apply or remove an advisory lock on the open file specified by fd.  The
       argument operation is one of the following:

           LOCK_SH  Place a shared lock.  More than one process may hold a shared
                    lock for a given file at a given time.

           LOCK_EX  Place an exclusive lock.  Only one process may hold an
                    exclusive lock for a given file at a given time.

           LOCK_UN  Remove an existing lock held by this process.

       A call to flock() may block if an incompatible lock is held by another
       process.  To make a nonblocking request, include LOCK_NB (by ORing) with
       any of the above operations.

       A single file may not simultaneously have both shared and exclusive locks.

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

       If a process uses open(2) (or similar) to obtain more than one descriptor
       for the same file, these descriptors are treated independently by flock().
       An attempt to lock the file using one of these file descriptors may be
       denied by a lock that the calling process has already placed via another
       descriptor.

       A process may only hold one type of lock (shared or exclusive) on a file.
       Subsequent flock() calls on an already locked file will convert an existing
       lock to the new lock mode.

       Locks created by flock() are preserved across an execve(2).

       A shared or exclusive lock can be placed on a file regardless of the mode
       in which the file was opened.

RETURN VALUE top

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

ERRORS top

       EBADF  fd is not an open file descriptor.

       EINTR  While waiting to acquire a lock, the call was interrupted by
              delivery of a signal caught by a handler; see signal(7).

       EINVAL operation is invalid.

       ENOLCK The kernel ran out of memory for allocating lock records.

       EWOULDBLOCK
              The file is locked and the LOCK_NB flag was selected.

CONFORMING TO top

       4.4BSD (the flock() call first appeared in 4.2BSD).  A version of flock(),
       possibly implemented in terms of fcntl(2), appears on most UNIX systems.

NOTES top

       flock() does not lock files over NFS.  Use fcntl(2) instead: that does work
       over NFS, given a sufficiently recent version of Linux and a server which
       supports locking.

       Since kernel 2.0, flock() is implemented as a system call in its own right
       rather than being emulated in the GNU C library as a call to fcntl(2).
       This yields true BSD semantics: there is no interaction between the types
       of lock placed by flock() and fcntl(2), and flock() does not detect
       deadlock.

       flock() places advisory locks only; given suitable permissions on a file, a
       process is free to ignore the use of flock() and perform I/O on the file.

       flock() and fcntl(2) locks have different semantics with respect to forked
       processes and dup(2).  On systems that implement flock() using fcntl(2),
       the semantics of flock() will be different from those described in this
       manual page.

       Converting a lock (shared to exclusive, or vice versa) is not guaranteed to
       be atomic: the existing lock is first removed, and then a new lock is
       established.  Between these two steps, a pending lock request by another
       process may be granted, with the result that the conversion either blocks,
       or fails if LOCK_NB was specified.  (This is the original BSD behavior, and
       occurs on many other implementations.)

SEE ALSO top

       close(2), dup(2), execve(2), fcntl(2), fork(2), open(2), lockf(3)

       Documentation/filesystem/locks.txt in the Linux kernel source tree
       (Documentation/locks.txt in older kernels)

COLOPHON top

       This page is part of release 3.45 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                               2009-07-25                            FLOCK(2)


flockfile(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | AVAILABILITY | SEE ALSO | COLOPHON The Linux Programming Interface

FLOCKFILE(3)                 Linux Programmer's Manual                FLOCKFILE(3)

NAME top

       flockfile, ftrylockfile, funlockfile - lock FILE for stdio

SYNOPSIS top

       #include <stdio.h>

       void flockfile(FILE *filehandle);
       int ftrylockfile(FILE *filehandle);
       void funlockfile(FILE *filehandle);

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

       All functions shown above:
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||
           _POSIX_SOURCE

DESCRIPTION top

       The stdio functions are thread-safe.  This is achieved by assigning to each
       FILE object a lockcount and (if the lockcount is nonzero) an owning thread.
       For each library call, these functions wait until the FILE object is no
       longer locked by a different thread, then lock it, do the requested I/O,
       and unlock the object again.

       (Note: this locking has nothing to do with the file locking done by
       functions like flock(2) and lockf(3).)

       All this is invisible to the C-programmer, but there may be two reasons to
       wish for more detailed control.  On the one hand, maybe a series of I/O
       actions by one thread belongs together, and should not be interrupted by
       the I/O of some other thread.  On the other hand, maybe the locking
       overhead should be avoided for greater efficiency.

       To this end, a thread can explicitly lock the FILE object, then do its
       series of I/O actions, then unlock.  This prevents other threads from
       coming in between.  If the reason for doing this was to achieve greater
       efficiency, one does the I/O with the nonlocking versions of the stdio
       functions: with getc_unlocked(3) and putc_unlocked(3) instead of getc(3)
       and putc(3).

       The flockfile() function waits for *filehandle to be no longer locked by a
       different thread, then makes the current thread owner of *filehandle, and
       increments the lockcount.

       The funlockfile() function decrements the lock count.

       The ftrylockfile() function is a nonblocking version of flockfile().  It
       does nothing in case some other thread owns *filehandle, and it obtains
       ownership and increments the lockcount otherwise.

RETURN VALUE top

       The ftrylockfile() function returns zero for success (the lock was
       obtained), and nonzero for failure.

ERRORS top

       None.

CONFORMING TO top

       POSIX.1-2001.

AVAILABILITY top

       These functions are available when _POSIX_THREAD_SAFE_FUNCTIONS is defined.
       They are in libc since libc 5.1.1 and in glibc since glibc 2.0.

SEE ALSO top

       unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-29                        FLOCKFILE(3)


floor(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FLOOR(3)                     Linux Programmer's Manual                    FLOOR(3)

NAME top

       floor, floorf, floorl - largest integral value not greater than argument

SYNOPSIS top

       #include <math.h>

       double floor(double x);
       float floorf(float x);
       long double floorl(long double x);

       Link with -lm.

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

       floorf(), floorl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions return the largest integral value that is not greater than
       x.

       For example, floor(0.5) is 0.0, and floor(-0.5) is -1.0.

RETURN VALUE top

       These functions return the floor of x.

       If x is integral, +0, -0, NaN, or an infinity, x itself is returned.

ERRORS top

       No errors occur.  POSIX.1-2001 documents a range error for overflows, but
       see NOTES.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

NOTES top

       SUSv2 and POSIX.1-2001 contain text about overflow (which might set errno
       to ERANGE, or raise an FE_OVERFLOW exception).  In practice, the result
       cannot overflow on any current machine, so this error-handling stuff is
       just nonsense.  (More precisely, overflow can happen only when the maximum
       value of the exponent is smaller than the number of mantissa bits.  For the
       IEEE-754 standard 32-bit and 64-bit floating-point numbers the maximum
       value of the exponent is 128 (respectively, 1024), and the number of
       mantissa bits is 24 (respectively, 53).)

SEE ALSO top

       ceil(3), lrint(3), nearbyint(3), rint(3), round(3), trunc(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            FLOOR(3)


fma(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FMA(3)                       Linux Programmer's Manual                      FMA(3)

NAME top

       fma, fmaf, fmal - floating-point multiply and add

SYNOPSIS top

       #include <math.h>

       double fma(double x, double y, double z);
       float fmaf(float x, float y, float z);
       long double fmal(long double x, long double y, long double z);

       Link with -lm.

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

       fma(), fmaf(), fmal():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The fma() function computes x * y + z.  The result is rounded as one
       ternary operation according to the current rounding mode (see fenv(3)).

RETURN VALUE top

       These functions return the value of x * y + z, rounded as one ternary
       operation.

       If x or y is a NaN, a NaN is returned.

       If x times y is an exact infinity, and z is an infinity with the opposite
       sign, a domain error occurs, and a NaN is returned.

       If one of x or y is an infinity, the other is 0, and z is not a NaN, a
       domain error occurs, and a NaN is returned.

       If one of x or y is an infinity, and the other is 0, and z is a NaN, a
       domain error occurs, and a NaN is returned.

       If x times y is not an infinity times zero (or vice versa), and z is a NaN,
       a NaN is returned.

       If the result overflows, a range error occurs, and an infinity with the
       correct sign is returned.

       If the result underflows, a range error occurs, and a signed 0 is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x * y + z, or x * y is invalid and z is not a NaN
              An invalid floating-point exception (FE_INVALID) is raised.

       Range error: result overflow
              An overflow floating-point exception (FE_OVERFLOW) is raised.

       Range error: result underflow
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       remainder(3), remquo(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                              FMA(3)


fmax(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FMAX(3)                      Linux Programmer's Manual                     FMAX(3)

NAME top

       fmax, fmaxf, fmaxl - determine maximum of two floating-point numbers

SYNOPSIS top

       #include <math.h>

       double fmax(double x, double y);
       float fmaxf(float x, float y);
       long double fmaxl(long double x, long double y);

       Link with -lm.

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

       fmax(), fmaxf(), fmaxl():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions return the larger value of x and y.

RETURN VALUE top

       These functions return the maximum of x and y.

       If one argument is a NaN, the other argument is returned.

       If both arguments are NaN, a NaN is returned.

ERRORS top

       No errors occur.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       fmin(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             FMAX(3)


fmemopen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FMEMOPEN(3)                  Linux Programmer's Manual                 FMEMOPEN(3)

NAME top

       fmemopen, open_memstream, open_wmemstream -  open memory as stream

SYNOPSIS top

       #include <stdio.h>

       FILE *fmemopen(void *buf, size_t size, const char *mode);

       FILE *open_memstream(char **ptr, size_t *sizeloc);

       #include <wchar.h>

       FILE *open_wmemstream(wchar_t **ptr, size_t *sizeloc);

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

       fmemopen(), open_memstream(), open_wmemstream():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The fmemopen() function opens a stream that permits the access specified by
       mode.  The stream allows I/O to be performed on the string or memory buffer
       pointed to by buf.  This buffer must be at least size bytes long.

       The argument mode is the same as for fopen(3).  If mode specifies an append
       mode, then the initial file position is set to the location of the first
       null byte ('\0') in the buffer; otherwise the initial file position is set
       to the start of the buffer.  Since glibc 2.9, the letter 'b' may be
       specified as the second character in mode.  This provides "binary" mode:
       writes don't implicitly add a terminating null byte, and fseek(3) SEEK_END
       is relative to the end of the buffer (i.e., the value specified by the size
       argument), rather than the current string length.

       When a stream that has been opened for writing is flushed (fflush(3)) or
       closed (fclose(3)), a null byte is written at the end of the buffer if
       there is space.  The caller should ensure that an extra byte is available
       in the buffer (and that size counts that byte) to allow for this.

       Attempts to write more than size bytes to the buffer result in an error.
       (By default, such errors will only be visible when the stdio buffer is
       flushed.  Disabling buffering with setbuf(fp, NULL) may be useful to detect
       errors at the time of an output operation.  Alternatively, the caller can
       explicitly set buf as the stdio stream buffer, at the same time informing
       stdio of the buffer's size, using setbuffer(fp, buf, size).)

       In a stream opened for reading, null bytes ('\0') in the buffer do not
       cause read operations to return an end-of-file indication.  A read from the
       buffer will only indicate end-of-file when the file pointer advances size
       bytes past the start of the buffer.

       If buf is specified as NULL, then fmemopen() dynamically allocates a buffer
       size bytes long.  This is useful for an application that wants to write
       data to a temporary buffer and then read it back again.  The buffer is
       automatically freed when the stream is closed.  Note that the caller has no
       way to obtain a pointer to the temporary buffer allocated by this call (but
       see open_memstream() below).

       The open_memstream() function opens a stream for writing to a buffer.  The
       buffer is dynamically allocated (as with malloc(3)), and automatically
       grows as required.  After closing the stream, the caller should free(3)
       this buffer.

       When the stream is closed (fclose(3)) or flushed (fflush(3)), the locations
       pointed to by ptr and sizeloc are updated to contain, respectively, a
       pointer to the buffer and the current size of the buffer.  These values
       remain valid only as long as the caller performs no further output on the
       stream.  If further output is performed, then the stream must again be
       flushed before trying to access these variables.

       A null byte is maintained at the end of the buffer.  This byte is not
       included in the size value stored at sizeloc.

       The stream's file position can be changed with fseek(3) or fseeko(3).
       Moving the file position past the end of the data already written fills the
       intervening space with zeros.

       The open_wmemstream() is similar to open_memstream(), but operates on wide
       characters instead of bytes.

RETURN VALUE top

       Upon successful completion fmemopen(), open_memstream() and
       open_wmemstream() return a FILE pointer.  Otherwise, NULL is returned and
       errno is set to indicate the error.

VERSIONS top

       fmemopen() and open_memstream() were already available in glibc 1.0.x.
       open_wmemstream() is available since glibc 2.4.

CONFORMING TO top

       POSIX.1-2008.  These functions are not specified in POSIX.1-2001, and are
       not widely available on other systems.

       POSIX.1-2008 specifies that 'b' in mode shall be ignored.  However,
       Technical Corrigendum 1 adjusts the standard to allow implementation-
       specific treatment for this case, thus permitting the glibc treatment of
       'b'.

NOTES top

       There is no file descriptor associated with the file stream returned by
       these functions (i.e., fileno(3) will return an error if called on the
       returned stream).

BUGS top

       In glibc before version 2.7, seeking past the end of a stream created by
       open_memstream() does not enlarge the buffer; instead the fseek(3) call
       fails, returning -1.

       If size is specified as zero, fmemopen() fails with the error EINVAL.  It
       would be more consistent if this case successfully created a stream that
       then returned end of file on the first attempt at reading.  Furthermore,
       POSIX.1-2008 does not specify a failure for this case.

       Specifying append mode ("a" or "a+") for fmemopen() sets the initial file
       position to the first null byte, but (if the file offset is reset to a
       location other than the end of the stream) does not force subsequent writes
       to append at the end of the stream.

       If the mode argument to fmemopen() specifies append ("a" or "a+"), and the
       size argument does not cover a null byte in buf then, according to
       POSIX.1-2008, the initial file position should be set to the next byte
       after the end of the buffer.  However, in this case the glibc fmemopen()
       sets the file position to -1.

       To specify binary mode for fmemopen() the 'b' must be the second character
       in mode.  Thus, for example, "wb+" has the desired effect, but "w+b" does
       not.  This is inconsistent with the treatment of mode by fopen(3).

       The glibc 2.9 addition of "binary" mode for fmemopen() silently changed the
       ABI: previously, fmemopen() ignored 'b' in mode.

EXAMPLE top

       The program below uses fmemopen() to open an input buffer, and
       open_memstream() to open a dynamically sized output buffer.  The program
       scans its input string (taken from the program's first command-line
       argument) reading integers, and writes the squares of these integers to the
       output buffer.  An example of the output produced by this program is the
       following:

           $ ./a.out '1 23 43'
           size=11; ptr=1 529 1849

Program source

       #define _GNU_SOURCE
       #include <string.h>
       #include <stdio.h>
       #include <stdlib.h>

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

       int
       main(int argc, char *argv[])
       {
           FILE *out, *in;
           int v, s;
           size_t size;
           char *ptr;

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

           in = fmemopen(argv[1], strlen(argv[1]), "r");
           if (in == NULL)
               handle_error("fmemopen");

           out = open_memstream(&ptr, &size);
           if (out == NULL)
               handle_error("open_memstream");

           for (;;) {
               s = fscanf(in, "%d", &v);
               if (s <= 0)
                   break;

               s = fprintf(out, "%d ", v * v);
               if (s == -1)
                   handle_error("fprintf");
           }
           fclose(in);
           fclose(out);
           printf("size=%ld; ptr=%s\n", (long) size, ptr);
           free(ptr);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fopen(3), fopencookie(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-28                         FMEMOPEN(3)


fmin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FMIN(3)                      Linux Programmer's Manual                     FMIN(3)

NAME top

       fmin, fminf, fminl - determine minimum of two floating-point numbers

SYNOPSIS top

       #include <math.h>

       double fmin(double x, double y);
       float fminf(float x, float y);
       long double fminl(long double x, long double y);

       Link with -lm.

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

       fmin(), fminf(), fminl():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions the lesser value of x and y.

RETURN VALUE top

       These functions return the minimum of x and y.

       If one argument is a NaN, the other argument is returned.

       If both arguments are NaN, a NaN is returned.

ERRORS top

       No errors occur.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       fmax(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             FMIN(3)


fmod(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

FMOD(3)                      Linux Programmer's Manual                     FMOD(3)

NAME top

       fmod, fmodf, fmodl - floating-point remainder function

SYNOPSIS top

       #include <math.h>

       double fmod(double x, double y);
       float fmodf(float x, float y);
       long double fmodl(long double x, long double y);

       Link with -lm.

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

       fmodf(), fmodl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The fmod() function computes the floating-point remainder of dividing x by
       y.  The return value is x - n * y, where n is the quotient of x / y,
       rounded toward zero to an integer.

RETURN VALUE top

       On success, these functions return the value x - n*y, for some integer n,
       such that the returned value has the same sign as x and a magnitude less
       than the magnitude of y.

       If x or y is a NaN, a NaN is returned.

       If x is an infinity, a domain error occurs, and a NaN is returned.

       If y is zero, a domain error occurs, and a NaN is returned.

       If x is +0 (-0), and y is not zero, +0 (-0) is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity
              errno is set to EDOM (but see BUGS).  An invalid floating-point
              exception (FE_INVALID) is raised.

       Domain error: y is zero
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

BUGS top

       Before version 2.10, the glibc implementation did not set errno to EDOM
       when a domain error occurred for an infinite x.

SEE ALSO top

       remainder(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-03-15                             FMOD(3)


fmtmsg(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ENVIRONMENT | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FMTMSG(3)                    Linux Programmer's Manual                   FMTMSG(3)

NAME top

       fmtmsg - print formatted error messages

SYNOPSIS top

       #include <fmtmsg.h>

       int fmtmsg(long classification, const char *label,
                  int severity, const char *text,
                  const char *action, const char *tag);

DESCRIPTION top

       This function displays a message described by its arguments on the
       device(s) specified in the classification argument.  For messages written
       to stderr, the format depends on the MSGVERB environment variable.

       The label argument identifies the source of the message.  The string must
       consist of two colon separated parts where the first part has not more than
       10 and the second part not more than 14 characters.

       The text argument describes the condition of the error.

       The action argument describes possible steps to recover from the error.  If
       it is printed, it is prefixed by "TO FIX: ".

       The tag argument is a reference to the online documentation where more
       information can be found.  It should contain the label value and a unique
       identification number.

Dummy arguments

       Each of the arguments can have a dummy value.  The dummy classification
       value MM_NULLMC (0L) does not specify any output, so nothing is printed.
       The dummy severity value NO_SEV (0) says that no severity is supplied.  The
       values MM_NULLLBL, MM_NULLTXT, MM_NULLACT, MM_NULLTAG are synonyms for
       ((char *) 0), the empty string, and MM_NULLSEV is a synonym for NO_SEV.

The classification argument

       The classification argument is the sum of values describing 4 types of
       information.

       The first value defines the output channel.

       MM_PRINT    Output to stderr.

       MM_CONSOLE  Output to the system console.

       MM_PRINT | MM_CONSOLE
                   Output to both.

       The second value is the source of the error:

       MM_HARD     A hardware error occurred.

       MM_FIRM     A firmware error occurred.

       MM_SOFT     A software error occurred.

       The third value encodes the detector of the problem:

       MM_APPL     It is detected by an application.

       MM_UTIL     It is detected by a utility.

       MM_OPSYS    It is detected by the operating system.

       The fourth value shows the severity of the incident:

       MM_RECOVER  It is a recoverable error.

       MM_NRECOV   It is a nonrecoverable error.

The severity argument

       The severity argument can take one of the following values:

       MM_NOSEV    No severity is printed.

       MM_HALT     This value is printed as HALT.

       MM_ERROR    This value is printed as ERROR.

       MM_WARNING  This value is printed as WARNING.

       MM_INFO     This value is printed as INFO.

       The numeric values are between 0 and 4.  Using addseverity(3) or the
       environment variable SEV_LEVEL you can add more levels and strings to
       print.

RETURN VALUE top

       The function can return 4 values:

       MM_OK       Everything went smooth.

       MM_NOTOK    Complete failure.

       MM_NOMSG    Error writing to stderr.

       MM_NOCON    Error writing to the console.

ENVIRONMENT top

       The environment variable MSGVERB ("message verbosity") can be used to
       suppress parts of the output to stderr.  (It does not influence output to
       the console.)  When this variable is defined, is non-NULL, and is a colon-
       separated list of valid keywords, then only the parts of the message
       corresponding to these keywords is printed.  Valid keywords are "label",
       "severity", "text", "action" and "tag".

       The environment variable SEV_LEVEL can be used to introduce new severity
       levels.  By default, only the five severity levels described above are
       available.  Any other numeric value would make fmtmsg() print nothing.  If
       the user puts SEV_LEVEL with a format like

              SEV_LEVEL=[description[:description[:...]]]

       in the environment of the process before the first call to fmtmsg(), where
       each description is of the form

              severity-keyword,level,printstring

       then fmtmsg() will also accept the indicated values for the level (in
       addition to the standard levels 0-4), and use the indicated printstring
       when such a level occurs.

       The severity-keyword part is not used by fmtmsg() but it has to be present.
       The level part is a string representation of a number.  The numeric value
       must be a number greater than 4.  This value must be used in the severity
       argument of fmtmsg() to select this class.  It is not possible to overwrite
       any of the predefined classes.  The printstring is the string printed when
       a message of this class is processed by fmtmsg().

VERSIONS top

       fmtmsg() is provided in glibc since version 2.1.

CONFORMING TO top

       The functions fmtmsg() and addseverity(3), and environment variables
       MSGVERB and SEV_LEVEL come from System V.  The function fmtmsg() and the
       environment variable MSGVERB are described in POSIX.1-2001.

NOTES top

       System V and UnixWare man pages tell us that these functions have been
       replaced by "pfmt() and addsev()" or by "pfmt(), vpfmt(), lfmt(), and
       vlfmt()", and will be removed later.

EXAMPLE top

       #include <stdio.h>
       #include <stdlib.h>
       #include <fmtmsg.h>

       int
       main(void)
       {
           long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
           int err;

           err = fmtmsg(class, "util-linux:mount", MM_ERROR,
                       "unknown mount option", "See mount(8).",
                       "util-linux:mount:017");
           switch (err) {
           case MM_OK:
               break;
           case MM_NOTOK:
               printf("Nothing printed\n");
               break;
           case MM_NOMSG:
               printf("Nothing printed to stderr\n");
               break;
           case MM_NOCON:
               printf("No console output\n");
               break;
           default:
               printf("Unknown error from fmtmsg()\n");
           }
           exit(EXIT_SUCCESS);
       }

       The output should be:

           util-linux:mount: ERROR: unknown mount option
           TO FIX: See mount(8).  util-linux:mount:017

       and after

           MSGVERB=text:action; export MSGVERB

       the output becomes:

           unknown mount option
           TO FIX: See mount(8).

SEE ALSO top

       addseverity(3), perror(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-06-14                           FMTMSG(3)


fnmatch(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FNMATCH(3)                   Linux Programmer's Manual                  FNMATCH(3)

NAME top

       fnmatch - match filename or pathname

SYNOPSIS top

       #include <fnmatch.h>

       int fnmatch(const char *pattern, const char *string, int flags);

DESCRIPTION top

       The fnmatch() function checks whether the string argument matches the
       pattern argument, which is a shell wildcard pattern.

       The flags argument modifies the behavior; it is the bitwise OR of zero or
       more of the following flags:

       FNM_NOESCAPE
              If this flag is set, treat backslash as an ordinary character,
              instead of an escape character.

       FNM_PATHNAME
              If this flag is set, match a slash in string only with a slash in
              pattern and not by an asterisk (*) or a question mark (?)
              metacharacter, nor by a bracket expression ([]) containing a slash.

       FNM_PERIOD
              If this flag is set, a leading period in string has to be matched
              exactly by a period in pattern.  A period is considered to be
              leading if it is the first character in string, or if both
              FNM_PATHNAME is set and the period immediately follows a slash.

       FNM_FILE_NAME
              This is a GNU synonym for FNM_PATHNAME.

       FNM_LEADING_DIR
              If this flag (a GNU extension) is set, the pattern is considered to
              be matched if it matches an initial segment of string which is
              followed by a slash.  This flag is mainly for the internal use of
              glibc and is only implemented in certain cases.

       FNM_CASEFOLD
              If this flag (a GNU extension) is set, the pattern is matched case-
              insensitively.

RETURN VALUE top

       Zero if string matches pattern, FNM_NOMATCH if there is no match or another
       nonzero value if there is an error.

CONFORMING TO top

       POSIX.2.  The FNM_FILE_NAME, FNM_LEADING_DIR, and FNM_CASEFOLD flags are
       GNU extensions.

SEE ALSO top

       sh(1), glob(3), scandir(3), wordexp(3), glob(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2000-10-15                          FNMATCH(3)


fopencookie(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FOPENCOOKIE(3)               Linux Programmer's Manual              FOPENCOOKIE(3)

NAME top

       fopencookie - opening a custom stream

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <stdio.h>

       FILE *fopencookie(void *cookie, const char *mode,
                         cookie_io_functions_t io_funcs);

DESCRIPTION top

       The fopencookie() function allows the programmer to create a custom
       implementation for a standard I/O stream.  This implementation can store
       the stream's data at a location of its own choosing; for example,
       fopencookie() is used to implement fmemopen(3), which provides a stream
       interface to data that is stored in a buffer in memory.

       In order to create a custom stream the programmer must:

       *  Implement four "hook" functions that are used internally by the standard
          I/O library when performing I/O on the stream.

       *  Define a "cookie" data type, a structure that provides bookkeeping
          information (e.g., where to store data) used by the aforementioned hook
          functions.  The standard I/O package knows nothing about the contents of
          this cookie (thus it is typed as void * when passed to fopencookie()),
          but automatically supplies the cookie as the first argument when calling
          the hook functions.

       *  Call fopencookie() to open a new stream and associate the cookie and
          hook functions with that stream.

       The fopencookie() function serves a purpose similar to fopen(3): it opens a
       new stream and returns a pointer to a FILE object that is used to operate
       on that stream.

       The cookie argument is a pointer to the caller's cookie structure that is
       to be associated with the new stream.  This pointer is supplied as the
       first argument when the standard I/O library invokes any of the hook
       functions described below.

       The mode argument serves the same purpose as for fopen(3).  The following
       modes are supported: r, w, a, r+, w+, and a+.  See fopen(3) for details.

       The io_funcs argument is a structure that contains four fields pointing to
       the programmer-defined hook functions that are used to implement this
       stream.  The structure is defined as follows

           struct cookie_io_functions_t {
               cookie_read_function_t  *read;
               cookie_write_function_t *write;
               cookie_seek_function_t  *seek;
               cookie_close_function_t *close;
           };

       The four fields are as follows:

       cookie_read_function_t *read
              This function implements read operations for the stream.  When
              called, it receives three arguments:

                  ssize_t read(void *cookie, char *buf, size_t size);

              The buf and size arguments are, respectively, a buffer into which
              input data can be placed and the size of that buffer.  As its
              function result, the read function should return the number of bytes
              copied into buf, 0 on end of file, or -1 on error.  The read
              function should update the stream offset appropriately.

              If *read is a NULL pointer, then reads from the custom stream always
              return end of file.

       cookie_write_function_t *write
              This function implements write operations for the stream.  When
              called, it receives three arguments:

                  ssize_t write(void *cookie, const char *buf, size_t size);

              The buf and size arguments are, respectively, a buffer of data to be
              output to the stream and the size of that buffer.  As its function
              result, the write function should return the number of bytes copied
              from buf, or 0 on error.  (The function must not return a negative
              value.)  The write function should update the stream offset
              appropriately.

              If *write is a NULL pointer, then output to the stream is discarded.

       cookie_seek_function_t *seek
              This function implements seek operations on the stream.  When
              called, it receives three arguments:

                  int seek(void *cookie, off64_t *offset, int whence);

              The *offset argument specifies the new file offset depending on
              which of the following three values is supplied in whence:

              SEEK_SET  The stream offset should be set *offset bytes from the
                        start of the stream.

              SEEK_CUR  *offset should be added to the current stream offset.

              SEEK_END  The stream offset should be set to the size of the stream
                        plus *offset.

              Before returning, the seek function should update *offset to
              indicate the new stream offset.

              As its function result, the seek function should return 0 on
              success, and -1 on error.

              If *seek is a NULL pointer, then it is not possible to perform seek
              operations on the stream.

       cookie_close_function_t *close
              This function closes the stream.  The hook function can do things
              such as freeing buffers allocated for the stream.  When called, it
              receives one argument:

                  int close(void *cookie);

              The cookie argument is the cookie that the programmer supplied when
              calling fopencookie().

              As its function result, the close function should return 0 on
              success, and EOF on error.

              If *close is NULL, then no special action is performed when the
              stream is closed.

RETURN VALUE top

       On success fopencookie() returns a pointer to the new stream.  On error,
       NULL is returned.

CONFORMING TO top

       This function is a nonstandard GNU extension.

EXAMPLE top

       The program below implements a custom stream whose functionality is similar
       (but not identical) to that available via fmemopen(3).  It implements a
       stream whose data is stored in a memory buffer.  The program writes its
       command-line arguments to the stream, and then seeks through the stream
       reading two out of every five characters and writing them to standard
       output.  The following shell session demonstrates the use of the program:

           $ ./a.out 'hello world'
           /he/
           / w/
           /d/
           Reached end of file

       Note that a more general version of the program below could be improved to
       more robustly handle various error situations (e.g., opening a stream with
       a cookie that already has an open stream; closing a stream that has already
       been closed).

Program source

       #define _GNU_SOURCE
       #include <sys/types.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <string.h>

       #define INIT_BUF_SIZE 4

       struct memfile_cookie {
           char   *buf;        /* Dynamically sized buffer for data */
           size_t  allocated;  /* Size of buf */
           size_t  endpos;     /* Number of characters in buf */
           off_t   offset;     /* Current file offset in buf */
       };

       ssize_t
       memfile_write(void *c, const char *buf, size_t size)
       {
           char *new_buff;
           struct memfile_cookie *cookie = c;

           /* Buffer too small? Keep doubling size until big enough */

           while (size + cookie->offset > cookie->allocated) {
               new_buff = realloc(cookie->buf, cookie->allocated * 2);
               if (new_buff == NULL) {
                   return -1;
               } else {
                   cookie->allocated *= 2;
                   cookie->buf = new_buff;
               }
           }

           memcpy(cookie->buf + cookie->offset, buf, size);

           cookie->offset += size;
           if (cookie->offset > cookie->endpos)
               cookie->endpos = cookie->offset;

           return size;
       }

       ssize_t
       memfile_read(void *c, char *buf, size_t size)
       {
           ssize_t xbytes;
           struct memfile_cookie *cookie = c;

           /* Fetch minimum of bytes requested and bytes available */

           xbytes = size;
           if (cookie->offset + size > cookie->endpos)
               xbytes = cookie->endpos - cookie->offset;
           if (xbytes < 0)     /* offset may be past endpos */
              xbytes = 0;

           memcpy(buf, cookie->buf + cookie->offset, xbytes);

           cookie->offset += xbytes;
           return xbytes;
       }

       int
       memfile_seek(void *c, off64_t *offset, int whence)
       {
           off64_t new_offset;
           struct memfile_cookie *cookie = c;

           if (whence == SEEK_SET)
               new_offset = *offset;
           else if (whence == SEEK_END)
               new_offset = cookie->endpos + *offset;
           else if (whence == SEEK_CUR)
               new_offset = cookie->offset + *offset;
           else
               return -1;

           if (new_offset < 0)
               return -1;

           cookie->offset = new_offset;
           *offset = new_offset;
           return 0;
       }

       int
       memfile_close(void *c)
       {
           struct memfile_cookie *cookie = c;

           free(cookie->buf);
           cookie->allocated = 0;
           cookie->buf = NULL;

           return 0;
       }

       int
       main(int argc, char *argv[])
       {
           cookie_io_functions_t  memfile_func = {
               .read  = memfile_read,
               .write = memfile_write,
               .seek  = memfile_seek,
               .close = memfile_close
           };
           FILE *fp;
           struct memfile_cookie mycookie;
           ssize_t nread;
           long p;
           int j;
           char buf[1000];

           /* Set up the cookie before calling fopencookie() */

           mycookie.buf = malloc(INIT_BUF_SIZE);
           if (mycookie.buf == NULL) {
               perror("malloc");
               exit(EXIT_FAILURE);
           }

           mycookie.allocated = INIT_BUF_SIZE;
           mycookie.offset = 0;
           mycookie.endpos = 0;

           fp = fopencookie(&mycookie,"w+", memfile_func);
           if (fp == NULL) {
               perror("fopencookie");
               exit(EXIT_FAILURE);
           }

           /* Write command-line arguments to our file */

           for (j = 1; j < argc; j++)
               if (fputs(argv[j], fp) == EOF) {
                   perror("fputs");
                   exit(EXIT_FAILURE);
               }

           /* Read two bytes out of every five, until EOF */

           for (p = 0; ; p += 5) {
               if (fseek(fp, p, SEEK_SET) == -1) {
                   perror("fseek");
                   exit(EXIT_FAILURE);
               }
               nread = fread(buf, 1, 2, fp);
               if (nread == -1) {
                   perror("fread");
                   exit(EXIT_FAILURE);
               }
               if (nread == 0) {
                   printf("Reached end of file\n");
                   break;
               }

               printf("/%.*s/\n", nread, buf);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fclose(3), fmemopen(3), fopen(3), fseek(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-30                      FOPENCOOKIE(3)


fork(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FORK(2)                      Linux Programmer's Manual                     FORK(2)

NAME top

       fork - create a child process

SYNOPSIS top

       #include <unistd.h>

       pid_t fork(void);

DESCRIPTION top

       fork() creates a new process by duplicating the calling process.  The new
       process, referred to as the child, is an exact duplicate of the calling
       process, referred to as the parent, except for the following points:

       *  The child has its own unique process ID, and this PID does not match the
          ID of any existing process group (setpgid(2)).

       *  The child's parent process ID is the same as the parent's process ID.

       *  The child does not inherit its parent's memory locks (mlock(2),
          mlockall(2)).

       *  Process resource utilizations (getrusage(2)) and CPU time counters
          (times(2)) are reset to zero in the child.

       *  The child's set of pending signals is initially empty (sigpending(2)).

       *  The child does not inherit semaphore adjustments from its parent
          (semop(2)).

       *  The child does not inherit record locks from its parent (fcntl(2)).

       *  The child does not inherit timers from its parent (setitimer(2),
          alarm(2), timer_create(2)).

       *  The child does not inherit outstanding asynchronous I/O operations from
          its parent (aio_read(3), aio_write(3)), nor does it inherit any
          asynchronous I/O contexts from its parent (see io_setup(2)).

       The process attributes in the preceding list are all specified in
       POSIX.1-2001.  The parent and child also differ with respect to the
       following Linux-specific process attributes:

       *  The child does not inherit directory change notifications (dnotify) from
          its parent (see the description of F_NOTIFY in fcntl(2)).

       *  The prctl(2) PR_SET_PDEATHSIG setting is reset so that the child does
          not receive a signal when its parent terminates.

       *  The default timer slack value is set to the parent's current timer slack
          value.  See the description of PR_SET_TIMERSLACK in prctl(2).

       *  Memory mappings that have been marked with the madvise(2) MADV_DONTFORK
          flag are not inherited across a fork().

       *  The termination signal of the child is always SIGCHLD (see clone(2)).

       Note the following further points:

       *  The child process is created with a single thread--the one that called
          fork().  The entire virtual address space of the parent is replicated in
          the child, including the states of mutexes, condition variables, and
          other pthreads objects; the use of pthread_atfork(3) may be helpful for
          dealing with problems that this can cause.

       *  The child inherits copies of the parent's set of open file descriptors.
          Each file descriptor in the child refers to the same open file
          description (see open(2)) as the corresponding file descriptor in the
          parent.  This means that the two descriptors share open file status
          flags, current file offset, and signal-driven I/O attributes (see the
          description of F_SETOWN and F_SETSIG in fcntl(2)).

       *  The child inherits copies of the parent's set of open message queue
          descriptors (see mq_overview(7)).  Each descriptor in the child refers
          to the same open message queue description as the corresponding
          descriptor in the parent.  This means that the two descriptors share the
          same flags (mq_flags).

       *  The child inherits copies of the parent's set of open directory streams
          (see opendir(3)).  POSIX.1-2001 says that the corresponding directory
          streams in the parent and child may share the directory stream
          positioning; on Linux/glibc they do not.

RETURN VALUE top

       On success, the PID of the child process is returned in the parent, and 0
       is returned in the child.  On failure, -1 is returned in the parent, no
       child process is created, and errno is set appropriately.

ERRORS top

       EAGAIN fork() cannot allocate sufficient memory to copy the parent's page
              tables and allocate a task structure for the child.

       EAGAIN It was not possible to create a new process because the caller's
              RLIMIT_NPROC resource limit was encountered.  To exceed this limit,
              the process must have either the CAP_SYS_ADMIN or the
              CAP_SYS_RESOURCE capability.

       ENOMEM fork() failed to allocate the necessary kernel structures because
              memory is tight.

       ENOSYS fork() is not supported on this platform (for example, hardware
              without a Memory-Management Unit).

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       Under Linux, fork() is implemented using copy-on-write pages, so the only
       penalty that it incurs is the time and memory required to duplicate the
       parent's page tables, and to create a unique task structure for the child.

       Since version 2.3.3, rather than invoking the kernel's fork() system call,
       the glibc fork() wrapper that is provided as part of the NPTL threading
       implementation invokes clone(2) with flags that provide the same effect as
       the traditional system call.  (A call to fork() is equivalent to a call to
       clone(2) specifying flags as just SIGCHLD.)  The glibc wrapper invokes any
       fork handlers that have been established using pthread_atfork(3).

EXAMPLE top

       See pipe(2) and wait(2).

SEE ALSO top

       clone(2), execve(2), setrlimit(2), unshare(2), vfork(2), wait(2),
       daemon(3), capabilities(7), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-27                             FORK(2)


openpty(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

OPENPTY(3)                   Linux Programmer's Manual                  OPENPTY(3)

NAME top

       openpty, login_tty, forkpty - tty utility functions

SYNOPSIS top

       #include <pty.h>

       int openpty(int *amaster, int *aslave, char *name,
                   const struct termios *termp,
                   const struct winsize *winp);

       pid_t forkpty(int *amaster, char *name,
                     const struct termios *termp,
                     const struct winsize *winp);

       #include <utmp.h>

       int login_tty(int fd);

       Link with -lutil.

DESCRIPTION top

       The openpty() function finds an available pseudoterminal and returns file
       descriptors for the master and slave in amaster and aslave.  If name is not
       NULL, the filename of the slave is returned in name.  If termp is not NULL,
       the terminal parameters of the slave will be set to the values in termp.
       If winp is not NULL, the window size of the slave will be set to the values
       in winp.

       The login_tty() function prepares for a login on the tty fd (which may be a
       real tty device, or the slave of a pseudoterminal as returned by openpty())
       by creating a new session, making fd the controlling terminal for the
       calling process, setting fd to be the standard input, output, and error
       streams of the current process, and closing fd.

       The forkpty() function combines openpty(), fork(2), and login_tty() to
       create a new process operating in a pseudoterminal.  The file descriptor of
       the master side of the pseudoterminal is returned in amaster, and the
       filename of the slave in name if it is not NULL.  The termp and winp
       arguments, if not NULL, will determine the terminal attributes and window
       size of the slave side of the pseudoterminal.

RETURN VALUE top

       If a call to openpty(), login_tty(), or forkpty() is not successful, -1 is
       returned and errno is set to indicate the error.  Otherwise, openpty(),
       login_tty(), and the child process of forkpty() return 0, and the parent
       process of forkpty() returns the process ID of the child process.

ERRORS top

       openpty() will fail if:

       ENOENT There are no available ttys.

       login_tty() will fail if ioctl(2) fails to set fd to the controlling
       terminal of the calling process.

       forkpty() will fail if either openpty() or fork(2) fails.

CONFORMING TO top

       These are BSD functions, present in libc5 and glibc2.  They are not
       standardized in POSIX.

NOTES top

       The const modifiers were added to the structure pointer arguments of
       openpty() and forkpty() in glibc 2.8.

       In versions of glibc before 2.0.92, openpty() returns file descriptors for
       a BSD pseudoterminal pair; since glibc 2.0.92, it first attempts to open a
       UNIX 98 pseudoterminal pair, and falls back to opening a BSD pseudoterminal
       pair if that fails.

BUGS top

       Nobody knows how much space should be reserved for name.  So, calling
       openpty() or forkpty() with non-NULL name may not be secure.

SEE ALSO top

       fork(2), ttyname(3), pty(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-06-13                          OPENPTY(3)


fpathconf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FPATHCONF(3)                 Linux Programmer's Manual                FPATHCONF(3)

NAME top

       fpathconf, pathconf - get configuration values for files

SYNOPSIS top

       #include <unistd.h>

       long fpathconf(int fd, int name);
       long pathconf(char *path, int name);

DESCRIPTION top

       fpathconf() gets a value for the configuration option name for the open
       file descriptor fd.

       pathconf() gets a value for configuration option name for the filename
       path.

       The corresponding macros defined in <unistd.h> are minimum values; if an
       application wants to take advantage of values which may change, a call to
       fpathconf() or pathconf() can be made, which may yield more liberal
       results.

       Setting name equal to one of the following constants returns the following
       configuration options:

       _PC_LINK_MAX
              returns the maximum number of links to the file.  If fd or path
              refer to a directory, then the value applies to the whole directory.
              The corresponding macro is _POSIX_LINK_MAX.

       _PC_MAX_CANON
              returns the maximum length of a formatted input line, where fd or
              path must refer to a terminal.  The corresponding macro is
              _POSIX_MAX_CANON.

       _PC_MAX_INPUT
              returns the maximum length of an input line, where fd or path must
              refer to a terminal.  The corresponding macro is _POSIX_MAX_INPUT.

       _PC_NAME_MAX
              returns the maximum length of a filename in the directory path or fd
              that the process is allowed to create.  The corresponding macro is
              _POSIX_NAME_MAX.

       _PC_PATH_MAX
              returns the maximum length of a relative pathname when path or fd is
              the current working directory.  The corresponding macro is
              _POSIX_PATH_MAX.

       _PC_PIPE_BUF
              returns the size of the pipe buffer, where fd must refer to a pipe
              or FIFO and path must refer to a FIFO.  The corresponding macro is
              _POSIX_PIPE_BUF.

       _PC_CHOWN_RESTRICTED
              returns nonzero if the chown(2) call may not be used on this file.
              If fd or path refer to a directory, then this applies to all files
              in that directory.  The corresponding macro is
              _POSIX_CHOWN_RESTRICTED.

       _PC_NO_TRUNC
              returns nonzero if accessing filenames longer than _POSIX_NAME_MAX
              generates an error.  The corresponding macro is _POSIX_NO_TRUNC.

       _PC_VDISABLE
              returns nonzero if special character processing can be disabled,
              where fd or path must refer to a terminal.

RETURN VALUE top

       The limit is returned, if one exists.  If the system does not have a limit
       for the requested resource, -1 is returned, and errno is unchanged.  If
       there is an error, -1 is returned, and errno is set to reflect the nature
       of the error.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Files with name lengths longer than the value returned for name equal to
       _PC_NAME_MAX may exist in the given directory.

       Some returned values may be huge; they are not suitable for allocating
       memory.

SEE ALSO top

       getconf(1), open(2), statfs(2), sysconf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-04-04                        FPATHCONF(3)


fpclassify(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FPCLASSIFY(3)                Linux Programmer's Manual               FPCLASSIFY(3)

NAME top

       fpclassify,  isfinite,  isnormal, isnan, isinf - floating-point classifica-
       tion macros

SYNOPSIS top

       #include <math.h>

       int fpclassify(x);

       int isfinite(x);

       int isnormal(x);

       int isnan(x);

       int isinf(x);

       Link with -lm.

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

       fpclassify(), isfinite(), isnormal():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       isnan():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       isinf():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       Floating point numbers can have special values, such as infinite or NaN.
       With the macro fpclassify(x) you can find out what type x is.  The macro
       takes any floating-point expression as argument.  The result is one of the
       following values:

       FP_NAN        x is "Not a Number".

       FP_INFINITE   x is either positive infinity or negative infinity.

       FP_ZERO       x is zero.

       FP_SUBNORMAL  x is too small to be represented in normalized format.

       FP_NORMAL     if nothing of the above is correct then it must be a normal
                     floating-point number.

       The other macros provide a short answer to some standard questions.

       isfinite(x)   returns a nonzero value if
                     (fpclassify(x) != FP_NAN && fpclassify(x) != FP_INFINITE)

       isnormal(x)   returns a nonzero value if (fpclassify(x) == FP_NORMAL)

       isnan(x)      returns a nonzero value if (fpclassify(x) == FP_NAN)

       isinf(x)      returns 1 if x is positive infinity, and -1 if x is negative
                     infinity.

CONFORMING TO top

       C99, POSIX.1.

       For isinf(), the standards merely say that the return value is nonzero if
       and only if the argument has an infinite value.

NOTES top

       In glibc 2.01 and earlier, isinf() returns a nonzero value (actually: 1) if
       x is positive infinity or negative infinity.  (This is all that C99
       requires.)

SEE ALSO top

       finite(3), INFINITY(3), isgreater(3), signbit(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                       FPCLASSIFY(3)


printf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PRINTF(3)                    Linux Programmer's Manual                   PRINTF(3)

NAME top

       printf,  fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf
       - formatted output conversion

SYNOPSIS top

       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const char *format, ...);

       #include <stdarg.h>

       int vprintf(const char *format, va_list ap);
       int vfprintf(FILE *stream, const char *format, va_list ap);
       int vsprintf(char *str, const char *format, va_list ap);
       int vsnprintf(char *str, size_t size, const char *format, va_list ap);

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

       snprintf(), vsnprintf():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The functions in the printf() family produce output according to a format
       as described below.  The functions printf() and vprintf() write output to
       stdout, the standard output stream; fprintf() and vfprintf() write output
       to the given output stream; sprintf(), snprintf(), vsprintf() and
       vsnprintf() write to the character string str.

       The functions snprintf() and vsnprintf() write at most size bytes
       (including the terminating null byte ('\0')) to str.

       The functions vprintf(), vfprintf(), vsprintf(), vsnprintf() are equivalent
       to the functions printf(), fprintf(), sprintf(), snprintf(), respectively,
       except that they are called with a va_list instead of a variable number of
       arguments.  These functions do not call the va_end macro.  Because they
       invoke the va_arg macro, the value of ap is undefined after the call.  See
       stdarg(3).

       These eight functions write the output under the control of a format string
       that specifies how subsequent arguments (or arguments accessed via the
       variable-length argument facilities of stdarg(3)) are converted for output.

       C99 and POSIX.1-2001 specify that the results are undefined if a call to
       sprintf(), snprintf(), vsprintf(), or vsnprintf() would cause copying to
       take place between objects that overlap (e.g., if the target string array
       and one of the supplied input arguments refer to the same buffer).  See
       NOTES.

Return value

       Upon successful return, these functions return the number of characters
       printed (excluding the null byte used to end output to strings).

       The functions snprintf() and vsnprintf() do not write more than size bytes
       (including the terminating null byte ('\0')).  If the output was truncated
       due to this limit then the return value is the number of characters
       (excluding the terminating null byte) which would have been written to the
       final string if enough space had been available.  Thus, a return value of
       size or more means that the output was truncated.  (See also below under
       NOTES.)

       If an output error is encountered, a negative value is returned.

Format of the format string

       The format string is a character string, beginning and ending in its
       initial shift state, if any.  The format string is composed of zero or more
       directives: ordinary characters (not %), which are copied unchanged to the
       output stream; and conversion specifications, each of which results in
       fetching zero or more subsequent arguments.  Each conversion specification
       is introduced by the character %, and ends with a conversion specifier.  In
       between there may be (in this order) zero or more flags, an optional
       minimum field width, an optional precision and an optional length modifier.

       The arguments must correspond properly (after type promotion) with the
       conversion specifier.  By default, the arguments are used in the order
       given, where each '*' and each conversion specifier asks for the next
       argument (and it is an error if insufficiently many arguments are given).
       One can also specify explicitly which argument is taken, at each place
       where an argument is required, by writing "%m$" instead of '%' and "*m$"
       instead of '*', where the decimal integer m denotes the position in the
       argument list of the desired argument, indexed starting from 1.  Thus,

           printf("%*d", width, num);

       and

           printf("%2$*1$d", width, num);

       are equivalent.  The second style allows repeated references to the same
       argument.  The C99 standard does not include the style using '$', which
       comes from the Single UNIX Specification.  If the style using '$' is used,
       it must be used throughout for all conversions taking an argument and all
       width and precision arguments, but it may be mixed with "%%" formats which
       do not consume an argument.  There may be no gaps in the numbers of
       arguments specified using '$'; for example, if arguments 1 and 3 are
       specified, argument 2 must also be specified somewhere in the format
       string.

       For some numeric conversions a radix character ("decimal point") or
       thousands' grouping character is used.  The actual character used depends
       on the LC_NUMERIC part of the locale.  The POSIX locale uses '.' as radix
       character, and does not have a grouping character.  Thus,

               printf("%'.2f", 1234567.89);

       results in "1234567.89" in the POSIX locale, in "1234567,89" in the nl_NL
       locale, and in "1.234.567,89" in the da_DK locale.

The flag characters

       The character % is followed by zero or more of the following flags:

       #      The value should be converted to an "alternate form".  For o
              conversions, the first character of the output string is made zero
              (by prefixing a 0 if it was not zero already).  For x and X
              conversions, a nonzero result has the string "0x" (or "0X" for X
              conversions) prepended to it.  For a, A, e, E, f, F, g, and G
              conversions, the result will always contain a decimal point, even if
              no digits follow it (normally, a decimal point appears in the
              results of those conversions only if a digit follows).  For g and G
              conversions, trailing zeros are not removed from the result as they
              would otherwise be.  For other conversions, the result is undefined.

       0      The value should be zero padded.  For d, i, o, u, x, X, a, A, e, E,
              f, F, g, and G conversions, the converted value is padded on the
              left with zeros rather than blanks.  If the 0 and - flags both
              appear, the 0 flag is ignored.  If a precision is given with a
              numeric conversion (d, i, o, u, x, and X), the 0 flag is ignored.
              For other conversions, the behavior is undefined.

       -      The converted value is to be left adjusted on the field boundary.
              (The default is right justification.)  Except for n conversions, the
              converted value is padded on the right with blanks, rather than on
              the left with blanks or zeros.  A - overrides a 0 if both are given.

       ' '    (a space) A blank should be left before a positive number (or empty
              string) produced by a signed conversion.

       +      A sign (+ or -) should always be placed before a number produced by
              a signed conversion.  By default a sign is used only for negative
              numbers.  A + overrides a space if both are used.

       The five flag characters above are defined in the C standard.  The SUSv2
       specifies one further flag character.

       '      For decimal conversion (i, d, u, f, F, g, G) the output is to be
              grouped with thousands' grouping characters if the locale
              information indicates any.  Note that many versions of gcc(1) cannot
              parse this option and will issue a warning.  SUSv2 does not include
              %'F.

       glibc 2.2 adds one further flag character.

       I      For decimal integer conversion (i, d, u) the output uses the
              locale's alternative output digits, if any.  For example, since
              glibc 2.2.3 this will give Arabic-Indic digits in the Persian
              ("fa_IR") locale.

The field width

       An optional decimal digit string (with nonzero first digit) specifying a
       minimum field width.  If the converted value has fewer characters than the
       field width, it will be padded with spaces on the left (or right, if the
       left-adjustment flag has been given).  Instead of a decimal digit string
       one may write "*" or "*m$" (for some decimal integer m) to specify that the
       field width is given in the next argument, or in the m-th argument,
       respectively, which must be of type int.  A negative field width is taken
       as a '-' flag followed by a positive field width.  In no case does a
       nonexistent or small field width cause truncation of a field; if the result
       of a conversion is wider than the field width, the field is expanded to
       contain the conversion result.

The precision

       An optional precision, in the form of a period ('.')  followed by an
       optional decimal digit string.  Instead of a decimal digit string one may
       write "*" or "*m$" (for some decimal integer m) to specify that the
       precision is given in the next argument, or in the m-th argument,
       respectively, which must be of type int.  If the precision is given as just
       '.', or the precision is negative, the precision is taken to be zero.  This
       gives the minimum number of digits to appear for d, i, o, u, x, and X
       conversions, the number of digits to appear after the radix character for
       a, A, e, E, f, and F conversions, the maximum number of significant digits
       for g and G conversions, or the maximum number of characters to be printed
       from a string for s and S conversions.

The length modifier

       Here, "integer conversion" stands for d, i, o, u, x, or X conversion.

       hh     A following integer conversion corresponds to a signed char or
              unsigned char argument, or a following n conversion corresponds to a
              pointer to a signed char argument.

       h      A following integer conversion corresponds to a short int or
              unsigned short int argument, or a following n conversion corresponds
              to a pointer to a short int argument.

       l      (ell) A following integer conversion corresponds to a long int or
              unsigned long int argument, or a following n conversion corresponds
              to a pointer to a long int argument, or a following c conversion
              corresponds to a wint_t argument, or a following s conversion
              corresponds to a pointer to wchar_t argument.

       ll     (ell-ell).  A following integer conversion corresponds to a long
              long int or unsigned long long int argument, or a following n
              conversion corresponds to a pointer to a long long int argument.

       L      A following a, A, e, E, f, F, g, or G conversion corresponds to a
              long double argument.  (C99 allows %LF, but SUSv2 does not.)

       q      ("quad". 4.4BSD and Linux libc5 only.  Don't use.)  This is a
              synonym for ll.

       j      A following integer conversion corresponds to an intmax_t or
              uintmax_t argument.

       z      A following integer conversion corresponds to a size_t or ssize_t
              argument.  (Linux libc5 has Z with this meaning.  Don't use it.)

       t      A following integer conversion corresponds to a ptrdiff_t argument.

       The SUSv2 only knows about the length modifiers h (in hd, hi, ho, hx, hX,
       hn) and l (in ld, li, lo, lx, lX, ln, lc, ls) and L (in Le, LE, Lf, Lg,
       LG).

The conversion specifier

       A character that specifies the type of conversion to be applied.  The
       conversion specifiers and their meanings are:

       d, i   The int argument is converted to signed decimal notation.  The
              precision, if any, gives the minimum number of digits that must
              appear; if the converted value requires fewer digits, it is padded
              on the left with zeros.  The default precision is 1.  When 0 is
              printed with an explicit precision 0, the output is empty.

       o, u, x, X
              The unsigned int argument is converted to unsigned octal (o),
              unsigned decimal (u), or unsigned hexadecimal (x and X) notation.
              The letters abcdef are used for x conversions; the letters ABCDEF
              are used for X conversions.  The precision, if any, gives the
              minimum number of digits that must appear; if the converted value
              requires fewer digits, it is padded on the left with zeros.  The
              default precision is 1.  When 0 is printed with an explicit
              precision 0, the output is empty.

       e, E   The double argument is rounded and converted in the style
              [-]d.ddde+-dd where there is one digit before the decimal-point
              character and the number of digits after it is equal to the
              precision; if the precision is missing, it is taken as 6; if the
              precision is zero, no decimal-point character appears.  An E
              conversion uses the letter E (rather than e) to introduce the
              exponent.  The exponent always contains at least two digits; if the
              value is zero, the exponent is 00.

       f, F   The double argument is rounded and converted to decimal notation in
              the style [-]ddd.ddd, where the number of digits after the decimal-
              point character is equal to the precision specification.  If the
              precision is missing, it is taken as 6; if the precision is
              explicitly zero, no decimal-point character appears.  If a decimal
              point appears, at least one digit appears before it.

              (The SUSv2 does not know about F and says that character string
              representations for infinity and NaN may be made available.  The C99
              standard specifies "[-]inf" or "[-]infinity" for infinity, and a
              string starting with "nan" for NaN, in the case of f conversion, and
              "[-]INF" or "[-]INFINITY" or "NAN*" in the case of F conversion.)

       g, G   The double argument is converted in style f or e (or F or E for G
              conversions).  The precision specifies the number of significant
              digits.  If the precision is missing, 6 digits are given; if the
              precision is zero, it is treated as 1.  Style e is used if the
              exponent from its conversion is less than -4 or greater than or
              equal to the precision.  Trailing zeros are removed from the
              fractional part of the result; a decimal point appears only if it is
              followed by at least one digit.

       a, A   (C99; not in SUSv2) For a conversion, the double argument is
              converted to hexadecimal notation (using the letters abcdef) in the
              style [-]0xh.hhhhp+-; for A conversion the prefix 0X, the letters
              ABCDEF, and the exponent separator P is used.  There is one
              hexadecimal digit before the decimal point, and the number of digits
              after it is equal to the precision.  The default precision suffices
              for an exact representation of the value if an exact representation
              in base 2 exists and otherwise is sufficiently large to distinguish
              values of type double.  The digit before the decimal point is
              unspecified for nonnormalized numbers, and nonzero but otherwise
              unspecified for normalized numbers.

       c      If no l modifier is present, the int argument is converted to an
              unsigned char, and the resulting character is written.  If an l
              modifier is present, the wint_t (wide character) argument is
              converted to a multibyte sequence by a call to the wcrtomb(3)
              function, with a conversion state starting in the initial state, and
              the resulting multibyte string is written.

       s      If no l modifier is present: The const char * argument is expected
              to be a pointer to an array of character type (pointer to a string).
              Characters from the array are written up to (but not including) a
              terminating null byte ('\0'); if a precision is specified, no more
              than the number specified are written.  If a precision is given, no
              null byte need be present; if the precision is not specified, or is
              greater than the size of the array, the array must contain a
              terminating null byte.

              If an l modifier is present: The const wchar_t * argument is
              expected to be a pointer to an array of wide characters.  Wide
              characters from the array are converted to multibyte characters
              (each by a call to the wcrtomb(3) function, with a conversion state
              starting in the initial state before the first wide character), up
              to and including a terminating null wide character.  The resulting
              multibyte characters are written up to (but not including) the
              terminating null byte.  If a precision is specified, no more bytes
              than the number specified are written, but no partial multibyte
              characters are written.  Note that the precision determines the
              number of bytes written, not the number of wide characters or screen
              positions.  The array must contain a terminating null wide
              character, unless a precision is given and it is so small that the
              number of bytes written exceeds it before the end of the array is
              reached.

       C      (Not in C99, but in SUSv2.)  Synonym for lc.  Don't use.

       S      (Not in C99, but in SUSv2.)  Synonym for ls.  Don't use.

       p      The void * pointer argument is printed in hexadecimal (as if by %#x
              or %#lx).

       n      The number of characters written so far is stored into the integer
              indicated by the int * (or variant) pointer argument.  No argument
              is converted.

       m      (Glibc extension.)  Print output of strerror(errno).  No argument is
              required.

       %      A '%' is written.  No argument is converted.  The complete
              conversion specification is '%%'.

CONFORMING TO top

       The fprintf(), printf(), sprintf(), vprintf(), vfprintf(), and vsprintf()
       functions conform to C89 and C99.  The snprintf() and vsnprintf() functions
       conform to C99.

       Concerning the return value of snprintf(), SUSv2 and C99 contradict each
       other: when snprintf() is called with size=0 then SUSv2 stipulates an
       unspecified return value less than 1, while C99 allows str to be NULL in
       this case, and gives the return value (as always) as the number of
       characters that would have been written in case the output string has been
       large enough.

       Linux libc4 knows about the five C standard flags.  It knows about the
       length modifiers h, l, L, and the conversions c, d, e, E, f, F, g, G, i, n,
       o, p, s, u, x, and X, where F is a synonym for f.  Additionally, it accepts
       D, O, and U as synonyms for ld, lo, and lu.  (This is bad, and caused
       serious bugs later, when support for %D disappeared.)  No locale-dependent
       radix character, no thousands' separator, no NaN or infinity, no "%m$" and
       "*m$".

       Linux libc5 knows about the five C standard flags and the ' flag, locale,
       "%m$" and "*m$".  It knows about the length modifiers h, l, L, Z, and q,
       but accepts L and q both for long double and for long long int (this is a
       bug).  It no longer recognizes F, D, O, and U, but adds the conversion
       character m, which outputs strerror(errno).

       glibc 2.0 adds conversion characters C and S.

       glibc 2.1 adds length modifiers hh, j, t, and z and conversion characters a
       and A.

       glibc 2.2 adds the conversion character F with C99 semantics, and the flag
       character I.

NOTES top

       Some programs imprudently rely on code such as the following

           sprintf(buf, "%s some further text", buf);

       to append text to buf.  However, the standards explicitly note that the
       results are undefined if source and destination buffers overlap when
       calling sprintf(), snprintf(), vsprintf(), and vsnprintf().  Depending on
       the version of gcc(1) used, and the compiler options employed, calls such
       as the above will not produce the expected results.

       The glibc implementation of the functions snprintf() and vsnprintf()
       conforms to the C99 standard, that is, behaves as described above, since
       glibc version 2.1.  Until glibc 2.0.6 they would return -1 when the output
       was truncated.

BUGS top

       Because sprintf() and vsprintf() assume an arbitrarily long string, callers
       must be careful not to overflow the actual space; this is often impossible
       to assure.  Note that the length of the strings produced is locale-
       dependent and difficult to predict.  Use snprintf() and vsnprintf() instead
       (or asprintf(3) and vasprintf(3)).

       Linux libc4.[45] does not have a snprintf(), but provides a libbsd that
       contains an snprintf() equivalent to sprintf(), that is, one that ignores
       the size argument.  Thus, the use of snprintf() with early libc4 leads to
       serious security problems.

       Code such as printf(foo); often indicates a bug, since foo may contain a %
       character.  If foo comes from untrusted user input, it may contain %n,
       causing the printf() call to write to memory and creating a security hole.

EXAMPLE top

       To print Pi to five decimal places:

           #include <math.h>
           #include <stdio.h>
           fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

       To print a date and time in the form "Sunday, July 3, 10:02", where weekday
       and month are pointers to strings:

           #include <stdio.h>
           fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
                   weekday, month, day, hour, min);

       Many countries use the day-month-year order.  Hence, an internationalized
       version must be able to print the arguments in an order specified by the
       format:

           #include <stdio.h>
           fprintf(stdout, format,
                   weekday, month, day, hour, min);

       where format depends on locale, and may permute the arguments.  With the
       value:

           "%1$s, %3$d. %2$s, %4$d:%5$.2d\n"

       one might obtain "Sonntag, 3. Juli, 10:02".

       To allocate a sufficiently large string and print into it (code correct for
       both glibc 2.0 and glibc 2.1):

       #include <stdio.h>
       #include <stdlib.h>
       #include <stdarg.h>

       char *
       make_message(const char *fmt, ...)
       {
           int n;
           int size = 100;     /* Guess we need no more than 100 bytes. */
           char *p, *np;
           va_list ap;

           if ((p = malloc(size)) == NULL)
               return NULL;

           while (1) {

               /* Try to print in the allocated space. */

               va_start(ap, fmt);
               n = vsnprintf(p, size, fmt, ap);
               va_end(ap);

               /* If that worked, return the string. */

               if (n > -1 && n < size)
                   return p;

               /* Else try again with more space. */

               if (n > -1)    /* glibc 2.1 */
                   size = n+1; /* precisely what is needed */
               else           /* glibc 2.0 */
                   size *= 2;  /* twice the old size */

               if ((np = realloc (p, size)) == NULL) {
                   free(p);
                   return NULL;
               } else {
                   p = np;
               }
           }
       }

SEE ALSO top

       printf(1), asprintf(3), dprintf(3), scanf(3), setlocale(3), wcrtomb(3),
       wprintf(3), locale(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           PRINTF(3)


fpurge(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FPURGE(3)                    Linux Programmer's Manual                   FPURGE(3)

NAME top

       fpurge, __fpurge - purge a stream

SYNOPSIS top

       /* unsupported */
       #include <stdio.h>

       int fpurge(FILE *stream);

       /* supported */
       #include <stdio.h>
       #include <stdio_ext.h>

       void  __fpurge(FILE *stream);

DESCRIPTION top

       The function fpurge() clears the buffers of the given stream.  For output
       streams this discards any unwritten output.  For input streams this
       discards any input read from the underlying object but not yet obtained via
       getc(3); this includes any text pushed back via ungetc(3).  See also
       fflush(3).

       The function __fpurge() does precisely the same, but without returning a
       value.

RETURN VALUE top

       Upon successful completion fpurge() returns 0.  On error, it returns -1 and
       sets errno appropriately.

ERRORS top

       EBADF  stream is not an open stream.

CONFORMING TO top

       These functions are nonstandard and not portable.  The function fpurge()
       was introduced in 4.4BSD and is not available under Linux.  The function
       __fpurge() was introduced in Solaris, and is present in glibc 2.1.95 and
       later.

NOTES top

       Usually it is a mistake to want to discard input buffers.

SEE ALSO top

       fflush(3), setbuf(3), stdio_ext(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-12-15                           FPURGE(3)


puts(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PUTS(3)                      Linux Programmer's Manual                     PUTS(3)

NAME top

       fputc, fputs, putc, putchar, puts - output of characters and strings

SYNOPSIS top

       #include <stdio.h>

       int fputc(int c, FILE *stream);

       int fputs(const char *s, FILE *stream);

       int putc(int c, FILE *stream);

       int putchar(int c);

       int puts(const char *s);

DESCRIPTION top

       fputc() writes the character c, cast to an unsigned char, to stream.

       fputs() writes the string s to stream, without its terminating null byte
       ('\0').

       putc() is equivalent to fputc() except that it may be implemented as a
       macro which evaluates stream more than once.

       putchar(c); is equivalent to putc(c,stdout).

       puts() writes the string s and a trailing newline to stdout.

       Calls to the functions described here can be mixed with each other and with
       calls to other output functions from the stdio library for the same output
       stream.

       For nonlocking counterparts, see unlocked_stdio(3).

RETURN VALUE top

       fputc(), putc() and putchar() return the character written as an unsigned
       char cast to an int or EOF on error.

       puts() and fputs() return a nonnegative number on success, or EOF on error.

CONFORMING TO top

       C89, C99.

BUGS top

       It is not advisable to mix calls to output functions from the stdio library
       with low-level calls to write(2) for the file descriptor associated with
       the same output stream; the results will be undefined and very probably not
       what you want.

SEE ALSO top

       write(2), ferror(3), fopen(3), fputwc(3), fputws(3), fseek(3), fwrite(3),
       gets(3), putwchar(3), scanf(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                             PUTS(3)


fputwc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FPUTWC(3)                    Linux Programmer's Manual                   FPUTWC(3)

NAME top

       fputwc, putwc - write a wide character to a FILE stream

SYNOPSIS top

       #include <stdio.h>
       #include <wchar.h>

       wint_t fputwc(wchar_t wc, FILE *stream);
       wint_t putwc(wchar_t wc, FILE *stream);

DESCRIPTION top

       The fputwc() function is the wide-character equivalent of the fputc(3)
       function.  It writes the wide character wc to stream.  If ferror(stream)
       becomes true, it returns WEOF.  If a wide-character conversion error
       occurs, it sets errno to EILSEQ and returns WEOF.  Otherwise it returns wc.

       The putwc() function or macro functions identically to fputwc().  It may be
       implemented as a macro, and may evaluate its argument more than once.
       There is no reason ever to use it.

       For nonlocking counterparts, see unlocked_stdio(3).

RETURN VALUE top

       The fputwc() function returns wc if no error occurred, or WEOF to indicate
       an error.

ERRORS top

       Apart from the usual ones, there is

       EILSEQ Conversion of wc to the stream's encoding fails.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The behavior of fputwc() depends on the LC_CTYPE category of the current
       locale.

       In the absence of additional information passed to the fopen(3) call, it is
       reasonable to expect that fputwc() will actually write the multibyte
       sequence corresponding to the wide character wc.

SEE ALSO top

       fgetwc(3), fputws(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           FPUTWC(3)


fputws(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FPUTWS(3)                    Linux Programmer's Manual                   FPUTWS(3)

NAME top

       fputws - write a wide-character string to a FILE stream

SYNOPSIS top

       #include <wchar.h>

       int fputws(const wchar_t *ws, FILE *stream);

DESCRIPTION top

       The fputws() function is the wide-character equivalent of the fputs(3)
       function.  It writes the wide-character string starting at ws, up to but
       not including the terminating null wide character (L'\0'), to stream.

       For a nonlocking counterpart, see unlocked_stdio(3).

RETURN VALUE top

       The fputws() function returns a nonnegative integer if the operation was
       successful, or -1 to indicate an error.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The behavior of fputws() depends on the LC_CTYPE category of the current
       locale.

       In the absence of additional information passed to the fopen(3) call, it is
       reasonable to expect that fputws() will actually write the multibyte string
       corresponding to the wide-character string ws.

SEE ALSO top

       fputwc(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           FPUTWS(3)


fread(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FREAD(3)                     Linux Programmer's Manual                    FREAD(3)

NAME top

       fread, fwrite - binary stream input/output

SYNOPSIS top

       #include <stdio.h>

       size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);

       size_t fwrite(const void *ptr, size_t size, size_t nmemb,
                     FILE *stream);

DESCRIPTION top

       The function fread() reads nmemb elements of data, each size bytes long,
       from the stream pointed to by stream, storing them at the location given by
       ptr.

       The function fwrite() writes nmemb elements of data, each size bytes long,
       to the stream pointed to by stream, obtaining them from the location given
       by ptr.

       For nonlocking counterparts, see unlocked_stdio(3).

RETURN VALUE top

       On success, fread() and fwrite() return the number of items read or
       written.  This number equals the number of bytes transferred only when size
       is 1.  If an error occurs, or the end of the file is reached, the return
       value is a short item count (or zero).

       fread() does not distinguish between end-of-file and error, and callers
       must use feof(3) and ferror(3) to determine which occurred.

CONFORMING TO top

       C89, POSIX.1-2001.

SEE ALSO top

       read(2), write(2), feof(3), ferror(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-30                            FREAD(3)


getaddrinfo(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETADDRINFO(3)               Linux Programmer's Manual              GETADDRINFO(3)

NAME top

       getaddrinfo,  freeaddrinfo,  gai_strerror  -  network  address  and service
       translation

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/socket.h>
       #include <netdb.h>

       int getaddrinfo(const char *node, const char *service,
                       const struct addrinfo *hints,
                       struct addrinfo **res);

       void freeaddrinfo(struct addrinfo *res);

       const char *gai_strerror(int errcode);

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

       getaddrinfo(), freeaddrinfo(), gai_strerror():
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       Given node and service, which identify an Internet host and a service,
       getaddrinfo() returns one or more addrinfo structures, each of which
       contains an Internet address that can be specified in a call to bind(2) or
       connect(2).  The getaddrinfo() function combines the functionality provided
       by the getservbyname(3) and getservbyport(3) functions into a single
       interface, but unlike the latter functions, getaddrinfo() is reentrant and
       allows programs to eliminate IPv4-versus-IPv6 dependencies.

       The addrinfo structure used by getaddrinfo() contains the following fields:

           struct addrinfo {
               int              ai_flags;
               int              ai_family;
               int              ai_socktype;
               int              ai_protocol;
               socklen_t        ai_addrlen;
               struct sockaddr *ai_addr;
               char            *ai_canonname;
               struct addrinfo *ai_next;
           };

       The hints argument points to an addrinfo structure that specifies criteria
       for selecting the socket address structures returned in the list pointed to
       by res.  If hints is not NULL it points to an addrinfo structure whose
       ai_family, ai_socktype, and ai_protocol specify criteria that limit the set
       of socket addresses returned by getaddrinfo(), as follows:

       ai_family   This field specifies the desired address family for the
                   returned addresses.  Valid values for this field include
                   AF_INET and AF_INET6.  The value AF_UNSPEC indicates that
                   getaddrinfo() should return socket addresses for any address
                   family (either IPv4 or IPv6, for example) that can be used with
                   node and service.

       ai_socktype This field specifies the preferred socket type, for example
                   SOCK_STREAM or SOCK_DGRAM.  Specifying 0 in this field
                   indicates that socket addresses of any type can be returned by
                   getaddrinfo().

       ai_protocol This field specifies the protocol for the returned socket
                   addresses.  Specifying 0 in this field indicates that socket
                   addresses with any protocol can be returned by getaddrinfo().

       ai_flags    This field specifies additional options, described below.
                   Multiple flags are specified by bitwise OR-ing them together.

       All the other fields in the structure pointed to by hints must contain
       either 0 or a NULL pointer, as appropriate.  Specifying hints as NULL is
       equivalent to setting ai_socktype and ai_protocol to 0; ai_family to
       AF_UNSPEC; and ai_flags to (AI_V4MAPPED | AI_ADDRCONFIG).

       node specifies either a numerical network address (for IPv4, numbers-and-
       dots notation as supported by inet_aton(3); for IPv6, hexadecimal string
       format as supported by inet_pton(3)), or a network hostname, whose network
       addresses are looked up and resolved.  If hints.ai_flags contains the
       AI_NUMERICHOST flag then node must be a numerical network address.  The
       AI_NUMERICHOST flag suppresses any potentially lengthy network host address
       lookups.

       If the AI_PASSIVE flag is specified in hints.ai_flags, and node is NULL,
       then the returned socket addresses will be suitable for bind(2)ing a socket
       that will accept(2) connections.  The returned socket address will contain
       the "wildcard address" (INADDR_ANY for IPv4 addresses, IN6ADDR_ANY_INIT for
       IPv6 address).  The wildcard address is used by applications (typically
       servers) that intend to accept connections on any of the hosts's network
       addresses.  If node is not NULL, then the AI_PASSIVE flag is ignored.

       If the AI_PASSIVE flag is not set in hints.ai_flags, then the returned
       socket addresses will be suitable for use with connect(2), sendto(2), or
       sendmsg(2).  If node is NULL, then the network address will be set to the
       loopback interface address (INADDR_LOOPBACK for IPv4 addresses,
       IN6ADDR_LOOPBACK_INIT for IPv6 address); this is used by applications that
       intend to communicate with peers running on the same host.

       service sets the port in each returned address structure.  If this argument
       is a service name (see services(5)), it is translated to the corresponding
       port number.  This argument can also be specified as a decimal number,
       which is simply converted to binary.  If service is NULL, then the port
       number of the returned socket addresses will be left uninitialized.  If
       AI_NUMERICSERV is specified in hints.ai_flags and service is not NULL, then
       service must point to a string containing a numeric port number.  This flag
       is used to inhibit the invocation of a name resolution service in cases
       where it is known not to be required.

       Either node or service, but not both, may be NULL.

       The getaddrinfo() function allocates and initializes a linked list of
       addrinfo structures, one for each network address that matches node and
       service, subject to any restrictions imposed by hints, and returns a
       pointer to the start of the list in res.  The items in the linked list are
       linked by the ai_next field.

       There are several reasons why the linked list may have more than one
       addrinfo structure, including: the network host is multihomed, accessible
       over multiple protocols (e.g., both AF_INET and AF_INET6); or the same
       service is available from multiple socket types (one SOCK_STREAM address
       and another SOCK_DGRAM address, for example).  Normally, the application
       should try using the addresses in the order in which they are returned.
       The sorting function used within getaddrinfo() is defined in RFC 3484; the
       order can be tweaked for a particular system by editing /etc/gai.conf
       (available since glibc 2.5).

       If hints.ai_flags includes the AI_CANONNAME flag, then the ai_canonname
       field of the first of the addrinfo structures in the returned list is set
       to point to the official name of the host.

       The remaining fields of each returned addrinfo structure are initialized as
       follows:

       * The ai_family, ai_socktype, and ai_protocol fields return the socket
         creation parameters (i.e., these fields have the same meaning as the
         corresponding arguments of socket(2)).  For example, ai_family might
         return AF_INET or AF_INET6; ai_socktype might return SOCK_DGRAM or
         SOCK_STREAM; and ai_protocol returns the protocol for the socket.

       * A pointer to the socket address is placed in the ai_addr field, and the
         length of the socket address, in bytes, is placed in the ai_addrlen
         field.

       If hints.ai_flags includes the AI_ADDRCONFIG flag, then IPv4 addresses are
       returned in the list pointed to by res only if the local system has at
       least one IPv4 address configured, and IPv6 addresses are only returned if
       the local system has at least one IPv6 address configured.  The loopback
       address is not considered for this case as valid as a configured address.

       If hint.ai_flags specifies the AI_V4MAPPED flag, and hints.ai_family was
       specified as AF_INET6, and no matching IPv6 addresses could be found, then
       return IPv4-mapped IPv6 addresses in the list pointed to by res.  If both
       AI_V4MAPPED and AI_ALL are specified in hints.ai_flags, then return both
       IPv6 and IPv4-mapped IPv6 addresses in the list pointed to by res.  AI_ALL
       is ignored if AI_V4MAPPED is not also specified.

       The freeaddrinfo() function frees the memory that was allocated for the
       dynamically allocated linked list res.

Extensions to getaddrinfo() for Internationalized Domain Names

       Starting with glibc 2.3.4, getaddrinfo() has been extended to selectively
       allow the incoming and outgoing hostnames to be transparently converted to
       and from the Internationalized Domain Name (IDN) format (see RFC 3490,
       Internationalizing Domain Names in Applications (IDNA)).  Four new flags
       are defined:

       AI_IDN If this flag is specified, then the node name given in node is
              converted to IDN format if necessary.  The source encoding is that
              of the current locale.

              If the input name contains non-ASCII characters, then the IDN
              encoding is used.  Those parts of the node name (delimited by dots)
              that contain non-ASCII characters are encoded using ASCII Compatible
              Encoding (ACE) before being passed to the name resolution functions.

       AI_CANONIDN
              After a successful name lookup, and if the AI_CANONNAME flag was
              specified, getaddrinfo() will return the canonical name of the node
              corresponding to the addrinfo structure value passed back.  The
              return value is an exact copy of the value returned by the name
              resolution function.

              If the name is encoded using ACE, then it will contain the xn--
              prefix for one or more components of the name.  To convert these
              components into a readable form the AI_CANONIDN flag can be passed
              in addition to AI_CANONNAME.  The resulting string is encoded using
              the current locale's encoding.

       AI_IDN_ALLOW_UNASSIGNED, AI_IDN_USE_STD3_ASCII_RULES
              Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
              unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES (check
              output to make sure it is a STD3 conforming hostname) flags
              respectively to be used in the IDNA handling.

RETURN VALUE top

       getaddrinfo() returns 0 if it succeeds, or one of the following nonzero
       error codes:

       EAI_ADDRFAMILY
              The specified network host does not have any network addresses in
              the requested address family.

       EAI_AGAIN
              The name server returned a temporary failure indication.  Try again
              later.

       EAI_BADFLAGS
              hints.ai_flags contains invalid flags; or, hints.ai_flags included
              AI_CANONNAME and name was NULL.

       EAI_FAIL
              The name server returned a permanent failure indication.

       EAI_FAMILY
              The requested address family is not supported.

       EAI_MEMORY
              Out of memory.

       EAI_NODATA
              The specified network host exists, but does not have any network
              addresses defined.

       EAI_NONAME
              The node or service is not known; or both node and service are NULL;
              or AI_NUMERICSERV was specified in hints.ai_flags and service was
              not a numeric port-number string.

       EAI_SERVICE
              The requested service is not available for the requested socket
              type.  It may be available through another socket type.  For
              example, this error could occur if service was "shell" (a service
              only available on stream sockets), and either hints.ai_protocol was
              IPPROTO_UDP, or hints.ai_socktype was SOCK_DGRAM; or the error could
              occur if service was not NULL, and hints.ai_socktype was SOCK_RAW (a
              socket type that does not support the concept of services).

       EAI_SOCKTYPE
              The requested socket type is not supported.  This could occur, for
              example, if hints.ai_socktype and hints.ai_protocol are inconsistent
              (e.g., SOCK_DGRAM and IPPROTO_TCP, respectively).

       EAI_SYSTEM
              Other system error, check errno for details.

       The gai_strerror() function translates these error codes to a human
       readable string, suitable for error reporting.

FILES top

       /etc/gai.conf

CONFORMING TO top

       POSIX.1-2001.  The getaddrinfo() function is documented in RFC 2553.

NOTES top

       getaddrinfo() supports the address%scope-id notation for specifying the
       IPv6 scope-ID.

       AI_ADDRCONFIG, AI_ALL, and AI_V4MAPPED are available since glibc 2.3.3.
       AI_NUMERICSERV is available since glibc 2.3.4.

       According to POSIX.1-2001, specifying hints as NULL should cause ai_flags
       to be assumed as 0.  The GNU C library instead assumes a value of
       (AI_V4MAPPED | AI_ADDRCONFIG) for this case, since this value is considered
       an improvement on the specification.

EXAMPLE top

       The following programs demonstrate the use of getaddrinfo(),
       gai_strerror(), freeaddrinfo(), and getnameinfo(3).  The programs are an
       echo server and client for UDP datagrams.

Server program

       #include <sys/types.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <string.h>
       #include <sys/socket.h>
       #include <netdb.h>

       #define BUF_SIZE 500

       int
       main(int argc, char *argv[])
       {
           struct addrinfo hints;
           struct addrinfo *result, *rp;
           int sfd, s;
           struct sockaddr_storage peer_addr;
           socklen_t peer_addr_len;
           ssize_t nread;
           char buf[BUF_SIZE];

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

           memset(&hints, 0, sizeof(struct addrinfo));
           hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
           hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
           hints.ai_flags = AI_PASSIVE;    /* For wildcard IP address */
           hints.ai_protocol = 0;          /* Any protocol */
           hints.ai_canonname = NULL;
           hints.ai_addr = NULL;
           hints.ai_next = NULL;

           s = getaddrinfo(NULL, argv[1], &hints, &result);
           if (s != 0) {
               fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(s));
               exit(EXIT_FAILURE);
           }

           /* getaddrinfo() returns a list of address structures.
              Try each address until we successfully bind(2).
              If socket(2) (or bind(2)) fails, we (close the socket
              and) try the next address. */

           for (rp = result; rp != NULL; rp = rp->ai_next) {
               sfd = socket(rp->ai_family, rp->ai_socktype,
                       rp->ai_protocol);
               if (sfd == -1)
                   continue;

               if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
                   break;                  /* Success */

               close(sfd);
           }

           if (rp == NULL) {               /* No address succeeded */
               fprintf(stderr, "Could not bind\n");
               exit(EXIT_FAILURE);
           }

           freeaddrinfo(result);           /* No longer needed */

           /* Read datagrams and echo them back to sender */

           for (;;) {
               peer_addr_len = sizeof(struct sockaddr_storage);
               nread = recvfrom(sfd, buf, BUF_SIZE, 0,
                       (struct sockaddr *) &peer_addr, &peer_addr_len);
               if (nread == -1)
                   continue;               /* Ignore failed request */

               char host[NI_MAXHOST], service[NI_MAXSERV];

               s = getnameinfo((struct sockaddr *) &peer_addr,
                               peer_addr_len, host, NI_MAXHOST,
                               service, NI_MAXSERV, NI_NUMERICSERV);
              if (s == 0)
                   printf("Received %ld bytes from %s:%s\n",
                           (long) nread, host, service);
               else
                   fprintf(stderr, "getnameinfo: %s\n", gai_strerror(s));

               if (sendto(sfd, buf, nread, 0,
                           (struct sockaddr *) &peer_addr,
                           peer_addr_len) != nread)
                   fprintf(stderr, "Error sending response\n");
           }
       }

Client program

       #include <sys/types.h>
       #include <sys/socket.h>
       #include <netdb.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <string.h>

       #define BUF_SIZE 500

       int
       main(int argc, char *argv[])
       {
           struct addrinfo hints;
           struct addrinfo *result, *rp;
           int sfd, s, j;
           size_t len;
           ssize_t nread;
           char buf[BUF_SIZE];

           if (argc < 3) {
               fprintf(stderr, "Usage: %s host port msg...\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           /* Obtain address(es) matching host/port */

           memset(&hints, 0, sizeof(struct addrinfo));
           hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
           hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
           hints.ai_flags = 0;
           hints.ai_protocol = 0;          /* Any protocol */

           s = getaddrinfo(argv[1], argv[2], &hints, &result);
           if (s != 0) {
               fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(s));
               exit(EXIT_FAILURE);
           }

           /* getaddrinfo() returns a list of address structures.
              Try each address until we successfully connect(2).
              If socket(2) (or connect(2)) fails, we (close the socket
              and) try the next address. */

           for (rp = result; rp != NULL; rp = rp->ai_next) {
               sfd = socket(rp->ai_family, rp->ai_socktype,
                            rp->ai_protocol);
               if (sfd == -1)
                   continue;

               if (connect(sfd, rp->ai_addr, rp->ai_addrlen) != -1)
                   break;                  /* Success */

               close(sfd);
           }

           if (rp == NULL) {               /* No address succeeded */
               fprintf(stderr, "Could not connect\n");
               exit(EXIT_FAILURE);
           }

           freeaddrinfo(result);           /* No longer needed */

           /* Send remaining command-line arguments as separate
              datagrams, and read responses from server */

           for (j = 3; j < argc; j++) {
               len = strlen(argv[j]) + 1;
                       /* +1 for terminating null byte */

               if (len + 1 > BUF_SIZE) {
                   fprintf(stderr,
                           "Ignoring long message in argument %d\n", j);
                   continue;
               }

               if (write(sfd, argv[j], len) != len) {
                   fprintf(stderr, "partial/failed write\n");
                   exit(EXIT_FAILURE);
               }

               nread = read(sfd, buf, BUF_SIZE);
               if (nread == -1) {
                   perror("read");
                   exit(EXIT_FAILURE);
               }

               printf("Received %ld bytes: %s\n", (long) nread, buf);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getaddrinfo_a(3), gethostbyname(3), getnameinfo(3), inet(3), hostname(7),
       ip(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-29                      GETADDRINFO(3)


getipnodebyname(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETIPNODEBYNAME(3)           Linux Programmer's Manual          GETIPNODEBYNAME(3)

NAME top

       getipnodebyname,  getipnodebyaddr,  freehostent - get network hostnames and
       addresses

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/socket.h>
       #include <netdb.h>

       struct hostent *getipnodebyname(const char *name, int af,
                                       int flags, int *error_num);

       struct hostent *getipnodebyaddr(const void *addr, size_t len,
                                       int af, int *error_num);

       void freehostent(struct hostent *ip);

DESCRIPTION top

       These functions are deprecated (and unavailable in glibc).  Use
       getaddrinfo(3) and getnameinfo(3) instead.

       The getipnodebyname() and getipnodebyaddr() functions return the names and
       addresses of a network host.  These functions return a pointer to the
       following structure:

           struct hostent {
               char  *h_name;
               char **h_aliases;
               int    h_addrtype;
               int    h_length;
               char **h_addr_list;
           };

       These functions replace the gethostbyname(3) and gethostbyaddr(3)
       functions, which could only access the IPv4 network address family.  The
       getipnodebyname() and getipnodebyaddr() functions can access multiple
       network address families.

       Unlike the gethostby functions, these functions return pointers to
       dynamically allocated memory.  The freehostent() function is used to
       release the dynamically allocated memory after the caller no longer needs
       the hostent structure.

getipnodebyname() arguments

       The getipnodebyname() function looks up network addresses for the host
       specified by the name argument.  The af argument specifies one of the
       following values:

       AF_INET
              The name argument points to a dotted-quad IPv4 address or a name of
              an IPv4 network host.

       AF_INET6
              The name argument points to a hexadecimal IPv6 address or a name of
              an IPv6 network host.

       The flags argument specifies additional options.  More than one option can
       be specified by bitwise OR-ing them together.  flags should be set to 0 if
       no options are desired.

       AI_V4MAPPED
              This flag is used with AF_INET6 to request a query for IPv4
              addresses instead of IPv6 addresses; the IPv4 addresses will be
              mapped to IPv6 addresses.

       AI_ALL This flag is used with AI_V4MAPPED to request a query for both IPv4
              and IPv6 addresses.  Any IPv4 address found will be mapped to an
              IPv6 address.

       AI_ADDRCONFIG
              This flag is used with AF_INET6 to further request that queries for
              IPv6 addresses should not be made unless the system has at least one
              IPv6 address assigned to a network interface, and that queries for
              IPv4 addresses should not be made unless the system has at least one
              IPv4 address assigned to a network interface.  This flag may be used
              by itself or with the AI_V4MAPPED flag.

       AI_DEFAULT
              This flag is equivalent to (AI_ADDRCONFIG | AI_V4MAPPED).

getipnodebyaddr() arguments

       The getipnodebyaddr() function looks up the name of the host whose network
       address is specified by the addr argument.  The af argument specifies one
       of the following values:

       AF_INET
              The addr argument points to a struct in_addr and len must be set to
              sizeof(struct in_addr).

       AF_INET6
              The addr argument points to a struct in6_addr and len must be set to
              sizeof(struct in6_addr).

RETURN VALUE top

       A NULL pointer is returned if an error occurred, and error_num will contain
       an error code from the following list:

       HOST_NOT_FOUND
              The hostname or network address was not found.

       NO_ADDRESS
              The domain name server recognized the network address or name, but
              no answer was returned.  This can happen if the network host has
              only IPv4 addresses and a request has been made for IPv6 information
              only, or vice versa.

       NO_RECOVERY
              The domain name server returned a permanent failure response.

       TRY_AGAIN
              The domain name server returned a temporary failure response.  You
              might have better luck next time.

       A successful query returns a pointer to a hostent structure that contains
       the following fields:

       h_name This is the official name of this network host.

       h_aliases
              This is an array of pointers to unofficial aliases for the same
              host.  The array is terminated by a NULL pointer.

       h_addrtype
              This is a copy of the af argument to getipnodebyname() or
              getipnodebyaddr().  h_addrtype will always be AF_INET if the af
              argument was AF_INET.  h_addrtype will always be AF_INET6 if the af
              argument was AF_INET6.

       h_length
              This field will be set to sizeof(struct in_addr) if h_addrtype is
              AF_INET, and to sizeof(struct in6_addr) if h_addrtype is AF_INET6.

       h_addr_list
              This is an array of one or more pointers to network address
              structures for the network host.  The array is terminated by a NULL
              pointer.

CONFORMING TO top

       RFC 2553.

NOTES top

       These functions were present in glibc 2.1.91-95, but were removed again.
       Several UNIX-like systems support them, but all call them deprecated.

SEE ALSO top

       getaddrinfo(3), getnameinfo(3), inet_ntop(3), inet_pton(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-04                  GETIPNODEBYNAME(3)


getifaddrs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETIFADDRS(3)                Linux Programmer's Manual               GETIFADDRS(3)

NAME top

       getifaddrs, freeifaddrs - get interface addresses

SYNOPSIS top

       #include <sys/types.h>
       #include <ifaddrs.h>

       int getifaddrs(struct ifaddrs **ifap);

       void freeifaddrs(struct ifaddrs *ifa);

DESCRIPTION top

       The getifaddrs() function creates a linked list of structures describing
       the network interfaces of the local system, and stores the address of the
       first item of the list in *ifap.  The list consists of ifaddrs structures,
       defined as follows:

           struct ifaddrs {
               struct ifaddrs  *ifa_next;    /* Next item in list */
               char            *ifa_name;    /* Name of interface */
               unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
               struct sockaddr *ifa_addr;    /* Address of interface */
               struct sockaddr *ifa_netmask; /* Netmask of interface */
               union {
                   struct sockaddr *ifu_broadaddr;
                                    /* Broadcast address of interface */
                   struct sockaddr *ifu_dstaddr;
                                    /* Point-to-point destination address */
               } ifa_ifu;
           #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
           #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
               void            *ifa_data;    /* Address-specific data */
           };

       The ifa_next field contains a pointer to the next structure on the list, or
       NULL if this is the last item of the list.

       The ifa_name points to the null-terminated interface name.

       The ifa_flags field contains the interface flags, as returned by the
       SIOCGIFFLAGS ioctl(2) operation (see netdevice(7) for a list of these
       flags).

       The ifa_addr field points to a structure containing the interface address.
       (The sa_family subfield should be consulted to determine the format of the
       address structure.)  This field may contain a NULL pointer.

       The ifa_netmask field points to a structure containing the netmask
       associated with ifa_addr, if applicable for the address family.  This field
       may contain a NULL pointer.

       Depending on whether the bit IFF_BROADCAST or IFF_POINTOPOINT is set in
       ifa_flags (only one can be set at a time), either ifa_broadaddr will
       contain the broadcast address associated with ifa_addr (if applicable for
       the address family) or ifa_dstaddr will contain the destination address of
       the point-to-point interface.

       The ifa_data field points to a buffer containing address-family-specific
       data; this field may be NULL if there is no such data for this interface.

       The data returned by getifaddrs() is dynamically allocated and should be
       freed using freeifaddrs() when no longer needed.

RETURN VALUE top

       On success, getifaddrs() returns zero; on error, -1 is returned, and errno
       is set appropriately.

ERRORS top

       getifaddrs() may fail and set errno for any of the errors specified for
       socket(2), bind(2), getsockname(2), recvmsg(2), sendto(2), malloc(3), or
       realloc(3).

VERSIONS top

       The getifaddrs() function first appeared in glibc 2.3, but before glibc
       2.3.3, the implementation only supported IPv4 addresses; IPv6 support was
       added in glibc 2.3.3.  Support of address families other than IPv4 is only
       available on kernels that support netlink.

CONFORMING TO top

       Not in POSIX.1-2001.  This function first appeared in BSDi and is present
       on the BSD systems, but with slightly different semantics documented--
       returning one entry per interface, not per address.  This means ifa_addr
       and other fields can actually be NULL if the interface has no address, and
       no link-level address is returned if the interface has an IP address
       assigned.  Also, the way of choosing either ifa_broadaddr or ifa_dstaddr
       differs on various systems.

NOTES top

       The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
       assigned to the interface, but also one AF_PACKET address per interface
       containing lower-level details about the interface and its physical layer.
       In this case, the ifa_data field may contain a pointer to a struct
       rtnl_link_stats, defined in <linux/if_link.h> (in Linux 2.4 and earlier,
       struct net_device_stats, defined in <linux/netdevice.h>), which contains
       various interface attributes and statistics.

EXAMPLE top

       The program below demonstrates the use of getifaddrs(), freeifaddrs(), and
       getnameinfo(3).  Here is what we see when running this program on one
       system:

           $ ./a.out
           lo      address family: 17 (AF_PACKET)
           eth0    address family: 17 (AF_PACKET)
           lo      address family: 2 (AF_INET)
                   address: <127.0.0.1>
           eth0    address family: 2 (AF_INET)
                   address: <10.1.1.4>
           lo      address family: 10 (AF_INET6)
                   address: <::1>
           eth0    address family: 10 (AF_INET6)
                   address: <fe80::2d0:59ff:feda:eb51%eth0>

Program source

       #include <arpa/inet.h>
       #include <sys/socket.h>
       #include <netdb.h>
       #include <ifaddrs.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       int
       main(int argc, char *argv[])
       {
           struct ifaddrs *ifaddr, *ifa;
           int family, s;
           char host[NI_MAXHOST];

           if (getifaddrs(&ifaddr) == -1) {
               perror("getifaddrs");
               exit(EXIT_FAILURE);
           }

           /* Walk through linked list, maintaining head pointer so we
              can free list later */

           for (ifa = ifaddr; ifa != NULL; ifa = ifa->ifa_next) {
               if (ifa->ifa_addr == NULL)
                   continue;

               family = ifa->ifa_addr->sa_family;

               /* Display interface name and family (including symbolic
                  form of the latter for the common families) */

               printf("%s  address family: %d%s\n",
                       ifa->ifa_name, family,
                       (family == AF_PACKET) ? " (AF_PACKET)" :
                       (family == AF_INET) ?   " (AF_INET)" :
                       (family == AF_INET6) ?  " (AF_INET6)" : "");

               /* For an AF_INET* interface address, display the address */

               if (family == AF_INET || family == AF_INET6) {
                   s = getnameinfo(ifa->ifa_addr,
                           (family == AF_INET) ? sizeof(struct sockaddr_in) :
                                                 sizeof(struct sockaddr_in6),
                           host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST);
                   if (s != 0) {
                       printf("getnameinfo() failed: %s\n", gai_strerror(s));
                       exit(EXIT_FAILURE);
                   }
                   printf("\taddress: <%s>\n", host);
               }
           }

           freeifaddrs(ifaddr);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       bind(2), getsockname(2), socket(2), packet(7), ifconfig(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-11-11                       GETIFADDRS(3)


removexattr(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

REMOVEXATTR(2)               Linux Programmer's Manual              REMOVEXATTR(2)

NAME top

       removexattr, lremovexattr, fremovexattr - remove an extended attribute

SYNOPSIS top

       #include <sys/types.h>
       #include <attr/xattr.h>

       int removexattr(const char *path, const char *name);
       int lremovexattr(const char *path, const char *name);
       int fremovexattr(int fd, const char *name);

DESCRIPTION top

       Extended attributes are name:value pairs associated with inodes (files,
       directories, symbolic links, etc.).  They are extensions to the normal
       attributes which are associated with all inodes in the system (i.e., the
       stat(2) data).  A complete overview of extended attributes concepts can be
       found in attr(5).

       removexattr() removes the extended attribute identified by name and
       associated with the given path in the file system.

       lremovexattr() is identical to removexattr(), except in the case of a
       symbolic link, where the extended attribute is removed from the link
       itself, not the file that it refers to.

       fremovexattr() is identical to removexattr(), only the extended attribute
       is removed from the open file referred to by fd (as returned by open(2)) in
       place of path.

       An extended attribute name is a simple null-terminated string.  The name
       includes a namespace prefix; there may be several, disjoint namespaces
       associated with an individual inode.

RETURN VALUE top

       On success, zero is returned.  On failure, -1 is returned and errno is set
       appropriately.

       If the named attribute does not exist, errno is set to ENOATTR.

       If extended attributes are not supported by the file system, or are
       disabled, errno is set to ENOTSUP.

       The errors documented for the stat(2) system call are also applicable here.

VERSIONS top

       These system calls have been available on Linux since kernel 2.4; glibc
       support is provided since version 2.3.

CONFORMING TO top

       These system calls are Linux-specific.

SEE ALSO top

       getfattr(1), setfattr(1), getxattr(2), listxattr(2), open(2), setxattr(2),
       stat(2), attr(5), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2001-12-01                      REMOVEXATTR(2)


frexp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FREXP(3)                     Linux Programmer's Manual                    FREXP(3)

NAME top

       frexp,  frexpf,  frexpl  -  convert floating-point number to fractional and
       integral components

SYNOPSIS top

       #include <math.h>

       double frexp(double x, int *exp);
       float frexpf(float x, int *exp);
       long double frexpl(long double x, int *exp);

       Link with -lm.

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

       frexpf(), frexpl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The frexp() function is used to split the number x into a normalized
       fraction and an exponent which is stored in exp.

RETURN VALUE top

       The frexp() function returns the normalized fraction.  If the argument x is
       not zero, the normalized fraction is x times a power of two, and its
       absolute value is always in the range 1/2 (inclusive) to 1 (exclusive),
       that is, [0.5,1).

       If x is zero, then the normalized fraction is zero and zero is stored in
       exp.

       If x is a NaN, a NaN is returned, and the value of *exp is unspecified.

       If x is positive infinity (negative infinity), positive infinity (negative
       infinity) is returned, and the value of *exp is unspecified.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

EXAMPLE top

       The program below produces results such as the following:

           $ ./a.out 2560
           frexp(2560, &e) = 0.625: 0.625 * 2^12 = 2560
           $ ./a.out -4
           frexp(-4, &e) = -0.5: -0.5 * 2^3 = -4

Program source

       #include <math.h>
       #include <float.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           double x, r;
           int exp;

           x = strtod(argv[1], NULL);
           r = frexp(x, &exp);

           printf("frexp(%g, &e) = %g: %g * %d^%d = %g\n",
                  x, r, r, FLT_RADIX, exp, x);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       ldexp(3), modf(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            FREXP(3)


scanf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SCANF(3)                     Linux Programmer's Manual                    SCANF(3)

NAME top

       scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conversion

SYNOPSIS top

       #include <stdio.h>

       int scanf(const char *format, ...);
       int fscanf(FILE *stream, const char *format, ...);
       int sscanf(const char *str, const char *format, ...);

       #include <stdarg.h>

       int vscanf(const char *format, va_list ap);
       int vsscanf(const char *str, const char *format, va_list ap);
       int vfscanf(FILE *stream, const char *format, va_list ap);

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

       vscanf(), vsscanf(), vfscanf():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The scanf() family of functions scans input according to format as
       described below.  This format may contain conversion specifications; the
       results from such conversions, if any, are stored in the locations pointed
       to by the pointer arguments that follow format.  Each pointer argument must
       be of a type that is appropriate for the value returned by the
       corresponding conversion specification.

       If the number of conversion specifications in format exceeds the number of
       pointer arguments, the results are undefined.  If the number of pointer
       arguments exceeds the number of conversion specifications, then the excess
       pointer arguments are evaluated, but are otherwise ignored.

       The scanf() function reads input from the standard input stream stdin,
       fscanf() reads input from the stream pointer stream, and sscanf() reads its
       input from the character string pointed to by str.

       The vfscanf() function is analogous to vfprintf(3) and reads input from the
       stream pointer stream using a variable argument list of pointers (see
       stdarg(3).  The vscanf() function scans a variable argument list from the
       standard input and the vsscanf() function scans it from a string; these are
       analogous to the vprintf(3) and vsprintf(3) functions respectively.

       The format string consists of a sequence of directives which describe how
       to process the sequence of input characters.  If processing of a directive
       fails, no further input is read, and scanf() returns.  A "failure" can be
       either of the following: input failure, meaning that input characters were
       unavailable, or matching failure, meaning that the input was inappropriate
       (see below).

       A directive is one of the following:

       +o      A sequence of white-space characters (space, tab, newline, etc.; see
              isspace(3)).  This directive matches any amount of white space,
              including none, in the input.

       +o      An ordinary character (i.e., one other than white space or '%').
              This character must exactly match the next character of input.

       +o      A conversion specification, which commences with a '%' (percent)
              character.  A sequence of characters from the input is converted
              according to this specification, and the result is placed in the
              corresponding pointer argument.  If the next item of input does not
              match the conversion specification, the conversion fails--this is a
              matching failure.

       Each conversion specification in format begins with either the character
       '%' or the character sequence "%n$" (see below for the distinction)
       followed by:

       +o      An optional '*' assignment-suppression character: scanf() reads
              input as directed by the conversion specification, but discards the
              input.  No corresponding pointer argument is required, and this
              specification is not included in the count of successful assignments
              returned by scanf().

       +o      An optional 'a' character.  This is used with string conversions,
              and relieves the caller of the need to allocate a corresponding
              buffer to hold the input: instead, scanf() allocates a buffer of
              sufficient size, and assigns the address of this buffer to the
              corresponding pointer argument, which should be a pointer to a char
              * variable (this variable does not need to be initialized before the
              call).  The caller should subsequently free(3) this buffer when it
              is no longer required.  This is a GNU extension; C99 employs the 'a'
              character as a conversion specifier (and it can also be used as such
              in the GNU implementation).

       +o      An optional decimal integer which specifies the maximum field width.
              Reading of characters stops either when this maximum is reached or
              when a nonmatching character is found, whichever happens first.
              Most conversions discard initial white space characters (the
              exceptions are noted below), and these discarded characters don't
              count toward the maximum field width.  String input conversions
              store a terminating null byte ('\0') to mark the end of the input;
              the maximum field width does not include this terminator.

       +o      An optional type modifier character.  For example, the l type
              modifier is used with integer conversions such as %d to specify that
              the corresponding pointer argument refers to a long int rather than
              a pointer to an int.

       +o      A conversion specifier that specifies the type of input conversion
              to be performed.

       The conversion specifications in format are of two forms, either beginning
       with '%' or beginning with "%n$".  The two forms should not be mixed in the
       same format string, except that a string containing "%n$" specifications
       can include %% and %*.  If format contains '%' specifications then these
       correspond in order with successive pointer arguments.  In the "%n$" form
       (which is specified in POSIX.1-2001, but not C99), n is a decimal integer
       that specifies that the converted input should be placed in the location
       referred to by the n-th pointer argument following format.

Conversions

       The following type modifier characters can appear in a conversion
       specification:

       h      Indicates that the conversion will be one of d, i, o, u, x, X, or n
              and the next pointer is a pointer to a short int or unsigned short
              int (rather than int).

       hh     As for h, but the next pointer is a pointer to a signed char or
              unsigned char.

       j      As for h, but the next pointer is a pointer to an intmax_t or a
              uintmax_t.  This modifier was introduced in C99.

       l      Indicates either that the conversion will be one of d, i, o, u, x,
              X, or n and the next pointer is a pointer to a long int or unsigned
              long int (rather than int), or that the conversion will be one of e,
              f, or g and the next pointer is a pointer to double (rather than
              float).  Specifying two l characters is equivalent to L.  If used
              with %c or %s the corresponding parameter is considered as a pointer
              to a wide character or wide-character string respectively.

       L      Indicates that the conversion will be either e, f, or g and the next
              pointer is a pointer to long double or the conversion will be d, i,
              o, u, or x and the next pointer is a pointer to long long.

       q      equivalent to L.  This specifier does not exist in ANSI C.

       t      As for h, but the next pointer is a pointer to a ptrdiff_t.  This
              modifier was introduced in C99.

       z      As for h, but the next pointer is a pointer to a size_t.  This
              modifier was introduced in C99.

       The following conversion specifiers are available:

       %      Matches a literal '%'.  That is, %% in the format string matches a
              single input '%' character.  No conversion is done (but initial
              white space characters are discarded), and assignment does not
              occur.

       d      Matches an optionally signed decimal integer; the next pointer must
              be a pointer to int.

       D      Equivalent to ld; this exists only for backward compatibility.
              (Note: thus only in libc4.  In libc5 and glibc the %D is silently
              ignored, causing old programs to fail mysteriously.)

       i      Matches an optionally signed integer; the next pointer must be a
              pointer to int.  The integer is read in base 16 if it begins with 0x
              or 0X, in base 8 if it begins with 0, and in base 10 otherwise.
              Only characters that correspond to the base are used.

       o      Matches an unsigned octal integer; the next pointer must be a
              pointer to unsigned int.

       u      Matches an unsigned decimal integer; the next pointer must be a
              pointer to unsigned int.

       x      Matches an unsigned hexadecimal integer; the next pointer must be a
              pointer to unsigned int.

       X      Equivalent to x.

       f      Matches an optionally signed floating-point number; the next pointer
              must be a pointer to float.

       e      Equivalent to f.

       g      Equivalent to f.

       E      Equivalent to f.

       a      (C99) Equivalent to f.

       s      Matches a sequence of non-white-space characters; the next pointer
              must be a pointer to character array that is long enough to hold the
              input sequence and the terminating null byte ('\0'), which is added
              automatically.  The input string stops at white space or at the
              maximum field width, whichever occurs first.

       c      Matches a sequence of characters whose length is specified by the
              maximum field width (default 1); the next pointer must be a pointer
              to char, and there must be enough room for all the characters (no
              terminating null byte is added).  The usual skip of leading white
              space is suppressed.  To skip white space first, use an explicit
              space in the format.

       [      Matches a nonempty sequence of characters from the specified set of
              accepted characters; the next pointer must be a pointer to char, and
              there must be enough room for all the characters in the string, plus
              a terminating null byte.  The usual skip of leading white space is
              suppressed.  The string is to be made up of characters in (or not
              in) a particular set; the set is defined by the characters between
              the open bracket [ character and a close bracket ] character.  The
              set excludes those characters if the first character after the open
              bracket is a circumflex (^).  To include a close bracket in the set,
              make it the first character after the open bracket or the
              circumflex; any other position will end the set.  The hyphen
              character - is also special; when placed between two other
              characters, it adds all intervening characters to the set.  To
              include a hyphen, make it the last character before the final close
              bracket.  For instance, [^]0-9-] means the set "everything except
              close bracket, zero through nine, and hyphen".  The string ends with
              the appearance of a character not in the (or, with a circumflex, in)
              set or when the field width runs out.

       p      Matches a pointer value (as printed by %p in printf(3); the next
              pointer must be a pointer to a pointer to void.

       n      Nothing is expected; instead, the number of characters consumed thus
              far from the input is stored through the next pointer, which must be
              a pointer to int.  This is not a conversion, although it can be
              suppressed with the * assignment-suppression character.  The C
              standard says: "Execution of a %n directive does not increment the
              assignment count returned at the completion of execution" but the
              Corrigendum seems to contradict this.  Probably it is wise not to
              make any assumptions on the effect of %n conversions on the return
              value.

RETURN VALUE top

       These functions return the number of input items successfully matched and
       assigned, which can be fewer than provided for, or even zero in the event
       of an early matching failure.

       The value EOF is returned if the end of input is reached before either the
       first successful conversion or a matching failure occurs.  EOF is also
       returned if a read error occurs, in which case the error indicator for the
       stream (see ferror(3)) is set, and errno is set indicate the error.

ERRORS top

       EAGAIN The file descriptor underlying stream is marked nonblocking, and the
              read operation would block.

       EBADF  The file descriptor underlying stream is invalid, or not open for
              reading.

       EILSEQ Input byte sequence does not form a valid character.

       EINTR  The read operation was interrupted by a signal; see signal(7).

       EINVAL Not enough arguments; or format is NULL.

       ENOMEM Out of memory.

       ERANGE The result of an integer conversion would exceed the size that can
              be stored in the corresponding integer type.

CONFORMING TO top

       The functions fscanf(), scanf(), and sscanf() conform to C89 and C99 and
       POSIX.1-2001.  These standards do not specify the ERANGE error.

       The q specifier is the 4.4BSD notation for long long, while ll or the usage
       of L in integer conversions is the GNU notation.

       The Linux version of these functions is based on the GNU libio library.
       Take a look at the info documentation of GNU libc (glibc-1.08) for a more
       concise description.

NOTES top

       The GNU C library supports a nonstandard extension that causes the library
       to dynamically allocate a string of sufficient size for input strings for
       the %s and %a[range] conversion specifiers.  To make use of this feature,
       specify a as a length modifier (thus %as or %a[range]).  The caller must
       free(3) the returned string, as in the following example:

           char *p;
           int n;

           errno = 0;
           n = scanf("%a[a-z]", &p);
           if (n == 1) {
               printf("read: %s\n", p);
               free(p);
           } else if (errno != 0) {
               perror("scanf");
           } else {
               fprintf(stderr, "No matching characters\n");
           }

       As shown in the above example, it is only necessary to call free(3) if the
       scanf() call successfully read a string.

       The a modifier is not available if the program is compiled with gcc
       -std=c99 or gcc -D_ISOC99_SOURCE (unless _GNU_SOURCE is also specified), in
       which case the a is interpreted as a specifier for floating-point numbers
       (see above).

       Since version 2.7, glibc also provides the m modifier for the same purpose
       as the a modifier.  The m modifier has the following advantages:

       * It may also be applied to %c conversion specifiers (e.g., %3mc).

       * It avoids ambiguity with respect to the %a floating-point conversion
         specifier (and is unaffected by gcc -std=c99 etc.)

       * It is specified in the upcoming revision of the POSIX.1 standard.

BUGS top

       All functions are fully C89 conformant, but provide the additional
       specifiers q and a as well as an additional behavior of the L and l
       specifiers.  The latter may be considered to be a bug, as it changes the
       behavior of specifiers defined in C89.

       Some combinations of the type modifiers and conversion specifiers defined
       by ANSI C do not make sense (e.g., %Ld).  While they may have a well-
       defined behavior on Linux, this need not to be so on other architectures.
       Therefore it usually is better to use modifiers that are not defined by
       ANSI C at all, that is, use q instead of L in combination with d, i, o, u,
       x, and X conversions or ll.

       The usage of q is not the same as on 4.4BSD, as it may be used in float
       conversions equivalently to L.

SEE ALSO top

       getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                            SCANF(3)


fseeko(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FSEEKO(3)                    Linux Programmer's Manual                   FSEEKO(3)

NAME top

       fseeko, ftello - seek to or report file position

SYNOPSIS top

       #include <stdio.h>

       int fseeko(FILE *stream, off_t offset, int whence);

       off_t ftello(FILE *stream);

DESCRIPTION top

       The fseeko() and ftello() functions are identical to fseek(3) and ftell(3)
       (see fseek(3)), respectively, except that the offset argument of fseeko()
       and the return value of ftello() is of type off_t instead of long.

       On many architectures both off_t and long are 32-bit types, but compilation
       with

              #define _FILE_OFFSET_BITS 64

       will turn off_t into a 64-bit type.

RETURN VALUE top

       On successful completion, fseeko() returns 0, while ftello() returns the
       current offset.  Otherwise, -1 is returned and errno is set to indicate the
       error.

ERRORS top

       See the ERRORS in fseek(3).

CONFORMING TO top

       SUSv2, POSIX.1-2001.

NOTES top

       These functions are found on System V-like systems.  They are not present
       in libc4, libc5, glibc 2.0 but are available since glibc 2.1.

SEE ALSO top

       fseek(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-11-05                           FSEEKO(3)


setxattr(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SETXATTR(2)                  Linux Programmer's Manual                 SETXATTR(2)

NAME top

       setxattr, lsetxattr, fsetxattr - set an extended attribute value

SYNOPSIS top

       #include <sys/types.h>
       #include <attr/xattr.h>

       int setxattr(const char *path, const char *name,
                     const void *value, size_t size, int flags);
       int lsetxattr(const char *path, const char *name,
                     const void *value, size_t size, int flags);
       int fsetxattr(int fd, const char *name,
                     const void *value, size_t size, int flags);

DESCRIPTION top

       Extended attributes are name:value pairs associated with inodes (files,
       directories, symbolic links, etc.).  They are extensions to the normal
       attributes which are associated with all inodes in the system (i.e., the
       stat(2) data).  A complete overview of extended attributes concepts can be
       found in attr(5).

       setxattr() sets the value of the extended attribute identified by name and
       associated with the given path in the file system.  The size of the value
       must be specified.

       lsetxattr() is identical to setxattr(), except in the case of a symbolic
       link, where the extended attribute is set on the link itself, not the file
       that it refers to.

       fsetxattr() is identical to setxattr(), only the extended attribute is set
       on the open file referred to by fd (as returned by open(2)) in place of
       path.

       An extended attribute name is a simple null-terminated string.  The name
       includes a namespace prefix; there may be several, disjoint namespaces
       associated with an individual inode.  The value of an extended attribute is
       a chunk of arbitrary textual or binary data of specified length.

       The flags argument can be used to refine the semantics of the operation.
       XATTR_CREATE specifies a pure create, which fails if the named attribute
       exists already.  XATTR_REPLACE specifies a pure replace operation, which
       fails if the named attribute does not already exist.  By default (no
       flags), the extended attribute will be created if need be, or will simply
       replace the value if the attribute exists.

RETURN VALUE top

       On success, zero is returned.  On failure, -1 is returned and errno is set
       appropriately.

       If XATTR_CREATE is specified, and the attribute exists already, errno is
       set to EEXIST.  If XATTR_REPLACE is specified, and the attribute does not
       exist, errno is set to ENOATTR.

       If there is insufficient space remaining to store the extended attribute,
       errno is set to either ENOSPC, or EDQUOT if quota enforcement was the
       cause.

       If extended attributes are not supported by the file system, or are
       disabled, errno is set to ENOTSUP.

       The errors documented for the stat(2) system call are also applicable here.

VERSIONS top

       These system calls have been available on Linux since kernel 2.4; glibc
       support is provided since version 2.3.

CONFORMING TO top

       These system calls are Linux-specific.

SEE ALSO top

       getfattr(1), setfattr(1), getxattr(2), listxattr(2), open(2),
       removexattr(2), stat(2), attr(5), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2001-12-31                         SETXATTR(2)


stat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

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

NAME top

       stat, fstat, lstat - get file status

SYNOPSIS top

       #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 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       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 symbolic link is the length of the
       pathname it contains, without a terminating 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).)
       In addition, st_atime is not updated if a file is opened with the
       O_NOATIME; see open(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 top

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

ERRORS top

       EACCES Search permission is denied for one of the directories in the path
              prefix of path.  (See also path_resolution(7).)

       EBADF  fd is bad.

       EFAULT Bad address.

       ELOOP  Too many symbolic links encountered while traversing the path.

       ENAMETOOLONG
              path is too long.

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

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

       ENOTDIR
              A component of the path prefix of path is not a directory.

       EOVERFLOW
              path or fd refers to a file whose size, inode number, or number of
              blocks cannot be represented in, respectively, the types off_t,
              ino_t, or blkcnt_t.  This error can occur when, for example, an
              application compiled on a 32-bit platform without
              -D_FILE_OFFSET_BITS=64 calls stat() on a file whose size exceeds
              (1<<31)-1 bytes.

CONFORMING TO top

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

       According to POSIX.1-2001, lstat() on a symbolic link need return valid
       information only in the st_size field and the file-type component of the
       st_mode field of the stat structure.  POSIX.-2008 tightens the
       specification, requiring lstat() to return valid information in all fields
       except the permission bits in st_mode.

       Use of the st_blocks and st_blksize fields may be less portable.  (They
       were introduced in BSD.  The interpretation differs between systems, and
       possibly on a single system when NFS mounts are involved.)  If you need to
       obtain the definition of the blkcnt_t or blksize_t types from <sys/stat.h>,
       then define _XOPEN_SOURCE with the value 500 or greater (before including
       any header files).

       POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG,
       S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX constants, but instead demanded
       the use of the macros S_ISDIR(), etc.  The S_IF* constants are present in
       POSIX.1-2001 and later.

       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 user space)
       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 nondirectories: 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 top

       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 of the form st_atim.tv_nsec if the _BSD_SOURCE or
       _SVID_SOURCE feature test macro is defined.  These fields are specified  in
       POSIX.1-2008,  and,  starting  with  version 2.12, glibc also exposes these
       field names if  _POSIX_C_SOURCE  is  defined  with  the  value  200809L  or
       greater,  or  _XOPEN_SOURCE  is  defined with the value 700 or greater.  If
       none of the aforementioned macros are defined, then the  nanosecond  values
       are  exposed  with names of the form st_atimensec.  On file systems that do
       not support subsecond timestamps, the nanosecond fields are  returned  with
       the value 0.

       On  Linux,  lstat()  will generally not trigger automounter action, whereas
       stat() will (but see fstatat(2)).

       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 system call provided
       by the kernel, and repacking the returned information if required  for  old
       binaries.  Similar remarks apply for fstat() and lstat().

EXAMPLE top

       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_FAILURE);
           }

           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 top

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

COLOPHON top

       This  page  is  part  of  release  3.45  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                               2012-11-11                             STAT(2)


fstatat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FSTATAT(2)                   Linux Programmer's Manual                  FSTATAT(2)

NAME top

       fstatat - get file status relative to a directory file descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <sys/stat.h>

       int fstatat(int dirfd, const char *pathname, struct stat *buf,
                   int flags);

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

       fstatat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The fstatat() system call operates in exactly the same way as stat(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by stat(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like stat(2)).

       If pathname is absolute, then dirfd is ignored.

       flags can either be 0, or include one or more of the following flags ORed:

       AT_NO_AUTOMOUNT (since Linux 2.6.38)
              Don't automount the terminal ("basename") component of pathname if
              it is a directory that is an automount point.  This allows the
              caller to gather attributes of an automount point (rather than the
              location it would mount).  This flag can be used in tools that scan
              directories to prevent mass-automounting of a directory of automount
              points.  The AT_NO_AUTOMOUNT flag has no effect if the mount point
              has already been mounted over.

       AT_SYMLINK_NOFOLLOW
              If pathname is a symbolic link, do not dereference it: instead
              return information about the link itself, like lstat(2).  (By
              default, fstatat() dereferences symbolic links, like stat(2).)

RETURN VALUE top

       On success, fstatat() returns 0.  On error, -1 is returned and errno is set
       to indicate the error.

ERRORS top

       The same errors that occur for stat(2) can also occur for fstatat().  The
       following additional errors can occur for fstatat():

       EBADF  dirfd is not a valid file descriptor.

       EINVAL Invalid flag specified in flags.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       fstatat() was added to Linux in kernel 2.6.16; library support was added to
       glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.  A similar system call exists on Solaris.

NOTES top

       See openat(2) for an explanation of the need for fstatat().

       The underlying system call employed by the glibc fstatat() wrapper function
       is actually called fstatat64().

SEE ALSO top

       openat(2), stat(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                          FSTATAT(2)


statfs(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

STATFS(2)                    Linux Programmer's Manual                   STATFS(2)

NAME top

       statfs, fstatfs - get file system statistics

SYNOPSIS top

       #include <sys/vfs.h>    /* or <sys/statfs.h> */

       int statfs(const char *path, struct statfs *buf);
       int fstatfs(int fd, struct statfs *buf);

DESCRIPTION top

       The function statfs() returns information about a mounted file system.
       path is the pathname of any file within the mounted file system.  buf is a
       pointer to a statfs structure defined approximately as follows:

           #if __WORDSIZE == 32          /* System word size */
           # define __SWORD_TYPE           int
           #else /* __WORDSIZE == 64 */
           # define __SWORD_TYPE         long int
           #endif

           struct statfs {
               __SWORD_TYPE f_type;    /* type of file system (see below) */
               __SWORD_TYPE f_bsize;   /* optimal transfer block size */
               fsblkcnt_t   f_blocks;  /* total data blocks in file system */
               fsblkcnt_t   f_bfree;   /* free blocks in fs */
               fsblkcnt_t   f_bavail;  /* free blocks available to
                                          unprivileged user */
               fsfilcnt_t   f_files;   /* total file nodes in file system */
               fsfilcnt_t   f_ffree;   /* free file nodes in fs */
               fsid_t       f_fsid;    /* file system id */
               __SWORD_TYPE f_namelen; /* maximum length of filenames */
               __SWORD_TYPE f_frsize;  /* fragment size (since Linux 2.6) */
               __SWORD_TYPE f_spare[5];
           };

           File system types:

              ADFS_SUPER_MAGIC      0xadf5
              AFFS_SUPER_MAGIC      0xADFF
              BEFS_SUPER_MAGIC      0x42465331
              BFS_MAGIC             0x1BADFACE
              CIFS_MAGIC_NUMBER     0xFF534D42
              CODA_SUPER_MAGIC      0x73757245
              COH_SUPER_MAGIC       0x012FF7B7
              CRAMFS_MAGIC          0x28cd3d45
              DEVFS_SUPER_MAGIC     0x1373
              EFS_SUPER_MAGIC       0x00414A53
              EXT_SUPER_MAGIC       0x137D
              EXT2_OLD_SUPER_MAGIC  0xEF51
              EXT2_SUPER_MAGIC      0xEF53
              EXT3_SUPER_MAGIC      0xEF53
              EXT4_SUPER_MAGIC      0xEF53
              HFS_SUPER_MAGIC       0x4244
              HPFS_SUPER_MAGIC      0xF995E849
              HUGETLBFS_MAGIC       0x958458f6
              ISOFS_SUPER_MAGIC     0x9660
              JFFS2_SUPER_MAGIC     0x72b6
              JFS_SUPER_MAGIC       0x3153464a
              MINIX_SUPER_MAGIC     0x137F /* orig. minix */
              MINIX_SUPER_MAGIC2    0x138F /* 30 char minix */
              MINIX2_SUPER_MAGIC    0x2468 /* minix V2 */
              MINIX2_SUPER_MAGIC2   0x2478 /* minix V2, 30 char names */
              MSDOS_SUPER_MAGIC     0x4d44
              NCP_SUPER_MAGIC       0x564c
              NFS_SUPER_MAGIC       0x6969
              NTFS_SB_MAGIC         0x5346544e
              OPENPROM_SUPER_MAGIC  0x9fa1
              PROC_SUPER_MAGIC      0x9fa0
              QNX4_SUPER_MAGIC      0x002f
              REISERFS_SUPER_MAGIC  0x52654973
              ROMFS_MAGIC           0x7275
              SMB_SUPER_MAGIC       0x517B
              SYSV2_SUPER_MAGIC     0x012FF7B6
              SYSV4_SUPER_MAGIC     0x012FF7B5
              TMPFS_MAGIC           0x01021994
              UDF_SUPER_MAGIC       0x15013346
              UFS_MAGIC             0x00011954
              USBDEVICE_SUPER_MAGIC 0x9fa2
              VXFS_SUPER_MAGIC      0xa501FCF5
              XENIX_SUPER_MAGIC     0x012FF7B4
              XFS_SUPER_MAGIC       0x58465342
              _XIAFS_SUPER_MAGIC    0x012FD16D

       Nobody knows what f_fsid is supposed to contain (but see below).

       Fields that are undefined for a particular file system are set to 0.
       fstatfs() returns the same information about an open file referenced by
       descriptor fd.

RETURN VALUE top

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

ERRORS top

       EACCES (statfs()) Search permission is denied for a component of the path
              prefix of path.  (See also path_resolution(7).)

       EBADF  (fstatfs()) fd is not a valid open file descriptor.

       EFAULT buf or path points to an invalid address.

       EINTR  This call was interrupted by a signal.

       EIO    An I/O error occurred while reading from the file system.

       ELOOP  (statfs()) Too many symbolic links were encountered in translating
              path.

       ENAMETOOLONG
              (statfs()) path is too long.

       ENOENT (statfs()) The file referred to by path does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOSYS The file system does not support this call.

       ENOTDIR
              (statfs()) A component of the path prefix of path is not a
              directory.

       EOVERFLOW
              Some values were too large to be represented in the returned struct.

CONFORMING TO top

       Linux-specific.  The Linux statfs() was inspired by the 4.4BSD one (but
       they do not use the same structure).

NOTES top

       The original Linux statfs() and fstatfs() system calls were not designed
       with extremely large file sizes in mind.  Subsequently, Linux 2.6 added new
       statfs64() and fstatfs64() system calls that employ a new structure,
       statfs64.  The new structure contains the same fields as the original
       statfs structure, but the sizes of various fields are increased, to
       accommodate large file sizes.  The glibc statfs() and fstatfs() wrapper
       functions transparently deal with the kernel differences.

       Some systems only have <sys/vfs.h>, other systems also have <sys/statfs.h>,
       where the former includes the latter.  So it seems including the former is
       the best choice.

       LSB has deprecated the library calls statfs() and fstatfs() and tells us to
       use statvfs(2) and fstatvfs(2) instead.

The f_fsid field

       Solaris, Irix and POSIX have a system call statvfs(2) that returns a struct
       statvfs (defined in <sys/statvfs.h>) containing an unsigned long f_fsid.
       Linux, SunOS, HP-UX, 4.4BSD have a system call statfs() that returns a
       struct statfs (defined in <sys/vfs.h>) containing a fsid_t f_fsid, where
       fsid_t is defined as struct { int val[2]; }.  The same holds for FreeBSD,
       except that it uses the include file <sys/mount.h>.

       The general idea is that f_fsid contains some random stuff such that the
       pair (f_fsid,ino) uniquely determines a file.  Some operating systems use
       (a variation on) the device number, or the device number combined with the
       file-system type.  Several OSes restrict giving out the f_fsid field to the
       superuser only (and zero it for unprivileged users), because this field is
       used in the filehandle of the file system when NFS-exported, and giving it
       out is a security concern.

       Under some operating systems the fsid can be used as second argument to the
       sysfs(2) system call.

SEE ALSO top

       stat(2), statvfs(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-21                           STATFS(2)


statvfs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

STATVFS(3)                   Linux Programmer's Manual                  STATVFS(3)

NAME top

       statvfs, fstatvfs - get file system statistics

SYNOPSIS top

       #include <sys/statvfs.h>

       int statvfs(const char *path, struct statvfs *buf);
       int fstatvfs(int fd, struct statvfs *buf);

DESCRIPTION top

       The function statvfs() returns information about a mounted file system.
       path is the pathname of any file within the mounted file system.  buf is a
       pointer to a statvfs structure defined approximately as follows:

           struct statvfs {
               unsigned long  f_bsize;    /* file system block size */
               unsigned long  f_frsize;   /* fragment size */
               fsblkcnt_t     f_blocks;   /* size of fs in f_frsize units */
               fsblkcnt_t     f_bfree;    /* # free blocks */
               fsblkcnt_t     f_bavail;   /* # free blocks for unprivileged users */
               fsfilcnt_t     f_files;    /* # inodes */
               fsfilcnt_t     f_ffree;    /* # free inodes */
               fsfilcnt_t     f_favail;   /* # free inodes for unprivileged users */
               unsigned long  f_fsid;     /* file system ID */
               unsigned long  f_flag;     /* mount flags */
               unsigned long  f_namemax;  /* maximum filename length */
           };

       Here the types fsblkcnt_t and fsfilcnt_t are defined in <sys/types.h>.
       Both used to be unsigned long.

       The field f_flag is a bit mask (of mount flags, see mount(8)).  Bits
       defined by POSIX are

       ST_RDONLY
              Read-only file system.

       ST_NOSUID
              Set-user-ID/set-group-ID bits are ignored by exec(3).

       It is unspecified whether all members of the returned struct have
       meaningful values on all file systems.

       fstatvfs() returns the same information about an open file referenced by
       descriptor fd.

RETURN VALUE top

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

ERRORS top

       EACCES (statvfs()) Search permission is denied for a component of the path
              prefix of path.  (See also path_resolution(7).)

       EBADF  (fstatvfs()) fd is not a valid open file descriptor.

       EFAULT Buf or path points to an invalid address.

       EINTR  This call was interrupted by a signal.

       EIO    An I/O error occurred while reading from the file system.

       ELOOP  (statvfs()) Too many symbolic links were encountered in translating
              path.

       ENAMETOOLONG
              (statvfs()) path is too long.

       ENOENT (statvfs()) The file referred to by path does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOSYS The file system does not support this call.

       ENOTDIR
              (statvfs()) A component of the path prefix of path is not a
              directory.

       EOVERFLOW
              Some values were too large to be represented in the returned struct.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The Linux kernel has system calls statfs(2) and fstatfs(2) to support this
       library call.

       The current glibc implementations of

          pathconf(path, _PC_REC_XFER_ALIGN);
          pathconf(path, _PC_ALLOC_SIZE_MIN);
          pathconf(path, _PC_REC_MIN_XFER_SIZE);

       respectively use the f_frsize, f_frsize, and f_bsize fields of the return
       value of statvfs(path,buf).

SEE ALSO top

       statfs(2)

COLOPHON top

       This page is part of release 3.45 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                               2003-08-22                          STATVFS(3)


ftime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

FTIME(3)                     Linux Programmer's Manual                    FTIME(3)

NAME top

       ftime - return date and time

SYNOPSIS top

       #include <sys/timeb.h>

       int ftime(struct timeb *tp);

DESCRIPTION top

       This function returns the current time as seconds and milliseconds since
       the Epoch, 1970-01-01 00:00:00 +0000 (UTC).  The time is returned in tp,
       which is declared as follows:

           struct timeb {
               time_t         time;
               unsigned short millitm;
               short          timezone;
               short          dstflag;
           };

       Here time is the number of seconds since the Epoch, and millitm is the
       number of milliseconds since time seconds since the Epoch.  The timezone
       field is the local timezone measured in minutes of time west of Greenwich
       (with a negative value indicating minutes east of Greenwich).  The dstflag
       field is a flag that, if nonzero, indicates that Daylight Saving time
       applies locally during the appropriate part of the year.

       POSIX.1-2001 says that the contents of the timezone and dstflag fields are
       unspecified; avoid relying on them.

RETURN VALUE top

       This function always returns 0.  (POSIX.1-2001 specifies, and some systems
       document, a -1 error return.)

CONFORMING TO top

       4.2BSD, POSIX.1-2001.  POSIX.1-2008 removes the specification of ftime().

       This function is obsolete.  Don't use it.  If the time in seconds suffices,
       time(2) can be used; gettimeofday(2) gives microseconds; clock_gettime(2)
       gives nanoseconds but is not as widely available.

BUGS top

       Under libc4 and libc5 the millitm field is meaningful.  But early glibc2 is
       buggy and returns 0 there; glibc 2.1.1 is correct again.

SEE ALSO top

       gettimeofday(2), time(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-02-25                            FTIME(3)


ftok(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FTOK(3)                      Linux Programmer's Manual                     FTOK(3)

NAME top

       ftok - convert a pathname and a project identifier to a System V IPC key

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>

       key_t ftok(const char *pathname, int proj_id);

DESCRIPTION top

       The ftok() function uses the identity of the file named by the given
       pathname (which must refer to an existing, accessible file) and the least
       significant 8 bits of proj_id (which must be nonzero) to generate a key_t
       type System V IPC key, suitable for use with msgget(2), semget(2), or
       shmget(2).

       The resulting value is the same for all pathnames that name the same file,
       when the same value of proj_id is used.  The value returned should be
       different when the (simultaneously existing) files or the project IDs
       differ.

RETURN VALUE top

       On success, the generated key_t value is returned.  On failure -1 is
       returned, with errno indicating the error as for the stat(2) system call.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Under libc4 and libc5 (and under SunOS 4.x) the prototype was:

              key_t ftok(char *pathname, char proj_id);

       Today proj_id is an int, but still only 8 bits are used.  Typical usage has
       an ASCII character proj_id, that is why the behavior is said to be
       undefined when proj_id is zero.

       Of course no guarantee can be given that the resulting key_t is unique.
       Typically, a best effort attempt combines the given proj_id byte, the lower
       16 bits of the inode number, and the lower 8 bits of the device number into
       a 32-bit result.  Collisions may easily happen, for example between files
       on /dev/hda1 and files on /dev/sda1.

SEE ALSO top

       msgget(2), semget(2), shmget(2), stat(2), svipc(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2001-11-28                             FTOK(3)


ftpusers(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

FTPUSERS(5)                  Linux Programmer's Manual                 FTPUSERS(5)

NAME top

       ftpusers - list of users that may not log in via the FTP daemon

DESCRIPTION top

       The text file ftpusers contains a list of users that may not log in using
       the File Transfer Protocol (FTP) server daemon.  This file is used not
       merely for system administration purposes but for improving security within
       a TCP/IP networked environment.  It will typically contain a list of the
       users that either have no business using ftp or have too many privileges to
       be allowed to log in through the FTP server daemon.  Such users usually
       include root, daemon, bin, uucp, and news.  If your FTP server daemon
       doesn't use ftpusers then it is suggested that you read its documentation
       to find out how to block access for certain users.  Washington University
       FTP server Daemon (wuftpd) and Professional FTP Daemon (proftpd) are known
       to make use of ftpusers.

Format

       The format of ftpusers is very simple.  There is one account name (or
       username) per line.  Lines starting with a # are ignored.

FILES top

       /etc/ftpusers

SEE ALSO top

       passwd(5), proftpd(8), wuftpd(8)

COLOPHON top

       This page is part of release 3.45 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-08-27                         FTPUSERS(5)


truncate(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TRUNCATE(2)                  Linux Programmer's Manual                 TRUNCATE(2)

NAME top

       truncate, ftruncate - truncate a file to a specified length

SYNOPSIS top

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

       int truncate(const char *path, off_t length);
       int ftruncate(int fd, off_t length);

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

       truncate():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

       ftruncate():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       The truncate() and ftruncate() functions cause the regular file named by
       path or referenced by fd to be truncated to a size of precisely length
       bytes.

       If the file previously was larger than this size, the extra data is lost.
       If the file previously was shorter, it is extended, and the extended part
       reads as null bytes ('\0').

       The file offset is not changed.

       If the size changed, then the st_ctime and st_mtime fields (respectively,
       time of last status change and time of last modification; see stat(2)) for
       the file are updated, and the set-user-ID and set-group-ID permission bits
       may be cleared.

       With ftruncate(), the file must be open for writing; with truncate(), the
       file must be writable.

RETURN VALUE top

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

ERRORS top

       For truncate():

       EACCES Search permission is denied for a component of the path prefix, or
              the named file is not writable by the user.  (See also
              path_resolution(7).)

       EFAULT Path points outside the process's allocated address space.

       EFBIG  The argument length is larger than the maximum file size. (XSI)

       EINTR  While blocked waiting to complete, the call was interrupted by a
              signal handler; see fcntl(2) and signal(7).

       EINVAL The argument length is negative or larger than the maximum file
              size.

       EIO    An I/O error occurred updating the inode.

       EISDIR The named file is a directory.

       ELOOP  Too many symbolic links were encountered in translating the
              pathname.

       ENAMETOOLONG
              A component of a pathname exceeded 255 characters, or an entire
              pathname exceeded 1023 characters.

       ENOENT The named file does not exist.

       ENOTDIR
              A component of the path prefix is not a directory.

       EPERM  The underlying file system does not support extending a file beyond
              its current size.

       EROFS  The named file resides on a read-only file system.

       ETXTBSY
              The file is a pure procedure (shared text) file that is being
              executed.

       For ftruncate() the same errors apply, but instead of things that can be
       wrong with path, we now have things that can be wrong with the file
       descriptor, fd:

       EBADF  fd is not a valid descriptor.

       EBADF or EINVAL
              fd is not open for writing.

       EINVAL fd does not reference a regular file.

CONFORMING TO top

       4.4BSD, SVr4, POSIX.1-2001 (these calls first appeared in 4.2BSD).

NOTES top

       The details in DESCRIPTION are for XSI-compliant systems.  For non-XSI-
       compliant systems, the POSIX standard allows two behaviors for ftruncate()
       when length exceeds the file length (note that truncate() is not specified
       at all in such an environment): either returning an error, or extending the
       file.  Like most UNIX implementations, Linux follows the XSI requirement
       when dealing with native file systems.  However, some nonnative file
       systems do not permit truncate() and ftruncate() to be used to extend a
       file beyond its current length: a notable example on Linux is VFAT.

       The original Linux truncate() and ftruncate() system calls were not
       designed to handle large file offsets.  Consequently, Linux 2.4 added
       truncate64() and ftruncate64() system calls that handle large files.
       However, these details can be ignored by applications using glibc, whose
       wrapper functions transparently employ the more recent system calls where
       they are available.

BUGS top

       A header file bug in glibc 2.12 meant that the minimum value of
       _POSIX_C_SOURCE required to expose the declaration of ftruncate() was
       200809L instead of 200112L.  This has been fixed in later glibc versions.

SEE ALSO top

       open(2), stat(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-08                         TRUNCATE(2)


fts(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FTS(3)                       Linux Programmer's Manual                      FTS(3)

NAME top

       fts, fts_open, fts_read, fts_children, fts_set, fts_close - traverse a file
       hierarchy

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fts.h>

       FTS *fts_open(char * const *path_argv, int options,
                     int (*compar)(const FTSENT **, const FTSENT **));

       FTSENT *fts_read(FTS *ftsp);

       FTSENT *fts_children(FTS *ftsp, int options);

       int fts_set(FTS *ftsp, FTSENT *f, int options);

       int fts_close(FTS *ftsp);

DESCRIPTION top

       The fts functions are provided for traversing file hierarchies.  A simple
       overview is that the fts_open() function returns a "handle" on a file
       hierarchy, which is then supplied to the other fts functions.  The function
       fts_read() returns a pointer to a structure describing one of the files in
       the file hierarchy.  The function fts_children() returns a pointer to a
       linked list of structures, each of which describes one of the files
       contained in a directory in the hierarchy.  In general, directories are
       visited two distinguishable times; in preorder (before any of their
       descendants are visited) and in postorder (after all of their descendants
       have been visited).  Files are visited once.  It is possible to walk the
       hierarchy "logically" (visiting the files that symbolic links point to) or
       physically (visiting the symbolic links themselves), order the walk of the
       hierarchy or prune and/or revisit portions of the hierarchy.

       Two structures are defined (and typedef'd) in the include file <fts.h>.
       The first is FTS, the structure that represents the file hierarchy itself.
       The second is FTSENT, the structure that represents a file in the file
       hierarchy.  Normally, an FTSENT structure is returned for every file in the
       file hierarchy.  In this manual page, "file" and "FTSENT structure" are
       generally interchangeable.  The FTSENT structure contains at least the
       following fields, which are described in greater detail below:

           typedef struct _ftsent {
               unsigned short fts_info;     /* flags for FTSENT structure */
               char          *fts_accpath;  /* access path */
               char          *fts_path;     /* root path */
               short          fts_pathlen;  /* strlen(fts_path) */
               char          *fts_name;     /* filename */
               short          fts_namelen;  /* strlen(fts_name) */
               short          fts_level;    /* depth (-1 to N) */
               int            fts_errno;    /* file errno */
               long           fts_number;   /* local numeric value */
               void          *fts_pointer;  /* local address value */
               struct ftsent *fts_parent;   /* parent directory */
               struct ftsent *fts_link;     /* next file structure */
               struct ftsent *fts_cycle;    /* cycle structure */
               struct stat   *fts_statp;    /* stat(2) information */
           } FTSENT;

       These fields are defined as follows:

       fts_info    One of the following flags describing the returned FTSENT
                   structure and the file it represents.  With the exception of
                   directories without errors (FTS_D), all of these entries are
                   terminal, that is, they will not be revisited, nor will any of
                   their descendants be visited.

                   FTS_D       A directory being visited in preorder.

                   FTS_DC      A directory that causes a cycle in the tree.  (The
                               fts_cycle field of the FTSENT structure will be
                               filled in as well.)

                   FTS_DEFAULT Any FTSENT structure that represents a file type
                               not explicitly described by one of the other
                               fts_info values.

                   FTS_DNR     A directory which cannot be read.  This is an error
                               return, and the fts_errno field will be set to
                               indicate what caused the error.

                   FTS_DOT     A file named "."  or ".."  which was not specified
                               as a filename to fts_open() (see FTS_SEEDOT).

                   FTS_DP      A directory being visited in postorder.  The
                               contents of the FTSENT structure will be unchanged
                               from when it was returned in preorder, that is,
                               with the fts_info field set to FTS_D.

                   FTS_ERR     This is an error return, and the fts_errno field
                               will be set to indicate what caused the error.

                   FTS_F       A regular file.

                   FTS_NS      A file for which no stat(2) information was
                               available.  The contents of the fts_statp field are
                               undefined.  This is an error return, and the
                               fts_errno field will be set to indicate what caused
                               the error.

                   FTS_NSOK    A file for which no stat(2) information was
                               requested.  The contents of the fts_statp field are
                               undefined.

                   FTS_SL      A symbolic link.

                   FTS_SLNONE  A symbolic link with a nonexistent target.  The
                               contents of the fts_statp field reference the file
                               characteristic information for the symbolic link
                               itself.

       fts_accpath A path for accessing the file from the current directory.

       fts_path    The path for the file relative to the root of the traversal.
                   This path contains the path specified to fts_open() as a
                   prefix.

       fts_pathlen The length of the string referenced by fts_path.

       fts_name    The name of the file.

       fts_namelen The length of the string referenced by fts_name.

       fts_level   The depth of the traversal, numbered from -1 to N, where this
                   file was found.  The FTSENT structure representing the parent
                   of the starting point (or root) of the traversal is numbered
                   -1, and the FTSENT structure for the root itself is numbered 0.

       fts_errno   Upon return of a FTSENT structure from the fts_children() or
                   fts_read() functions, with its fts_info field set to FTS_DNR,
                   FTS_ERR or FTS_NS, the fts_errno field contains the value of
                   the external variable errno specifying the cause of the error.
                   Otherwise, the contents of the fts_errno field are undefined.

       fts_number  This field is provided for the use of the application program
                   and is not modified by the fts functions.  It is initialized to
                   0.

       fts_pointer This field is provided for the use of the application program
                   and is not modified by the fts functions.  It is initialized to
                   NULL.

       fts_parent  A pointer to the FTSENT structure referencing the file in the
                   hierarchy immediately above the current file, that is, the
                   directory of which this file is a member.  A parent structure
                   for the initial entry point is provided as well, however, only
                   the fts_level, fts_number and fts_pointer fields are guaranteed
                   to be initialized.

       fts_link    Upon return from the fts_children() function, the fts_link
                   field points to the next structure in the NULL-terminated
                   linked list of directory members.  Otherwise, the contents of
                   the fts_link field are undefined.

       fts_cycle   If a directory causes a cycle in the hierarchy (see FTS_DC),
                   either because of a hard link between two directories, or a
                   symbolic link pointing to a directory, the fts_cycle field of
                   the structure will point to the FTSENT structure in the
                   hierarchy that references the same file as the current FTSENT
                   structure.  Otherwise, the contents of the fts_cycle field are
                   undefined.

       fts_statp   A pointer to stat(2) information for the file.

       A single buffer is used for all of the paths of all of the files in the
       file hierarchy.  Therefore, the fts_path and fts_accpath fields are
       guaranteed to be null-terminated only for the file most recently returned
       by fts_read().  To use these fields to reference any files represented by
       other FTSENT structures will require that the path buffer be modified using
       the information contained in that FTSENT structure's fts_pathlen field.
       Any such modifications should be undone before further calls to fts_read()
       are attempted.  The fts_name field is always null-terminated.

fts_open()

       The fts_open() function takes a pointer to an array of character pointers
       naming one or more paths which make up a logical file hierarchy to be
       traversed.  The array must be terminated by a NULL pointer.

       There are a number of options, at least one of which (either FTS_LOGICAL or
       FTS_PHYSICAL) must be specified.  The options are selected by ORing the
       following values:

       FTS_COMFOLLOW
                    This option causes any symbolic link specified as a root path
                    to be followed immediately whether or not FTS_LOGICAL is also
                    specified.

       FTS_LOGICAL  This option causes the fts routines to return FTSENT
                    structures for the targets of symbolic links instead of the
                    symbolic links themselves.  If this option is set, the only
                    symbolic links for which FTSENT structures are returned to the
                    application are those referencing nonexistent files.  Either
                    FTS_LOGICAL or FTS_PHYSICAL must be provided to the fts_open()
                    function.

       FTS_NOCHDIR  As a performance optimization, the fts functions change
                    directories as they walk the file hierarchy.  This has the
                    side-effect that an application cannot rely on being in any
                    particular directory during the traversal.  The FTS_NOCHDIR
                    option turns off this optimization, and the fts functions will
                    not change the current directory.  Note that applications
                    should not themselves change their current directory and try
                    to access files unless FTS_NOCHDIR is specified and absolute
                    pathnames were provided as arguments to fts_open().

       FTS_NOSTAT   By default, returned FTSENT structures reference file
                    characteristic information (the statp field) for each file
                    visited.  This option relaxes that requirement as a
                    performance optimization, allowing the fts functions to set
                    the fts_info field to FTS_NSOK and leave the contents of the
                    statp field undefined.

       FTS_PHYSICAL This option causes the fts routines to return FTSENT
                    structures for symbolic links themselves instead of the target
                    files they point to.  If this option is set, FTSENT structures
                    for all symbolic links in the hierarchy are returned to the
                    application.  Either FTS_LOGICAL or FTS_PHYSICAL must be
                    provided to the fts_open() function.

       FTS_SEEDOT   By default, unless they are specified as path arguments to
                    fts_open(), any files named "."  or ".."  encountered in the
                    file hierarchy are ignored.  This option causes the fts
                    routines to return FTSENT structures for them.

       FTS_XDEV     This option prevents fts from descending into directories that
                    have a different device number than the file from which the
                    descent began.

       The argument compar() specifies a user-defined function which may be used
       to order the traversal of the hierarchy.  It takes two pointers to pointers
       to FTSENT structures as arguments and should return a negative value, zero,
       or a positive value to indicate if the file referenced by its first
       argument comes before, in any order with respect to, or after, the file
       referenced by its second argument.  The fts_accpath, fts_path and
       fts_pathlen fields of the FTSENT structures may never be used in this
       comparison.  If the fts_info field is set to FTS_NS or FTS_NSOK, the
       fts_statp field may not either.  If the compar() argument is NULL, the
       directory traversal order is in the order listed in path_argv for the root
       paths, and in the order listed in the directory for everything else.

fts_read()

       The fts_read() function returns a pointer to an FTSENT structure describing
       a file in the hierarchy.  Directories (that are readable and do not cause
       cycles) are visited at least twice, once in preorder and once in postorder.
       All other files are visited at least once.  (Hard links between directories
       that do not cause cycles or symbolic links to symbolic links may cause
       files to be visited more than once, or directories more than twice.)

       If all the members of the hierarchy have been returned, fts_read() returns
       NULL and sets the external variable errno to 0.  If an error unrelated to a
       file in the hierarchy occurs, fts_read() returns NULL and sets errno
       appropriately.  If an error related to a returned file occurs, a pointer to
       an FTSENT structure is returned, and errno may or may not have been set
       (see fts_info).

       The FTSENT structures returned by fts_read() may be overwritten after a
       call to fts_close() on the same file hierarchy stream, or, after a call to
       fts_read() on the same file hierarchy stream unless they represent a file
       of type directory, in which case they will not be overwritten until after a
       call to fts_read() after the FTSENT structure has been returned by the
       function fts_read() in postorder.

fts_children()

       The fts_children() function returns a pointer to an FTSENT structure
       describing the first entry in a NULL-terminated linked list of the files in
       the directory represented by the FTSENT structure most recently returned by
       fts_read().  The list is linked through the fts_link field of the FTSENT
       structure, and is ordered by the user-specified comparison function, if
       any.  Repeated calls to fts_children() will recreate this linked list.

       As a special case, if fts_read() has not yet been called for a hierarchy,
       fts_children() will return a pointer to the files in the logical directory
       specified to fts_open(), that is, the arguments specified to fts_open().
       Otherwise, if the FTSENT structure most recently returned by fts_read() is
       not a directory being visited in preorder, or the directory does not
       contain any files, fts_children() returns NULL and sets errno to zero.  If
       an error occurs, fts_children() returns NULL and sets errno appropriately.

       The FTSENT structures returned by fts_children() may be overwritten after a
       call to fts_children(), fts_close() or fts_read() on the same file
       hierarchy stream.

       Option may be set to the following value:

       FTS_NAMEONLY Only the names of the files are needed.  The contents of all
                    the fields in the returned linked list of structures are
                    undefined with the exception of the fts_name and fts_namelen
                    fields.

fts_set()

       The function fts_set() allows the user application to determine further
       processing for the file f of the stream ftsp.  The fts_set() function
       returns 0 on success, and -1 if an error occurs.  Option must be set to one
       of the following values:

       FTS_AGAIN    Revisit the file; any file type may be revisited.  The next
                    call to fts_read() will return the referenced file.  The
                    fts_stat and fts_info fields of the structure will be
                    reinitialized at that time, but no other fields will have been
                    changed.  This option is meaningful only for the most recently
                    returned file from fts_read().  Normal use is for postorder
                    directory visits, where it causes the directory to be
                    revisited (in both preorder and postorder) as well as all of
                    its descendants.

       FTS_FOLLOW   The referenced file must be a symbolic link.  If the
                    referenced file is the one most recently returned by
                    fts_read(), the next call to fts_read() returns the file with
                    the fts_info and fts_statp fields reinitialized to reflect the
                    target of the symbolic link instead of the symbolic link
                    itself.  If the file is one of those most recently returned by
                    fts_children(), the fts_info and fts_statp fields of the
                    structure, when returned by fts_read(), will reflect the
                    target of the symbolic link instead of the symbolic link
                    itself.  In either case, if the target of the symbolic link
                    does not exist the fields of the returned structure will be
                    unchanged and the fts_info field will be set to FTS_SLNONE.

                    If the target of the link is a directory, the preorder return,
                    followed by the return of all of its descendants, followed by
                    a postorder return, is done.

       FTS_SKIP     No descendants of this file are visited.  The file may be one
                    of those most recently returned by either fts_children() or
                    fts_read().

fts_close()

       The fts_close() function closes a file hierarchy stream ftsp and restores
       the current directory to the directory from which fts_open() was called to
       open ftsp.  The fts_close() function returns 0 on success, and -1 if an
       error occurs.

ERRORS top

       The function fts_open() may fail and set errno for any of the errors
       specified for open(2) and malloc(3).

       The function fts_close() may fail and set errno for any of the errors
       specified for chdir(2) and close(2).

       The functions fts_read() and fts_children() may fail and set errno for any
       of the errors specified for chdir(2), malloc(3), opendir(3), readdir(3) and
       stat(2).

       In addition, fts_children(), fts_open() and fts_set() may fail and set
       errno as follows:

       EINVAL The options were invalid.

VERSIONS top

       These functions are available in Linux since glibc2.

CONFORMING TO top

       4.4BSD.

SEE ALSO top

       find(1), chdir(2), stat(2), ftw(3), qsort(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-25                              FTS(3)


ftw(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

FTW(3)                       Linux Programmer's Manual                      FTW(3)

NAME top

       ftw, nftw - file tree walk

SYNOPSIS top

       #include <ftw.h>

       int ftw(const char *dirpath,
               int (*fn) (const char *fpath, const struct stat *sb,
                          int typeflag),
               int nopenfd);

       #define _XOPEN_SOURCE 500   /* See feature_test_macros(7) */
       #include <ftw.h>

       int nftw(const char *dirpath,
               int (*fn) (const char *fpath, const struct stat *sb,
                          int typeflag, struct FTW *ftwbuf),
               int nopenfd, int flags);

DESCRIPTION top

       ftw() walks through the directory tree that is located under the directory
       dirpath, and calls fn() once for each entry in the tree.  By default,
       directories are handled before the files and subdirectories they contain
       (preorder traversal).

       To avoid using up all of the calling process's file descriptors, nopenfd
       specifies the maximum number of directories that ftw() will hold open
       simultaneously.  When the search depth exceeds this, ftw() will become
       slower because directories have to be closed and reopened.  ftw() uses at
       most one file descriptor for each level in the directory tree.

       For each entry found in the tree, ftw() calls fn() with three arguments:
       fpath, sb, and typeflag.  fpath is the pathname of the entry, and is
       expressed either as a pathname relative to the calling process's current
       working directory at the time of the call to ftw(), if dirpath was
       expressed as a relative pathname, or as an absolute pathname, if dirpath
       was expressed as an absolute pathname.  sb is a pointer to the stat
       structure returned by a call to stat(2) for fpath.  typeflag is an integer
       that has one of the following values:

       FTW_F  fpath is a regular file.

       FTW_D  fpath is a directory.

       FTW_DNR
              fpath is a directory which can't be read.

       FTW_NS The stat(2) call failed on fpath, which is not a symbolic link.

              If fpath is a symbolic link and stat(2) failed, POSIX.1-2001 states
              that it is undefined whether FTW_NS or FTW_SL (see below) is passed
              in typeflag.

       To stop the tree walk, fn() returns a nonzero value; this value will become
       the return value of ftw().  As long as fn() returns 0, ftw() will continue
       either until it has traversed the entire tree, in which case it will return
       zero, or until it encounters an error (such as a malloc(3) failure), in
       which case it will return -1.

       Because ftw() uses dynamic data structures, the only safe way to exit out
       of a tree walk is to return a nonzero value from fn().  To allow a signal
       to terminate the walk without causing a memory leak, have the handler set a
       global flag that is checked by fn().  Don't use longjmp(3) unless the
       program is going to terminate.

nftw()

       The function nftw() is the same as ftw(), except that it has one additional
       argument, flags, and calls fn() with one more argument, ftwbuf.

       This flags argument is formed by ORing zero or more of the following flags:

       FTW_ACTIONRETVAL (since glibc 2.3.3)
              If this glibc-specific flag is set, then nftw() handles the return
              value from fn() differently.  fn() should return one of the
              following values:

              FTW_CONTINUE
                     Instructs nftw() to continue normally.

              FTW_SKIP_SIBLINGS
                     If fn() returns this value, then siblings of the current
                     entry will be skipped, and processing continues in the
                     parent.

              FTW_SKIP_SUBTREE
                     If fn() is called with an entry that is a directory (typeflag
                     is FTW_D), this return value will prevent objects within that
                     directory from being passed as arguments to fn().  nftw()
                     continues processing with the next sibling of the directory.

              FTW_STOP
                     Causes nftw() to return immediately with the return value
                     FTW_STOP.

              Other return values could be associated with new actions in the
              future; fn() should not return values other than those listed above.

              The feature test macro _GNU_SOURCE must be defined (before including
              any header files) in order to obtain the definition of
              FTW_ACTIONRETVAL from <ftw.h>.

       FTW_CHDIR
              If set, do a chdir(2) to each directory before handling its
              contents.  This is useful if the program needs to perform some
              action in the directory in which fpath resides.

       FTW_DEPTH
              If set, do a post-order traversal, that is, call fn() for the
              directory itself after handling the contents of the directory and
              its subdirectories.  (By default, each directory is handled before
              its contents.)

       FTW_MOUNT
              If set, stay within the same file system (i.e., do not cross mount
              points).

       FTW_PHYS
              If set, do not follow symbolic links.  (This is what you want.)  If
              not set, symbolic links are followed, but no file is reported twice.

              If FTW_PHYS is not set, but FTW_DEPTH is set, then the function fn()
              is never called for a directory that would be a descendant of
              itself.

       For each entry in the directory tree, nftw() calls fn() with four
       arguments.  fpath and sb are as for ftw().  typeflag may receive any of the
       same values as with ftw(), or any of the following values:

       FTW_DP fpath is a directory, and FTW_DEPTH was specified in flags.  All of
              the files and subdirectories within fpath have been processed.

       FTW_SL fpath is a symbolic link, and FTW_PHYS was set in flags.

       FTW_SLN
              fpath is a symbolic link pointing to a nonexistent file.  (This
              occurs only if FTW_PHYS is not set.)

       The fourth argument that nftw() supplies when calling fn() is a structure
       of type FTW:

           struct FTW {
               int base;
               int level;
           };

       base is the offset of the filename (i.e., basename component) in the
       pathname given in fpath.  level is the depth of fpath in the directory
       tree, relative to the root of the tree (dirpath, which has depth 0).

RETURN VALUE top

       These functions return 0 on success, and -1 if an error occurs.

       If fn() returns nonzero, then the tree walk is terminated and the value
       returned by fn() is returned as the result of ftw() or nftw().

       If nftw() is called with the FTW_ACTIONRETVAL flag, then the only nonzero
       value that should be used by fn() to terminate the tree walk is FTW_STOP,
       and that value is returned as the result of nftw().

CONFORMING TO top

       POSIX.1-2001, SVr4, SUSv1.  POSIX.1-2008 marks ftw() as obsolete.

NOTES top

       POSIX.1-2001 note that the results are unspecified if fn does not preserve
       the current working directory.

       The function nftw() and the use of FTW_SL with ftw() were introduced in
       SUSv1.

       On some systems ftw() will never use FTW_SL, on other systems FTW_SL occurs
       only for symbolic links that do not point to an existing file, and again on
       other systems ftw() will use FTW_SL for each symbolic link.  For
       predictable control, use nftw().

       Under Linux, libc4 and libc5 and glibc 2.0.6 will use FTW_F for all objects
       (files, symbolic links, FIFOs, etc.)  that can be stat'ed but are not a
       directory.

       The function nftw() is available since glibc 2.1.

       FTW_ACTIONRETVAL is glibc-specific.

EXAMPLE top

       The following program traverses the directory tree under the path named in
       its first command-line argument, or under the current directory if no
       argument is supplied.  It displays various information about each file.
       The second command-line argument can be used to specify characters that
       control the value assigned to the flags argument when calling nftw().

       #define _XOPEN_SOURCE 500
       #include <ftw.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #include <stdint.h>

       static int
       display_info(const char *fpath, const struct stat *sb,
                    int tflag, struct FTW *ftwbuf)
       {
           printf("%-3s %2d %7jd   %-40s %d %s\n",
               (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
               (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
               (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
               (tflag == FTW_SLN) ? "sln" : "???",
               ftwbuf->level, (intmax_t) sb->st_size,
               fpath, ftwbuf->base, fpath + ftwbuf->base);
           return 0;           /* To tell nftw() to continue */
       }

       int
       main(int argc, char *argv[])
       {
           int flags = 0;

           if (argc > 2 && strchr(argv[2], 'd') != NULL)
               flags |= FTW_DEPTH;
           if (argc > 2 && strchr(argv[2], 'p') != NULL)
               flags |= FTW_PHYS;

           if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
                   == -1) {
               perror("nftw");
               exit(EXIT_FAILURE);
           }
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       stat(2), fts(3), readdir(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                              FTW(3)


full(4) - Linux manual page

NAME | CONFIGURATION | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

FULL(4)                      Linux Programmer's Manual                     FULL(4)

NAME top

       full - always full device

CONFIGURATION top

       If  your  system does not have /dev/full created already, it can be created
       with the following commands:

               mknod -m 666 /dev/full c 1 7
               chown root:root /dev/full

DESCRIPTION top

       File /dev/full has major device number 1 and minor device number 7.

       Writes to the /dev/full device will fail with an ENOSPC error.  This can be
       used to test how a program handles disk-full errors.

       Reads from the /dev/full device will return \0 characters.

       Seeks on /dev/full will always succeed.

FILES top

       /dev/full

SEE ALSO top

       mknod(1), null(4), zero(4)

COLOPHON top

       This page is part of release 3.45 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-11-24                             FULL(4)


futex(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FUTEX(2)                     Linux Programmer's Manual                    FUTEX(2)

NAME top

       futex - fast user-space locking

SYNOPSIS top

       #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 top

       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
       processes may not be equal, the kernel maps them internally so the same
       memory mapped in different locations will correspond for futex() calls).
       This system call 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 user space, a call
       needs to be made to the kernel to arbitrate.  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 nonportable 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 contention), 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 process 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 onward.

       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 similar 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 top

       In the event of an error, all operations return -1, and set errno to
       indicate the error.  The return value on success depends on the operation,
       as described in the following list:

       FUTEX_WAIT
              Returns 0 if the process was woken by a FUTEX_WAKE call.  See ERRORS
              for the various possible error returns.

       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.

ERRORS top

       EACCES No read access to futex memory.

       EAGAIN FUTEX_CMP_REQUEUE detected that the value pointed to by uaddr is not
              equal to the expected value val3.  (This probably indicates a race;
              use the safe FUTEX_WAKE now.)

       EFAULT Error retrieving timeout information from user space.

       EINTR  A FUTEX_WAIT operation was interrupted by a signal (see signal(7))
              or a spurious wakeup.

       EINVAL Invalid argument.

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

       ENOSYS Invalid operation specified in op.

       ETIMEDOUT
              Timeout during the FUTEX_WAIT operation.

       EWOULDBLOCK
              op was FUTEX_WAIT and the value pointed to by uaddr was not equal to
              the expected value val at the time of the call.

VERSIONS top

       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 described in this page 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 top

       This system call is Linux-specific.

NOTES top

       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 user-space library referenced below.

SEE ALSO top

       futex(7)

       Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux (proceedings of
       the Ottawa Linux Symposium 2002), online at
       <http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf>

       Futex example library, futex-*.tar.bz2 at
       <ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/>

COLOPHON top

       This page is part of release 3.45 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                               2012-08-13                            FUTEX(2)


futex(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FUTEX(7)                     Linux Programmer's Manual                    FUTEX(7)

NAME top

       futex - fast user-space locking

SYNOPSIS top

       #include <linux/futex.h>

DESCRIPTION top

       The Linux kernel provides futexes ("Fast user-space mutexes") as a building
       block for fast user-space locking and semaphores.  Futexes are very basic
       and lend themselves well for building higher level locking abstractions
       such as POSIX mutexes.

       This page does not set out to document all design decisions but restricts
       itself to issues relevant for application and library development.  Most
       programmers will in fact not be using futexes directly but instead rely on
       system libraries built on them, such as the NPTL pthreads implementation.

       A futex is identified by a piece of memory which can be shared between
       different processes.  In these different processes, it need not have
       identical addresses.  In its bare form, a futex has semaphore semantics; it
       is a counter that can be incremented and decremented atomically; processes
       can wait for the value to become positive.

       Futex operation is entirely user space for the noncontended case.  The
       kernel is only involved to arbitrate the contended case.  As any sane
       design will strive for noncontention, futexes are also optimized for this
       situation.

       In its bare form, a futex is an aligned integer which is only touched by
       atomic assembler instructions.  Processes can share this integer using
       mmap(2), via shared memory segments or because they share memory space, in
       which case the application is commonly called multithreaded.

Semantics

       Any futex operation starts in user space, but it may necessary to
       communicate with the kernel using the futex(2) system call.

       To "up" a futex, execute the proper assembler instructions that will cause
       the host CPU to atomically increment the integer.  Afterward, check if it
       has in fact changed from 0 to 1, in which case there were no waiters and
       the operation is done.  This is the noncontended case which is fast and
       should be common.

       In the contended case, the atomic increment changed the counter from -1
       (or some other negative number).  If this is detected, there are waiters.
       User space should now set the counter to 1 and instruct the kernel to wake
       up any waiters using the FUTEX_WAKE operation.

       Waiting on a futex, to "down" it, is the reverse operation.  Atomically
       decrement the counter and check if it changed to 0, in which case the
       operation is done and the futex was uncontended.  In all other
       circumstances, the process should set the counter to -1 and request that
       the kernel wait for another process to up the futex.  This is done using
       the FUTEX_WAIT operation.

       The futex(2) system call can optionally be passed a timeout specifying how
       long the kernel should wait for the futex to be upped.  In this case,
       semantics are more complex and the programmer is referred to futex(2) for
       more details.  The same holds for asynchronous futex waiting.

VERSIONS top

       Initial futex support was merged in Linux 2.5.7 but with different
       semantics from those described above.  Current semantics are available from
       Linux 2.5.40 onward.

NOTES top

       To reiterate, bare futexes are not intended as an easy to use abstraction
       for end-users.  Implementors are expected to be assembly literate and to
       have read the sources of the futex user-space library referenced below.

       This man page illustrates the most common use of the futex(2) primitives:
       it is by no means the only one.

SEE ALSO top

       futex(2)

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

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                            FUTEX(7)


utimensat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

UTIMENSAT(2)                 Linux Programmer's Manual                UTIMENSAT(2)

NAME top

       utimensat, futimens - change file timestamps with nanosecond precision

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <sys/stat.h>

       int utimensat(int dirfd, const char *pathname,
                     const struct timespec times[2], int flags);

       int futimens(int fd, const struct timespec times[2]);

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

       utimensat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE
       futimens():
           Since glibc 2.10:
                  _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
                  _GNU_SOURCE

DESCRIPTION top

       utimensat() and futimens() update the timestamps of a file with nanosecond
       precision.  This contrasts with the historical utime(2) and utimes(2),
       which permit only second and microsecond precision, respectively, when
       setting file timestamps.

       With utimensat() the file is specified via the pathname given in pathname.
       With futimens() the file whose timestamps are to be updated is specified
       via an open file descriptor, fd.

       For both calls, the new file timestamps are specified in the array times:
       times[0] specifies the new "last access time" (atime); times[1] specifies
       the new "last modification time" (mtime).  Each of the elements of times
       specifies a time as the number of seconds and nanoseconds since the Epoch,
       1970-01-01 00:00:00 +0000 (UTC).  This information is conveyed in a
       structure of the following form:

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

       Updated file timestamps are set to the greatest value supported by the file
       system that is not greater than the specified time.

       If the tv_nsec field of one of the timespec structures has the special
       value UTIME_NOW, then the corresponding file timestamp is set to the
       current time.  If the tv_nsec field of one of the timespec structures has
       the special value UTIME_OMIT, then the corresponding file timestamp is left
       unchanged.  In both of these cases, the value of the corresponding tv_sec
       field is ignored.

       If times is NULL, then both timestamps are set to the current time.

Permissions requirements

       To set both file timestamps to the current time (i.e., times is NULL, or
       both tv_nsec fields specify UTIME_NOW), either:

       1. the caller must have write access to the file;

       2. the caller's effective user ID must match the owner of the file; or

       3. the caller must have appropriate privileges.

       To make any change other than setting both timestamps to the current time
       (i.e., times is not NULL, and both tv_nsec fields are not UTIME_NOW and
       both tv_nsec fields are not UTIME_OMIT), either condition 2 or 3 above must
       apply.

       If both tv_nsec fields are specified as UTIME_OMIT, then no file ownership
       or permission checks are performed, and the file timestamps are not
       modified, but other error conditions may still be detected.

utimensat() specifics

       If pathname is relative, then by default it is interpreted relative to the
       directory referred to by the open file descriptor, dirfd (rather than
       relative to the current working directory of the calling process, as is
       done by utimes(2) for a relative pathname).  See openat(2) for an
       explanation of why this can be useful.

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like utimes(2)).

       If pathname is absolute, then dirfd is ignored.

       The flags field is a bit mask that may be 0, or include the following
       constant, defined in <fcntl.h>:

       AT_SYMLINK_NOFOLLOW
              If pathname specifies a symbolic link, then update the timestamps of
              the link, rather than the file to which it refers.

RETURN VALUE top

       On success, utimensat() and futimens() return 0.  On error, -1 is returned
       and errno is set to indicate the error.

ERRORS top

       EACCES times is NULL, or both tv_nsec values are UTIME_NOW, and:
              * the effective user ID of the caller does not match the owner of
                the file, the caller does not have write access to the file, and
                the caller is not privileged (Linux: does not have either the
                CAP_FOWNER or the CAP_DAC_OVERRIDE capability); or,
              * the file is marked immutable (see chattr(1)).

       EBADF  (futimens()) fd is not a valid file descriptor.

       EBADF  (utimensat()) pathname is a relative pathname, but dirfd is neither
              AT_FDCWD nor a valid file descriptor.

       EFAULT times pointed to an invalid address; or, dirfd was AT_FDCWD, and
              pathname is NULL or an invalid address.

       EINVAL Invalid value in flags.

       EINVAL Invalid value in one of the tv_nsec fields (value outside range 0 to
              999,999,999, and not UTIME_NOW or UTIME_OMIT); or an invalid value
              in one of the tv_sec fields.

       EINVAL pathname is NULL, dirfd is not AT_FDCWD, and flags contains
              AT_SYMLINK_NOFOLLOW.

       ELOOP  (utimensat()) Too many symbolic links were encountered in resolving
              pathname.

       ENAMETOOLONG
              (utimensat()) pathname is too long.

       ENOENT (utimensat()) A component of pathname does not refer to an existing
              directory or file, or pathname is an empty string.

       ENOTDIR
              (utimensat()) pathname is a relative pathname, but dirfd is neither
              AT_FDCWD nor a file descriptor referring to a directory; or, one of
              the prefix components of pathname is not a directory.

       EPERM  The caller attempted to change one or both timestamps to a value
              other than the current time, or to change one of the timestamps to
              the current time while leaving the other timestamp unchanged, (i.e.,
              times is not NULL, both tv_nsec fields are not UTIME_NOW, and both
              tv_nsec fields are not UTIME_OMIT) and:
              * the caller's effective user ID does not match the owner of file,
                and the caller is not privileged (Linux: does not have the
                CAP_FOWNER capability); or,
              * the file is marked append-only or immutable (see chattr(1)).

       EROFS  The file is on a read-only file system.

       ESRCH  (utimensat()) Search permission is denied for one of the prefix
              components of pathname.

VERSIONS top

       utimensat() was added to Linux in kernel 2.6.22; glibc support was added
       with version 2.6.

       Support for futimens() first appeared in glibc 2.6.

CONFORMING TO top

       futimens() and utimensat() are specified in POSIX.1-2008.

NOTES top

       utimensat() obsoletes futimesat(2).

       On Linux, timestamps cannot be changed for a file marked immutable, and the
       only change permitted for files marked append-only is to set the timestamps
       to the current time.  (This is consistent with the historical behavior of
       utime(2) and utimes(2) on Linux.)

       On Linux, futimens() is a library function implemented on top of the
       utimensat() system call.  To support this, the Linux utimensat() system
       call implements a nonstandard feature: if pathname is NULL, then the call
       modifies the timestamps of the file referred to by the file descriptor
       dirfd (which may refer to any type of file).  Using this feature, the call
       futimens(fd, times) is implemented as:

           utimensat(fd, NULL, times, 0);

BUGS top

       Several bugs afflict utimensat() and futimens() on kernels before 2.6.26.
       These bugs are either nonconformances with the POSIX.1 draft specification
       or inconsistencies with historical Linux behavior.

       * POSIX.1 specifies that if one of the tv_nsec fields has the value
         UTIME_NOW or UTIME_OMIT, then the value of the corresponding tv_sec field
         should be ignored.  Instead, the value of the tv_sec field is required to
         be 0 (or the error EINVAL results).

       * Various bugs mean that for the purposes of permission checking, the case
         where both tv_nsec fields are set to UTIME_NOW isn't always treated the
         same as specifying times as NULL, and the case where one tv_nsec value is
         UTIME_NOW and the other is UTIME_OMIT isn't treated the same as
         specifying times as a pointer to an array of structures containing
         arbitrary time values.  As a result, in some cases: a) file timestamps
         can be updated by a process that shouldn't have permission to perform
         updates; b) file timestamps can't be updated by a process that should
         have permission to perform updates; and c) the wrong errno value is
         returned in case of an error.

       * POSIX.1 says that a process that has write access to the file can make a
         call with times as NULL, or with times pointing to an array of structures
         in which both tv_nsec fields are UTIME_NOW, in order to update both
         timestamps to the current time.  However, futimens() instead checks
         whether the access mode of the file descriptor allows writing.

SEE ALSO top

       chattr(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3),
       path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-25                        UTIMENSAT(2)


futimes(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

FUTIMES(3)                   Linux Programmer's Manual                  FUTIMES(3)

NAME top

       futimes, lutimes - change file timestamps

SYNOPSIS top

       #include <sys/time.h>

       int futimes(int fd, const struct timeval tv[2]);

       int lutimes(const char *filename, const struct timeval tv[2]);

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

       futimes(), lutimes(): _BSD_SOURCE

DESCRIPTION top

       futimes() changes the access and modification times of a file in the same
       way as utimes(2), with the difference that the file whose timestamps are to
       be changed is specified via a file descriptor, fd, rather than via a
       pathname.

       lutimes() changes the access and modification times of a file in the same
       way as utimes(2), with the difference that if filename refers to a symbolic
       link, then the link is not dereferenced: instead, the timestamps of the
       symbolic link are changed.

RETURN VALUE top

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

ERRORS top

       Errors are as for utimes(2), with the following additions for futimes():

       EBADF  fd is not a valid file descriptor.

       ENOSYS The /proc file system could not be accessed.

VERSIONS top

       futimes() is available since glibc 2.3.  lutimes() is available since glibc
       2.6, and is implemented using the utimensat(2) system call, which is
       supported since kernel 2.6.22.

CONFORMING TO top

       These functions are not specified in any standard.  Other than Linux, they
       are only available on the BSDs.

SEE ALSO top

       utime(2), utimensat(2), symlink(7)

COLOPHON top

       This page is part of release 3.45 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-07                          FUTIMES(3)


futimesat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FUTIMESAT(2)                 Linux Programmer's Manual                FUTIMESAT(2)

NAME top

       futimesat  -  change  timestamps  of  a  file  relative to a directory file
       descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <sys/time.h>

       int futimesat(int dirfd, const char *pathname,
                     const struct timeval times[2]);

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

       futimesat(): _GNU_SOURCE

DESCRIPTION top

       This system call is obsolete.  Use utimensat(2) instead.

       The futimesat() system call operates in exactly the same way as utimes(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by utimes(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like utimes(2)).

       If pathname is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, futimesat() returns a 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for utimes(2) can also occur for futimesat().
       The following additional errors can occur for futimesat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       futimesat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       This system call is nonstandard.  It was implemented from a specification
       that was proposed for POSIX.1, but that specification was replaced by the
       one for utimensat(2).

       A similar system call exists on Solaris.

NOTES top

Glibc Notes

       If pathname is NULL, then the glibc futimesat() wrapper function updates
       the times for the file referred to by dirfd.

SEE ALSO          top
       stat(2), utimensat(2), utimes(2), futimes(3), path_resolution(7)

COLOPHON          top
       This page is part of release 3.45 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                               2012-05-10                        FUTIMESAT(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


fwide(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

FWIDE(3)                     Linux Programmer's Manual                    FWIDE(3)

NAME top

       fwide - set and determine the orientation of a FILE stream

SYNOPSIS top

       #include <wchar.h>

       int fwide(FILE *stream, int mode);

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

       fwide():
           _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
           _ISOC95_SOURCE /* Since glibc 2.12 */ ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       When mode is zero, the fwide() function determines the current orientation
       of stream.  It returns a positive value if stream is wide-character
       oriented, that is, if wide-character I/O is permitted but char I/O is
       disallowed.  It returns a negative value if stream is byte oriented, i.e.,
       if char I/O is permitted but wide-character I/O is disallowed.  It returns
       zero if stream has no orientation yet; in this case the next I/O operation
       might change the orientation (to byte oriented if it is a char I/O
       operation, or to wide-character oriented if it is a wide-character I/O
       operation).

       Once a stream has an orientation, it cannot be changed and persists until
       the stream is closed.

       When mode is nonzero, the fwide() function first attempts to set stream's
       orientation (to wide-character oriented if mode is greater than 0, or to
       byte oriented if mode is less than 0).  It then returns a value denoting
       the current orientation, as above.

RETURN VALUE top

       The fwide() function returns the stream's orientation, after possibly
       changing it.  A positive return value means wide-character oriented.  A
       negative return value means byte oriented.  A return value of zero means
       undecided.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       Wide-character output to a byte oriented stream can be performed through
       the fprintf(3) function with the %lc and %ls directives.

       Char oriented output to a wide-character oriented stream can be performed
       through the fwprintf(3) function with the %c and %s directives.

SEE ALSO top

       fprintf(3), fwprintf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-17                            FWIDE(3)


wprintf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WPRINTF(3)                   Linux Programmer's Manual                  WPRINTF(3)

NAME top

       wprintf,  fwprintf,  swprintf,  vwprintf,  vfwprintf, vswprintf - formatted
       wide-character output conversion

SYNOPSIS top

       #include <stdio.h>
       #include <wchar.h>

       int wprintf(const wchar_t *format, ...);
       int fwprintf(FILE *stream, const wchar_t *format, ...);
       int swprintf(wchar_t *wcs, size_t maxlen,
                    const wchar_t *format, ...);

       int vwprintf(const wchar_t *format, va_list args);
       int vfwprintf(FILE *stream, const wchar_t *format, va_list args);
       int vswprintf(wchar_t *wcs, size_t maxlen,
                     const wchar_t *format, va_list args);

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

       All functions shown above:
           _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
           _ISOC95_SOURCE /* Since glibc 2.12 */ ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The wprintf() family of functions is the wide-character equivalent of the
       printf(3) family of functions.  It performs formatted output of wide
       characters.

       The wprintf() and vwprintf() functions perform wide-character output to
       stdout.  stdout must not be byte oriented; see fwide(3) for more
       information.

       The fwprintf() and vfwprintf() functions perform wide-character output to
       stream.  stream must not be byte oriented; see fwide(3) for more
       information.

       The swprintf() and vswprintf() functions perform wide-character output to
       an array of wide characters.  The programmer must ensure that there is room
       for at least maxlen wide characters at wcs.

       These functions are like the printf(3), vprintf(3), fprintf(3),
       vfprintf(3), sprintf(3), vsprintf(3) functions except for the following
       differences:

       +o      The format string is a wide-character string.

       +o      The output consists of wide characters, not bytes.

       +o      swprintf() and vswprintf() take a maxlen argument, sprintf(3) and
              vsprintf(3) do not.  (snprintf(3) and vsnprintf(3) take a maxlen
              argument, but these functions do not return -1 upon buffer overflow
              on Linux.)

       The treatment of the conversion characters c and s is different:

       c      If no l modifier is present, the int argument is converted to a wide
              character by a call to the btowc(3) function, and the resulting wide
              character is written.  If an l modifier is present, the wint_t (wide
              character) argument is written.

       s      If no l modifier is present: The const char * argument is expected
              to be a pointer to an array of character type (pointer to a string)
              containing a multibyte character sequence beginning in the initial
              shift state.  Characters from the array are converted to wide
              characters (each by a call to the mbrtowc(3) function with a
              conversion state starting in the initial state before the first
              byte).  The resulting wide characters are written up to (but not
              including) the terminating null wide character.  If a precision is
              specified, no more wide characters than the number specified are
              written.  Note that the precision determines the number of wide
              characters written, not the number of bytes or screen positions.
              The array must contain a terminating null byte, unless a precision
              is given and it is so small that the number of converted wide
              characters reaches it before the end of the array is reached.  If an
              l modifier is present: The const wchar_t * argument is expected to
              be a pointer to an array of wide characters.  Wide characters from
              the array are written up to (but not including) a terminating null
              wide character.  If a precision is specified, no more than the
              number specified are written.  The array must contain a terminating
              null wide character, unless a precision is given and it is smaller
              than or equal to the number of wide characters in the array.

RETURN VALUE top

       The functions return the number of wide characters written, excluding the
       terminating null wide character in case of the functions swprintf() and
       vswprintf().  They return -1 when an error occurs.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wprintf() et al. depends on the LC_CTYPE category of the
       current locale.

       If the format string contains non-ASCII wide characters, the program will
       only work correctly if the LC_CTYPE category of the current locale at run
       time is the same as the LC_CTYPE category of the current locale at compile
       time.  This is because the wchar_t representation is platform- and locale-
       dependent.  (The glibc represents wide characters using their Unicode
       (ISO-10646) code point, but other platforms don't do this.  Also, the use
       of C99 universal character names of the form \unnnn does not solve this
       problem.)  Therefore, in internationalized programs, the format string
       should consist of ASCII wide characters only, or should be constructed at
       run time in an internationalized way (e.g., using gettext(3) or iconv(3),
       followed by mbstowcs(3)).

SEE ALSO top

       fprintf(3), fputwc(3), fwide(3), printf(3), snprintf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-17                          WPRINTF(3)


getaddrinfo_a(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETADDRINFO_A(3)             Linux Programmer's Manual            GETADDRINFO_A(3)

NAME top

       getaddrinfo_a,  gai_suspend,  gai_error,  gai_cancel - asynchronous network
       address and service translation

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <netdb.h>

       int getaddrinfo_a(int mode, struct gaicb *list[],
                       int nitems, struct sigevent *sevp);

       int gai_suspend(struct gaicb *list[], int nitems,
                       struct timespec *timeout);

       int gai_error(struct gaicb *req);

       int gai_cancel(struct gaicb *req);

       Link with -lanl.

DESCRIPTION top

       The getaddrinfo_a() function performs the same task as getaddrinfo(3), but
       allows multiple name look-ups to be performed asynchronously, with optional
       notification on completion of look-up operations.

       The mode argument has one of the following values:

       GAI_WAIT
              Perform the look-ups synchronously.  The call blocks until the look-
              ups have completed.

       GAI_NOWAIT
              Perform the look-ups asynchronously.  The call returns immediately,
              and the requests are resolved in the background.  See the discussion
              of the sevp argument below.

       The array list specifies the look-up requests to process.  The nitems
       argument specifies the number of elements in list.  The requested look-up
       operations are started in parallel.  NULL elements in list are ignored.
       Each request is described by a gaicb structure, defined as follows:

           struct gaicb {
               const char            *ar_name;
               const char            *ar_service;
               const struct addrinfo *ar_request;
               struct addrinfo       *ar_result;
           };

       The elements of this structure correspond to the arguments of
       getaddrinfo(3).  Thus, ar_name corresponds to the node argument and
       ar_service to the service argument, identifying an Internet host and a
       service.  The ar_request element corresponds to the hints argument,
       specifying the criteria for selecting the returned socket address
       structures.  Finally, ar_result corresponds to the res argument; you do not
       need to initialize this element, it will be automatically set when the
       request is resolved.  The addrinfo structure referenced by the last two
       elements is described in getaddrinfo(3).

       When mode is specified as GAI_NOWAIT, notifications about resolved requests
       can be obtained by employing the sigevent structure pointed to by the sevp
       argument.  For the definition and general details of this structure, see
       sigevent(7).  The sevp->sigev_notify field can have the following values:

       SIGEV_NONE
              Don't provide any notification.

       SIGEV_SIGNAL
              When a look-up completes, generate the signal sigev_signo for the
              process.  See sigevent(7) for general details.  The si_code field of
              the siginfo_t structure will be set to SI_ASYNCNL.

       SIGEV_THREAD
              When a look-up completes, invoke sigev_notify_function as if it were
              the start function of a new thread.  See sigevent(7) for details.

       For SIGEV_SIGNAL and SIGEV_THREAD, it may be useful to point
       sevp->sigev_value.sival_ptr to list.

       The gai_suspend() function suspends execution of the calling thread,
       waiting for the completion of one or more requests in the array list.  The
       nitems argument specifies the size of the array list.  The call blocks
       until one of the following occurs:

       *  One or more of the operations in list completes.

       *  The call is interrupted by a signal that is caught.

       *  The time interval specified in timeout elapses.  This argument specifies
          a timeout in seconds plus nanoseconds (see nanosleep(2) for details of
          the timespec structure).  If timeout is NULL, then the call blocks
          indefinitely (until one of the events above occurs).

       No explicit indication of which request was completed is given; you must
       determine which request(s) have completed by iterating with gai_error()
       over the list of requests.

       The gai_error() function returns the status of the request req: either
       EAI_INPROGRESS if the request was not completed yet, 0 if it was handled
       successfully, or an error code if the request could not be resolved.

       The gai_cancel() function cancels the request req.  If the request has been
       canceled successfully, the error status of the request will be set to
       EAI_CANCELLED and normal asynchronous notification will be performed.  The
       request cannot be canceled if it is currently being processed; in that
       case, it will be handled as if gai_cancel() has never been called.  If req
       is NULL, an attempt is made to cancel all outstanding requests that the
       process has made.

RETURN VALUE top

       The getaddrinfo_a() function returns 0 if all of the requests have been
       enqueued successfully, or one of the following nonzero error codes:

       EAI_AGAIN
              The resources necessary to enqueue the look-up requests were not
              available.  The application may check the error status of each
              request to determine which ones failed.

       EAI_MEMORY
              Out of memory.

       EAI_SYSTEM
              mode is invalid.

       The gai_suspend() function returns 0 if at least one of the listed requests
       has been completed.  Otherwise, it returns one of the following nonzero
       error codes:

       EAI_AGAIN
              The given timeout expired before any of the requests could be
              completed.

       EAI_ALLDONE
              There were no actual requests given to the function.

       EAI_INTR
              A signal has interrupted the function.  Note that this interruption
              might have been caused by signal notification of some completed
              look-up request.

       The gai_error() function can return EAI_INPROGRESS for an unfinished look-
       up request, 0 for a successfully completed look-up (as described above),
       one of the error codes that could be returned by getaddrinfo(3), or the
       error code EAI_CANCELLED if the request has been canceled explicitly before
       it could be finished.

       The gai_cancel() function can return one of these values:

       EAI_CANCELLED
              The request has been canceled successfully.

       EAI_NOTCANCELLED
              The request has not been canceled.

       EAI_ALLDONE
              The request has already completed.

       The gai_strerror(3) function translates these error codes to a human
       readable string, suitable for error reporting.

CONFORMING TO top

       These functions are GNU extensions; they first appeared in glibc in version
       2.2.3.

NOTES top

       The interface of getaddrinfo_a() was modeled after the lio_listio(3)
       interface.

EXAMPLE top

       Two examples are provided: a simple example that resolves several requests
       in parallel synchronously, and a complex example showing some of the
       asynchronous capabilities.

Synchronous Example

       The program below simply resolves several hostnames in parallel, giving a
       speed-up compared to resolving the hostnames sequentially using
       getaddrinfo(3).  The program might be used like this:

           $ ./a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
           ftp.us.kernel.org: 128.30.2.36
           enoent.linuxfoundation.org: Name or service not known
           gnu.cz: 87.236.197.13

       Here is the program source code

       #define _GNU_SOURCE
       #include <netdb.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           int i, ret;
           struct gaicb *reqs[argc - 1];
           char host[NI_MAXHOST];
           struct addrinfo *res;

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

           for (i = 0; i < argc - 1; i++) {
               reqs[i] = malloc(sizeof(*reqs[0]));
               if (reqs[i] == NULL) {
                   perror("malloc");
                   exit(EXIT_FAILURE);
               }
               memset(reqs[i], 0, sizeof(*reqs[0]));
               reqs[i]->ar_name = argv[i + 1];
           }

           ret = getaddrinfo_a(GAI_WAIT, reqs, argc - 1, NULL);
           if (ret != 0) {
               fprintf(stderr, "getaddrinfo_a() failed: %s\n",
                       gai_strerror(ret));
               exit(EXIT_FAILURE);
           }

           for (i = 0; i < argc - 1; i++) {
               printf("%s: ", reqs[i]->ar_name);
               ret = gai_error(reqs[i]);
               if (ret == 0) {
                   res = reqs[i]->ar_result;

                   ret = getnameinfo(res->ai_addr, res->ai_addrlen,
                           host, sizeof(host),
                           NULL, 0, NI_NUMERICHOST);
                   if (ret != 0) {
                       fprintf(stderr, "getnameinfo() failed: %s\n",
                               gai_strerror(ret));
                       exit(EXIT_FAILURE);
                   }
                   puts(host);

               } else {
                   puts(gai_strerror(ret));
               }
           }
           exit(EXIT_SUCCESS);
       }

Asynchronous Example

       This example shows a simple interactive getaddrinfo_a() front-end.  The
       notification facility is not demonstrated.

       An example session might look like this:

           $ ./a.out
           > a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
           > c 2
           [2] gnu.cz: Request not canceled
           > w 0 1
           [00] ftp.us.kernel.org: Finished
           > l
           [00] ftp.us.kernel.org: 216.165.129.139
           [01] enoent.linuxfoundation.org: Processing request in progress
           [02] gnu.cz: 87.236.197.13
           > l
           [00] ftp.us.kernel.org: 216.165.129.139
           [01] enoent.linuxfoundation.org: Name or service not known
           [02] gnu.cz: 87.236.197.13

       The program source goes as follows:

       #define _GNU_SOURCE
       #include <netdb.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       static struct gaicb **reqs = NULL;
       static int nreqs = 0;

       static char *
       getcmd(void)
       {
           static char buf[256];

           fputs("> ", stdout); fflush(stdout);
           if (fgets(buf, sizeof(buf), stdin) == NULL)
               return NULL;

           if (buf[strlen(buf) - 1] == '\n')
               buf[strlen(buf) - 1] = 0;

           return buf;
       }

       /* Add requests for specified hostnames */
       static void
       add_requests(void)
       {
           int nreqs_base = nreqs;
           char *host;
           int ret;

           while ((host = strtok(NULL, " "))) {
               nreqs++;
               reqs = realloc(reqs, nreqs * sizeof(reqs[0]));

               reqs[nreqs - 1] = calloc(1, sizeof(*reqs[0]));
               reqs[nreqs - 1]->ar_name = strdup(host);
           }

           /* Queue nreqs_base..nreqs requests. */

           ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base],
                               nreqs - nreqs_base, NULL);
           if (ret) {
               fprintf(stderr, "getaddrinfo_a() failed: %s\n",
                       gai_strerror(ret));
               exit(EXIT_FAILURE);
           }
       }

       /* Wait until at least one of specified requests completes */
       static void
       wait_requests(void)
       {
           char *id;
           int i, ret, n;
           struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs));
                       /* NULL elements are ignored by gai_suspend(). */

           while ((id = strtok(NULL, " ")) != NULL) {
               n = atoi(id);

               if (n >= nreqs) {
                   printf("Bad request number: %s\n", id);
                   return;
               }

               wait_reqs[n] = reqs[n];
           }

           ret = gai_suspend(wait_reqs, nreqs, NULL);
           if (ret) {
               printf("gai_suspend(): %s\n", gai_strerror(ret));
               return;
           }

           for (i = 0; i < nreqs; i++) {
               if (wait_reqs[i] == NULL)
                   continue;

               ret = gai_error(reqs[i]);
               if (ret == EAI_INPROGRESS)
                   continue;

               printf("[%02d] %s: %s\n", i, reqs[i]->ar_name,
                      ret == 0 ? "Finished" : gai_strerror(ret));
           }
       }

       /* Cancel specified requests */
       static void
       cancel_requests(void)
       {
           char *id;
           int ret, n;

           while ((id = strtok(NULL, " ")) != NULL) {
               n = atoi(id);

               if (n >= nreqs) {
                   printf("Bad request number: %s\n", id);
                   return;
               }

               ret = gai_cancel(reqs[n]);
               printf("[%s] %s: %s\n", id, reqs[atoi(id)]->ar_name,
                      gai_strerror(ret));
           }
       }

       /* List all requests */
       static void
       list_requests(void)
       {
           int i, ret;
           char host[NI_MAXHOST];
           struct addrinfo *res;

           for (i = 0; i < nreqs; i++) {
               printf("[%02d] %s: ", i, reqs[i]->ar_name);
               ret = gai_error(reqs[i]);

               if (!ret) {
                   res = reqs[i]->ar_result;

                   ret = getnameinfo(res->ai_addr, res->ai_addrlen,
                                     host, sizeof(host),
                                     NULL, 0, NI_NUMERICHOST);
                   if (ret) {
                       fprintf(stderr, "getnameinfo() failed: %s\n",
                               gai_strerror(ret));
                       exit(EXIT_FAILURE);
                   }
                   puts(host);
               } else {
                   puts(gai_strerror(ret));
               }
           }
       }

       int
       main(int argc, char *argv[])
       {
           char *cmdline;
           char *cmd;

           while ((cmdline = getcmd()) != NULL) {
               cmd = strtok(cmdline, " ");

               if (cmd == NULL) {
                   list_requests();
               } else {
                   switch (cmd[0]) {
                   case 'a':
                       add_requests();
                       break;
                   case 'w':
                       wait_requests();
                       break;
                   case 'c':
                       cancel_requests();
                       break;
                   case 'l':
                       list_requests();
                       break;
                   default:
                       fprintf(stderr, "Bad command: %c\n", cmd[0]);
                       break;
                   }
               }
           }
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getaddrinfo(3), inet(3), lio_listio(3), hostname(7), ip(7), sigevent(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-27                    GETADDRINFO_A(3)


gamma(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GAMMA(3)                     Linux Programmer's Manual                    GAMMA(3)

NAME top

       gamma, gammaf, gammal - (logarithm of the) gamma function

SYNOPSIS top

       #include <math.h>

       double gamma(double x);
       float gammaf(float x);
       long double gammal(long double x);

       Link with -lm.

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

       gamma():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE
       gammaf(), gammal():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600

DESCRIPTION top

       These functions are deprecated: instead, use either the tgamma(3) or the
       lgamma(3) functions, as appropriate.

       For the definition of the Gamma function, see tgamma(3).

*BSD version

       The libm in 4.4BSD and some versions of FreeBSD had a gamma() function that
       computes the Gamma function, as one would expect.

glibc version

       Glibc has a gamma() function that is equivalent to lgamma(3) and computes
       the natural logarithm of the Gamma function.

RETURN VALUE top

       See lgamma(3).

ERRORS top

       See lgamma(3).

CONFORMING TO top

       Because of historical variations in behavior across systems, this function
       is not specified in any standard.

NOTES top

History

       4.2BSD had a gamma() that computed ln(|Gamma(|x|)|), leaving the sign of
       Gamma(|x|) in the external integer signgam.  In 4.3BSD the name was changed
       to lgamma(3), and the man page promises

           "At some time in the future the name gamma will be rehabilitated and
           used for the Gamma function"

       This did indeed happen in 4.4BSD, where gamma() computes the Gamma function
       (with no effect on signgam).  However, this came too late, and we now have
       tgamma(3), the "true gamma" function.

SEE ALSO          top
       lgamma(3), signgam(3), tgamma(3)

COLOPHON          top
       This page is part of release 3.45 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/.

GNU                                 2008-08-05                            GAMMA(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


gcvt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GCVT(3)                      Linux Programmer's Manual                     GCVT(3)

NAME top

       gcvt - convert a floating-point number to a string

SYNOPSIS top

       #include <stdlib.h>

       char *gcvt(double number, size_t ndigit, char *buf);

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

       gcvt():
           Since glibc 2.12:
               _SVID_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _SVID_SOURCE || _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE &&
               _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The gcvt() function converts number to a minimal length null-terminated
       ASCII string and stores the result in buf.  It produces ndigit significant
       digits in either printf(3) F format or E format.

RETURN VALUE top

       The gcvt() function returns the address of the string pointed to by buf.

CONFORMING TO top

       Marked as LEGACY in POSIX.1-2001.  POSIX.1-2008 removes the specification
       of gcvt(), recommending the use of sprintf(3) instead (though snprintf(3)
       may be preferable).

SEE ALSO top

       ecvt(3), fcvt(3), sprintf(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             GCVT(3)


getauxval(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETAUXVAL(3)                 Linux Programmer's Manual                GETAUXVAL(3)

NAME top

       getauxval - retrieve a value from the auxiliary vector

SYNOPSIS top

       #include <sys/auxv.h>

       unsigned long getauxval(unsigned long type);

DESCRIPTION top

       The getauxval() function retrieves values from the auxiliary vector, a
       mechanism that the kernel's ELF binary loader uses to pass certain
       information to user space when a program is executed.

       Each entry in the auxiliary vector consists of a pair of values: a type
       that identifies what this entry represents, and a value for that type.
       Given the argument type, getauxval() returns the corresponding value.

       The value returned for each type is given in the following list.  Not all
       type values are present on all architectures.

       AT_BASE
              The base address of the program interpreter (usually, the dynamic
              linker).

       AT_BASE_PLATFORM
              A string identifying the real platform; may differ from AT_PLATFORM
              (PowerPC only).

       AT_CLKTCK
              The frequency with which times(2) counts.  This value can also be
              obtained via sysconf(_SC_CLK_TCK).

       AT_DCACHEBSIZE
              The data cache block size.

       AT_EGID
              The effective group ID of the thread.

       AT_ENTRY
              The entry address of the executable.

       AT_EUID
              The effective user ID of the thread.

       AT_EXECFD
              File descriptor of program.

       AT_EXECFN
              Pathname used to execute program.

       AT_FLAGS
              Flags (unused).

       AT_FPUCW
              Used FPU control word (SuperH architecture only).  This gives some
              information about the FPU initialization performed by the kernel.

       AT_GID The real group ID of the thread.

       AT_HWCAP
              A pointer to a multibyte mask of bits whose settings indicate
              detailed processor capabilities.  The contents of the bit mask are
              hardware dependent (for example, see the kernel source file
              arch/x86/include/asm/cpufeature.h for details relating to the Intel
              x86 architecture).  A human-readable version of the same information
              is available via /proc/cpuinfo.

       AT_ICACHEBSIZE
              The instruction cache block size.

       AT_PAGESZ
              The system page size (the same value returned by
              sysconf(_SC_PAGESIZE)).

       AT_PHDR
              The address of the program headers of the executable.

       AT_PHENT
              The size of program header entry.

       AT_PHNUM
              The number of program headers.

       AT_PLATFORM
              A pointer to a string that identifies the hardware platform that the
              program is running on.  The dynamic linker uses this in the
              interpretation of rpath values.

       AT_RANDOM
              The address of sixteen bytes containing a random value.

       AT_SECURE
              Has a nonzero value if this executable should be treated securely.
              Most commonly, a nonzero value indicates that the process is
              executing a set-user-ID or set-group-ID program; alternatively, a
              nonzero value may be triggered by a Linux Security Module.  When
              this value is nonzero, the dynamic linker disables the use of
              certain environment variables (see ld-linux.so(8)) and glibc changes
              other aspects of its behavior.  (See also secure_getenv(3).)

       AT_SYSINFO
              The entry point to the system call function in the VDSO.  Not
              present/needed on all architectures (e.g., absent on x86-64).

       AT_SYSINFO_EHDR
              The address of a page containing the Virtual Dynamic Shared Object
              (VDSO) that the kernel creates in order to provide fast
              implementations of certain system calls.

       AT_UCACHEBSIZE
              The unified cache block size.

       AT_UID The real user ID of the thread.

RETURN VALUE top

       On success, getauxval() returns the value corresponding to type.  If type
       is not found, 0 is returned.

ERRORS top

       No errors are diagnosed.

VERSIONS top

       The getauxval() function was added to glibc in version 2.16.

CONFORMING TO top

       This function is a nonstandard glibc extension.

NOTES top

       The primary consumer of the information in the auxiliary vector is the
       dynamic linker ld-linux.so(8).  The auxiliary vector is a convenient and
       efficient shortcut that allows the kernel to communicate a certain set of
       standard information that the dynamic linker usually or always needs.  In
       some cases, the same information could be obtained by system calls, but
       using the auxiliary vector is cheaper.

       The auxiliary vector resides just above the argument list and environment
       in the process address space.  The auxiliary vector supplied to a program
       can be viewed by setting the LD_SHOW_AUXV environment variable when running
       a program:

           $ LD_SHOW_AUXV=1 sleep 1

       The auxiliary vector of any process can (subject to file permissions) be
       obtained via /proc/PID/auxv; see proc(5) for more information.

SEE ALSO top

       secure_getenv(3), ld-linux.so(8)

       The kernel source file Documentation/ABI/stable/vdso

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-11-07                        GETAUXVAL(3)


getcontext(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETCONTEXT(2)                Linux Programmer's Manual               GETCONTEXT(2)

NAME top

       getcontext, setcontext - get or set the user context

SYNOPSIS top

       #include <ucontext.h>

       int getcontext(ucontext_t *ucp);
       int setcontext(const ucontext_t *ucp);

DESCRIPTION top

       In a System V-like environment, one has the two types mcontext_t and
       ucontext_t defined in <ucontext.h> and the four functions getcontext(),
       setcontext(), makecontext(3) and swapcontext(3) that allow user-level
       context switching between multiple threads of control within a process.

       The mcontext_t type is machine-dependent and opaque.  The ucontext_t type
       is a structure that has at least the following fields:

           typedef struct ucontext {
               struct ucontext *uc_link;
               sigset_t         uc_sigmask;
               stack_t          uc_stack;
               mcontext_t       uc_mcontext;
               ...
           } ucontext_t;

       with sigset_t and stack_t defined in <signal.h>.  Here uc_link points to
       the context that will be resumed when the current context terminates (in
       case the current context was created using makecontext(3)), uc_sigmask is
       the set of signals blocked in this context (see sigprocmask(2)), uc_stack
       is the stack used by this context (see sigaltstack(2)), and uc_mcontext is
       the machine-specific representation of the saved context, that includes the
       calling thread's machine registers.

       The function getcontext() initializes the structure pointed at by ucp to
       the currently active context.

       The function setcontext() restores the user context pointed at by ucp.  A
       successful call does not return.  The context should have been obtained by
       a call of getcontext(), or makecontext(3), or passed as third argument to a
       signal handler.

       If the context was obtained by a call of getcontext(), program execution
       continues as if this call just returned.

       If the context was obtained by a call of makecontext(3), program execution
       continues by a call to the function func specified as the second argument
       of that call to makecontext(3).  When the function func returns, we
       continue with the uc_link member of the structure ucp specified as the
       first argument of that call to makecontext(3).  When this member is NULL,
       the thread exits.

       If the context was obtained by a call to a signal handler, then old
       standard text says that "program execution continues with the program
       instruction following the instruction interrupted by the signal".  However,
       this sentence was removed in SUSv2, and the present verdict is "the result
       is unspecified".

RETURN VALUE top

       When successful, getcontext() returns 0 and setcontext() does not return.
       On error, both return -1 and set errno appropriately.

ERRORS top

       None defined.

CONFORMING TO top

       SUSv2, POSIX.1-2001.  POSIX.1-2008 removes the specification of
       getcontext(), citing portability issues, and recommending that applications
       be rewritten to use POSIX threads instead.

NOTES top

       The earliest incarnation of this mechanism was the setjmp(3)/longjmp(3)
       mechanism.  Since that does not define the handling of the signal context,
       the next stage was the sigsetjmp(3)/siglongjmp(3) pair.  The present
       mechanism gives much more control.  On the other hand, there is no easy way
       to detect whether a return from getcontext() is from the first call, or via
       a setcontext() call.  The user has to invent her own bookkeeping device,
       and a register variable won't do since registers are restored.

       When a signal occurs, the current user context is saved and a new context
       is created by the kernel for the signal handler.  Do not leave the handler
       using longjmp(3): it is undefined what would happen with contexts.  Use
       siglongjmp(3) or setcontext() instead.

SEE ALSO top

       sigaction(2), sigaltstack(2), sigprocmask(2), longjmp(3), makecontext(3),
       sigsetjmp(3)

COLOPHON top

       This page is part of release 3.45 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                               2009-03-15                       GETCONTEXT(2)


getcpu(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETCPU(2)                    Linux Programmer's Manual                   GETCPU(2)

NAME top

       getcpu - determine CPU and NUMA node on which the calling thread is running

SYNOPSIS top

       #include <linux/getcpu.h>

       int getcpu(unsigned *cpu, unsigned *node, struct getcpu_cache *tcache);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The getcpu() system call identifies the processor and node on which the
       calling thread or process is currently running and writes them into the
       integers pointed to by the cpu and node arguments.  The processor is a
       unique small integer identifying a CPU.  The node is a unique small
       identifier identifying a NUMA node.  When either cpu or node is NULL
       nothing is written to the respective pointer.

       The third argument to this system call is nowadays unused (see NOTES).

       The information placed in cpu is only guaranteed to be current at the time
       of the call: unless the CPU affinity has been fixed using
       sched_setaffinity(2), the kernel might change the CPU at any time.
       (Normally this does not happen because the scheduler tries to minimize
       movements between CPUs to keep caches hot, but it is possible.)  The caller
       must allow for the possibility that the information returned in cpu and
       node is no longer current by the time the call returns.

RETURN VALUE top

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

ERRORS top

       EFAULT Arguments point outside the calling process's address space.

VERSIONS top

       getcpu() was added in kernel 2.6.19 for x86_64 and i386.

CONFORMING TO top

       getcpu() is Linux specific.

NOTES top

       Linux makes a best effort to make this call as fast possible.  The
       intention of getcpu() is to allow programs to make optimizations with per-
       CPU data or for NUMA optimization.

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2); or use sched_getcpu(3) instead.

       The tcache argument is unused since Linux 2.6.24.  In earlier kernels, if
       this argument was non-NULL, then it specified a pointer to a caller-
       allocated buffer in thread-local storage that was used to provide a caching
       mechanism for getcpu().  Use of the cache could speed getcpu() calls, at
       the cost that there was a very small chance that the returned information
       would be out of date.  The caching mechanism was considered to cause
       problems when migrating threads between CPUs, and so the argument is now
       ignored.

SEE ALSO top

       mbind(2), sched_setaffinity(2), set_mempolicy(2), sched_getcpu(3),
       cpuset(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                           GETCPU(2)


getcwd(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETCWD(3)                    Linux Programmer's Manual                   GETCWD(3)

NAME top

       getcwd, getwd, get_current_dir_name - get current working directory

SYNOPSIS top

       #include <unistd.h>

       char *getcwd(char *buf, size_t size);

       char *getwd(char *buf);

       char *get_current_dir_name(void);

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

       get_current_dir_name():
              _GNU_SOURCE

       getwd():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       These functions return a null-terminated string containing an absolute
       pathname that is the current working directory of the calling process.  The
       pathname is returned as the function result and via the argument buf, if
       present.

       The getcwd() function copies an absolute pathname of the current working
       directory to the array pointed to by buf, which is of length size.

       If the length of the absolute pathname of the current working directory,
       including the terminating null byte, exceeds size bytes, NULL is returned,
       and errno is set to ERANGE; an application should check for this error, and
       allocate a larger buffer if necessary.

       As an extension to the POSIX.1-2001 standard, Linux (libc4, libc5, glibc)
       getcwd() allocates the buffer dynamically using malloc(3) if buf is NULL.
       In this case, the allocated buffer has the length size unless size is zero,
       when buf is allocated as big as necessary.  The caller should free(3) the
       returned buffer.

       get_current_dir_name() will malloc(3) an array big enough to hold the
       absolute pathname of the current working directory.  If the environment
       variable PWD is set, and its value is correct, then that value will be
       returned.  The caller should free(3) the returned buffer.

       getwd() does not malloc(3) any memory.  The buf argument should be a
       pointer to an array at least PATH_MAX bytes long.  If the length of the
       absolute pathname of the current working directory, including the
       terminating null byte, exceeds PATH_MAX bytes, NULL is returned, and errno
       is set to ENAMETOOLONG.  (Note that on some systems, PATH_MAX may not be a
       compile-time constant; furthermore, its value may depend on the file
       system, see pathconf(3).)  For portability and security reasons, use of
       getwd() is deprecated.

RETURN VALUE top

       On success, these functions return a pointer to a string containing the
       pathname of the current working directory.  In the case getcwd() and
       getwd() this is the same value as buf.

       On failure, these functions return NULL, and errno is set to indicate the
       error.  The contents of the array pointed to by buf are undefined on error.

ERRORS top

       EACCES Permission to read or search a component of the filename was denied.

       EFAULT buf points to a bad address.

       EINVAL The size argument is zero and buf is not a NULL pointer.

       EINVAL getwd(): buf is NULL.

       ENAMETOOLONG
              getwd(): The size of the null-terminated absolute pathname string
              exceeds PATH_MAX bytes.

       ENOENT The current working directory has been unlinked.

       ERANGE The size argument is less than the length of the absolute pathname
              of the working directory, including the terminating null byte.  You
              need to allocate a bigger array and try again.

CONFORMING TO top

       getcwd() conforms to POSIX.1-2001.  Note however that POSIX.1-2001 leaves
       the behavior of getcwd() unspecified if buf is NULL.

       getwd() is present in POSIX.1-2001, but marked LEGACY.  POSIX.1-2008
       removes the specification of getwd().  Use getcwd() instead.  POSIX.1-2001
       does not define any errors for getwd().

       get_current_dir_name() is a GNU extension.

NOTES top

       Under Linux, the function getcwd() is a system call (since 2.1.92).  On
       older systems it would query /proc/self/cwd.  If both system call and proc
       file system are missing, a generic implementation is called.  Only in that
       case can these calls fail under Linux with EACCES.

       These functions are often used to save the location of the current working
       directory for the purpose of returning to it later.  Opening the current
       directory (".") and calling fchdir(2) to return is usually a faster and
       more reliable alternative when sufficiently many file descriptors are
       available, especially on platforms other than Linux.

SEE ALSO top

       chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           GETCWD(3)


getdate(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ENVIRONMENT | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETDATE(3)                   Linux Programmer's Manual                  GETDATE(3)

NAME top

       getdate, getdate_r - convert a date-plus-time string to broken-down time

SYNOPSIS top

       #include <time.h>

       struct tm *getdate(const char *string);

       extern int getdate_err;

       #include <time.h>

       int getdate_r(const char *string, struct tm *res);

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

       getdate():
           _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
       getdate_r():
           _GNU_SOURCE

DESCRIPTION top

       The function getdate() converts a string representation of a date and time,
       contained in the buffer pointed to by string, into a broken-down time.  The
       broken-down time is stored in a tm structure, and a pointer to this
       structure is returned as the function result.  This tm structure is
       allocated in static storage, and consequently it will be overwritten by
       further calls to getdate().

       In contrast to strptime(3), (which has a format argument), getdate() uses
       the formats found in the file whose full pathname is given in the
       environment variable DATEMSK.  The first line in the file that matches the
       given input string is used for the conversion.

       The matching is done case insensitively.  Superfluous whitespace, either in
       the pattern or in the string to be converted, is ignored.

       The conversion specifications that a pattern can contain are those given
       for strptime(3).  One more conversion specification is specified in
       POSIX.1-2001:

       %Z     Timezone name.  This is not implemented in glibc.

       When %Z is given, the structure containing the broken-down time is
       initialized with values corresponding to the current time in the given
       timezone.  Otherwise, the structure is initialized to the broken-down time
       corresponding to the current local time (as by a call to localtime(3)).

       When only the weekday is given, the day is taken to be the first such day
       on or after today.

       When only the month is given (and no year), the month is taken to be the
       first such month equal to or after the current month.  If no day is given,
       it is the first day of the month.

       When no hour, minute and second are given, the current hour, minute and
       second are taken.

       If no date is given, but we know the hour, then that hour is taken to be
       the first such hour equal to or after the current hour.

       getdate_r() is a GNU extension that provides a reentrant version of
       getdate().  Rather than using a global variable to report errors and a
       static buffer to return the broken down time, it returns errors via the
       function result value, and returns the resulting broken-down time in the
       caller-allocated buffer pointed to by the argument res.

RETURN VALUE top

       When successful, getdate() returns a pointer to a struct tm.  Otherwise, it
       returns NULL and sets the global variable getdate_err to one of the error
       numbers shown below.  Changes to errno are unspecified.

       On success getdate_r() returns 0; on error it returns one of the error
       numbers shown below.

ERRORS top

       The following errors are returned via getdate_err (for getdate()) or as the
       function result (for getdate_r()):

       1   The DATEMSK environment variable is not defined, or its value is an
           empty string.

       2   The template file specified by DATEMSK cannot be opened for reading.

       3   Failed to get file status information.

       4   The template file is not a regular file.

       5   An error was encountered while reading the template file.

       6   Memory allocation failed (not enough memory available).

       7   There is no line in the file that matches the input.

       8   Invalid input specification.

ENVIRONMENT top

       DATEMSK
              File containing format patterns.

       TZ, LC_TIME
              Variables used by strptime(3).

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The POSIX.1-2001 specification for strptime(3) contains conversion
       specifications using the %E or %O modifier, while such specifications are
       not given for getdate().  In glibc, getdate() is implemented using
       strptime(3), so that precisely the same conversions are supported by both.

EXAMPLE top

       The program below calls getdate() for each of its command-line arguments,
       and for each call displays the values in the fields of the returned tm
       structure.  The following shell session demonstrates the operation of the
       program:

           $ TFILE=$PWD/tfile
           $ echo '%A' > $TFILE       # Full weekday name
           $ echo '%T' >> $TFILE      # ISO date (YYYY-MM-DD)
           $ echo '%F' >> $TFILE      # Time (HH:MM:SS)
           $ date
           $ export DATEMSK=$TFILE
           $ ./a.out Tuesday '2009-12-28' '12:22:33'
           Sun Sep  7 06:03:36 CEST 2008
           Call 1 ("Tuesday") succeeded:
               tm_sec   = 36
               tm_min   = 3
               tm_hour  = 6
               tm_mday  = 9
               tm_mon   = 8
               tm_year  = 108
               tm_wday  = 2
               tm_yday  = 252
               tm_isdst = 1
           Call 2 ("2009-12-28") succeeded:
               tm_sec   = 36
               tm_min   = 3
               tm_hour  = 6
               tm_mday  = 28
               tm_mon   = 11
               tm_year  = 109
               tm_wday  = 1
               tm_yday  = 361
               tm_isdst = 0
           Call 3 ("12:22:33") succeeded:
               tm_sec   = 33
               tm_min   = 22
               tm_hour  = 12
               tm_mday  = 7
               tm_mon   = 8
               tm_year  = 108
               tm_wday  = 0
               tm_yday  = 250
               tm_isdst = 1

Program source

       #define _GNU_SOURCE 500
       #include <time.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           struct tm *tmp;
           int j;

           for (j = 1; j < argc; j++) {
               tmp = getdate(argv[j]);

               if (tmp == NULL) {
                   printf("Call %d failed; getdate_err = %d\n",
                          j, getdate_err);
                   continue;
               }

               printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
               printf("    tm_sec   = %d\n", tmp->tm_sec);
               printf("    tm_min   = %d\n", tmp->tm_min);
               printf("    tm_hour  = %d\n", tmp->tm_hour);
               printf("    tm_mday  = %d\n", tmp->tm_mday);
               printf("    tm_mon   = %d\n", tmp->tm_mon);
               printf("    tm_year  = %d\n", tmp->tm_year);
               printf("    tm_wday  = %d\n", tmp->tm_wday);
               printf("    tm_yday  = %d\n", tmp->tm_yday);
               printf("    tm_isdst = %d\n", tmp->tm_isdst);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       time(2), localtime(3), setlocale(3), strftime(3), strptime(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                          GETDATE(3)


getline(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETLINE(3)                   Linux Programmer's Manual                  GETLINE(3)

NAME top

       getline, getdelim - delimited string input

SYNOPSIS top

       #include <stdio.h>

       ssize_t getline(char **lineptr, size_t *n, FILE *stream);

       ssize_t getdelim(char **lineptr, size_t *n, int delim, FILE *stream);

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

       getline(), getdelim():
           Since glibc 2.10:
               _POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       getline() reads an entire line from stream, storing the address of the
       buffer containing the text into *lineptr.  The buffer is null-terminated
       and includes the newline character, if one was found.

       If *lineptr is NULL, then getline() will allocate a buffer for storing the
       line, which should be freed by the user program.  (In this case, the value
       in *n is ignored.)

       Alternatively, before calling getline(), *lineptr can contain a pointer to
       a malloc(3)-allocated buffer *n bytes in size.  If the buffer is not large
       enough to hold the line, getline() resizes it with realloc(3), updating
       *lineptr and *n as necessary.

       In either case, on a successful call, *lineptr and *n will be updated to
       reflect the buffer address and allocated size respectively.

       getdelim() works like getline(), except that a line delimiter other than
       newline can be specified as the delimiter argument.  As with getline(), a
       delimiter character is not added if one was not present in the input before
       end of file was reached.

RETURN VALUE top

       On success, getline() and getdelim() return the number of characters read,
       including the delimiter character, but not including the terminating null
       byte.  This value can be used to handle embedded null bytes in the line
       read.

       Both functions return -1 on failure to read a line (including end-of-file
       condition).

ERRORS top

       EINVAL Bad arguments (n or lineptr is NULL, or stream is not valid).

VERSIONS top

       These functions are available since libc 4.6.27.

CONFORMING TO top

       Both getline() and getdelim() were originally GNU extensions.  They were
       standardized in POSIX.1-2008.

EXAMPLE top

       #define _GNU_SOURCE
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(void)
       {
           FILE *fp;
           char *line = NULL;
           size_t len = 0;
           ssize_t read;

           fp = fopen("/etc/motd", "r");
           if (fp == NULL)
               exit(EXIT_FAILURE);

           while ((read = getline(&line, &len, fp)) != -1) {
               printf("Retrieved line of length %zu :\n", read);
               printf("%s", line);
           }

           free(line);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       read(2), fgets(3), fopen(3), fread(3), gets(3), scanf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-06-12                          GETLINE(3)


getdents(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETDENTS(2)                  Linux Programmer's Manual                 GETDENTS(2)

NAME top

       getdents - get directory entries

SYNOPSIS top

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

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       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 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 values (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.

       The d_type field is implemented since Linux 2.6.4.  It occupies a space
       that was previously a zero-filled padding byte in the linux_dirent
       structure.  Thus, on kernels before 2.6.3, attempting to access this field
       always provides the value 0 (DT_UNKNOWN).

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

RETURN VALUE top

       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 top

       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 top

       SVr4.

NOTES top

       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.
       However, you probably want to use readdir(3) instead.

       This call supersedes readdir(2).

       The original Linux getdents() system call did not handle large file systems
       and large file offsets.  Consequently, Linux 2.4 added getdents64(), with
       wider types for the d_ino and d_off fields employed in the linux_dirent
       structure.

EXAMPLE top

       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 _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;
           char d_type;

           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);
                   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" : "???");
                   printf("%4d %10lld  %s\n", d->d_reclen,
                           (long long) d->d_off, d->d_name);
                   bpos += d->d_reclen;
               }
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       readdir(2), readdir(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-03                         GETDENTS(2)


getdirentries(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETDIRENTRIES(3)             Linux Programmer's Manual            GETDIRENTRIES(3)

NAME top

       getdirentries - get directory entries in a file system-independent format

SYNOPSIS top

       #include <dirent.h>

       ssize_t getdirentries(int fd, char *buf, size_t nbytes , off_t *basep);

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

       getdirentries(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       Read directory entries from the directory specified by fd into buf.  At
       most nbytes are read.  Reading starts at offset *basep, and *basep is
       updated with the new position after reading.

RETURN VALUE top

       getdirentries() returns the number of bytes read or zero when at the end of
       the directory.  If an error occurs, -1 is returned, and errno is set
       appropriately.

ERRORS top

       See the Linux library source code for details.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs, and a few other systems.  Use
       opendir(3) and readdir(3) instead.

SEE ALSO top

       lseek(2), open(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                    GETDIRENTRIES(3)


getdomainname(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETDOMAINNAME(2)             Linux Programmer's Manual            GETDOMAINNAME(2)

NAME top

       getdomainname, setdomainname - get/set NIS domain name

SYNOPSIS top

       #include <unistd.h>

       int getdomainname(char *name, size_t len);
       int setdomainname(const char *name, size_t len);

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

       getdomainname(), setdomainname():
           _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       These functions are used to access or to change the NIS domain name of the
       host system.

       setdomainname() sets the domain name to the value given in the character
       array name.  The len argument specifies the number of bytes in name.
       (Thus, name does not require a terminating null byte.)

       getdomainname() returns the null-terminated domain name in the character
       array name, which has a length of len bytes.  If the null-terminated domain
       name requires more than len bytes, getdomainname() returns the first len
       bytes (glibc) or gives an error (libc).

RETURN VALUE top

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

ERRORS top

       setdomainname() can fail with the following errors:

       EFAULT name pointed outside of user address space.

       EINVAL len was negative or too large.

       EPERM  the caller is unprivileged (Linux: does not have the CAP_SYS_ADMIN
              capability).

       getdomainname() can fail with the following errors:

       EINVAL For getdomainname() under libc: name is NULL or name is longer than
              len bytes.

CONFORMING TO top

       POSIX does not specify these calls.

NOTES top

       Since Linux 1.0, the limit on the length of a domain name, including the
       terminating null byte, is 64 bytes.  In older kernels, it was 8 bytes.

       On most Linux architectures (including x86), there is no getdomainname()
       system call; instead, glibc implements getdomainname() as a library
       function that returns a copy of the domainname field returned from a call
       to uname(2).

SEE ALSO top

       gethostname(2), sethostname(2), uname(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-25                    GETDOMAINNAME(2)


getdtablesize(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETDTABLESIZE(2)             Linux Programmer's Manual            GETDTABLESIZE(2)

NAME top

       getdtablesize - get descriptor table size

SYNOPSIS top

       #include <unistd.h>

       int getdtablesize(void);

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

       getdtablesize():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       getdtablesize() returns the maximum number of files a process can have
       open, one more than the largest possible value for a file descriptor.

RETURN VALUE top

       The current limit on the number of open files per process.

ERRORS top

       On Linux, getdtablesize() can return any of the errors described for
       getrlimit(2); see NOTES below.

CONFORMING TO top

       SVr4, 4.4BSD (the getdtablesize() function first appeared in 4.2BSD).  It
       is not specified in POSIX.1-2001; portable applications should employ
       sysconf(_SC_OPEN_MAX) instead of this call.

NOTES top

       getdtablesize() is implemented as a libc library function.  The glibc
       version calls getrlimit(2) and returns the current RLIMIT_NOFILE limit, or
       OPEN_MAX when that fails.  The libc4 and libc5 versions return OPEN_MAX
       (set to 256 since Linux 0.98.4).

SEE ALSO top

       close(2), dup(2), getrlimit(2), open(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                    GETDTABLESIZE(2)


getgid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETGID(2)                    Linux Programmer's Manual                   GETGID(2)

NAME top

       getgid, getegid - get group identity

SYNOPSIS top

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

       gid_t getgid(void);
       gid_t getegid(void);

DESCRIPTION top

       getgid() returns the real group ID of the calling process.

       getegid() returns the effective group ID of the calling process.

ERRORS top

       These functions are always successful.

CONFORMING TO top

       POSIX.1-2001, 4.3BSD.

NOTES top

       The original Linux getgid() and getegid() system calls supported only
       16-bit group IDs.  Subsequently, Linux 2.4 added getgid32() and
       getegid32(), supporting 32-bit IDs.  The glibc getgid() and getegid()
       wrapper functions transparently deal with the variations across kernel
       versions.

SEE ALSO top

       getresgid(2), setgid(2), setregid(2), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                           GETGID(2)


getenv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | VERSIONS | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETENV(3)                    Linux Programmer's Manual                   GETENV(3)

NAME top

       getenv, secure_getenv - get an environment variable

SYNOPSIS top

       #include <stdlib.h>

       char *getenv(const char *name);

       char *secure_getenv(const char *name);

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

       secure_getenv(): _GNU_SOURCE

DESCRIPTION top

       The getenv() function searches the environment list to find the environment
       variable name, and returns a pointer to the corresponding value string.

       The GNU-specific secure_getenv() function is just like getenv() except that
       it returns NULL in cases where "secure execution" is required.  Secure
       execution is required if one of the following conditions was true when the
       program run by the calling process was loaded:

       *  the process's effective user ID did not match its real user ID or the
          process's effective group ID did not match its real group ID (typically
          this is the result of executing a set-user-ID or set-group-ID program);

       *  the effective capability bit was set on the executable file; or

       *  the process has a nonempty permitted capability set.

       Secure execution may also required if triggered by some Linux security
       modules.

       The secure_getenv() function is intended for use in general-purpose
       libraries to avoid vulnerabilities that could occur if set-user-ID or set-
       group-ID programs accidentally trusted the environment.

RETURN VALUE top

       The getenv() function returns a pointer to the value in the environment, or
       NULL if there is no match.

CONFORMING TO top

       getenv(): SVr4, POSIX.1-2001, 4.3BSD, C89, C99.

       secure_getenv() is a GNU extension.

VERSIONS top

       secure_getenv() first appeared in glibc 2.17.

NOTES top

       The strings in the environment list are of the form name=value.

       As typically implemented, getenv() returns a pointer to a string within the
       environment list.  The caller must take care not to modify this string,
       since that would change the environment of the process.

       The implementation of getenv() is not required to be reentrant.  The string
       pointed to by the return value of getenv() may be statically allocated, and
       can be modified by a subsequent call to getenv(), putenv(3), setenv(3), or
       unsetenv(3).

       The "secure execution" mode of secure_getenv() is controlled by the
       AT_SECURE flag contained in the auxiliary vector passed from the kernel to
       user space.

SEE ALSO top

       clearenv(3), getauxval(3), putenv(3), setenv(3), unsetenv(3),
       capabilities(7), environ(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-14                           GETENV(3)


getuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | CONFORMING TO | NOTES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETUID(2)                    Linux Programmer's Manual                   GETUID(2)

NAME top

       getuid, geteuid - get user identity

SYNOPSIS top

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

       uid_t getuid(void);
       uid_t geteuid(void);

DESCRIPTION top

       getuid() returns the real user ID of the calling process.

       geteuid() returns the effective user ID of the calling process.

ERRORS top

       These functions are always successful.

CONFORMING TO top

       POSIX.1-2001, 4.3BSD.

NOTES top

History

       In UNIX V6 the getuid() call returned (euid << 8) + uid.  UNIX V7
       introduced separate calls getuid() and geteuid().

NOTES          top
       The original Linux getuid() and geteuid() system calls supported only
       16-bit user IDs.  Subsequently, Linux 2.4 added getuid32() and geteuid32(),
       supporting 32-bit IDs.  The glibc getuid() and geteuid() wrapper functions
       transparently deal with the variations across kernel versions.

SEE ALSO          top
       getresuid(2), setreuid(2), setuid(2), credentials(7)

COLOPHON          top
       This page is part of release 3.45 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                               2010-11-22                           GETUID(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


getgrnam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETGRNAM(3)                  Linux Programmer's Manual                 GETGRNAM(3)

NAME top

       getgrnam, getgrnam_r, getgrgid, getgrgid_r - get group file entry

SYNOPSIS top

       #include <sys/types.h>
       #include <grp.h>

       struct group *getgrnam(const char *name);

       struct group *getgrgid(gid_t gid);

       int getgrnam_r(const char *name, struct group *grp,
                 char *buf, size_t buflen, struct group **result);

       int getgrgid_r(gid_t gid, struct group *grp,
                 char *buf, size_t buflen, struct group **result);

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

       getgrnam_r(), getgrgid_r():
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||
           _POSIX_SOURCE

DESCRIPTION top

       The getgrnam() function returns a pointer to a structure containing the
       broken-out fields of the record in the group database (e.g., the local
       group file /etc/group, NIS, and LDAP) that matches the group name name.

       The getgrgid() function returns a pointer to a structure containing the
       broken-out fields of the record in the group database that matches the
       group ID gid.

       The group structure is defined in <grp.h> as follows:

           struct group {
               char   *gr_name;       /* group name */
               char   *gr_passwd;     /* group password */
               gid_t   gr_gid;        /* group ID */
               char  **gr_mem;        /* group members */
           };

       For more information about the fields of this structure, see group(5).

       The getgrnam_r() and getgrgid_r() functions obtain the same information as
       getgrnam() and getgrgid(), but store the retrieved group structure in the
       space pointed to by grp.  The string fields pointed to by the members of
       the group structure are stored in the buffer buf of size buflen.  A pointer
       to the result (in case of success) or NULL (in case no entry was found or
       an error occurred) is stored in *result.

       The call

           sysconf(_SC_GETGR_R_SIZE_MAX)

       returns either -1, without changing errno, or an initial suggested size for
       buf.  (If this size is too small, the call fails with ERANGE, in which case
       the caller can retry with a larger buffer.)

RETURN VALUE top

       The getgrnam() and getgrgid() functions return a pointer to a group
       structure, or NULL if the matching entry is not found or an error occurs.
       If an error occurs, errno is set appropriately.  If one wants to check
       errno after the call, it should be set to zero before the call.

       The return value may point to a static area, and may be overwritten by
       subsequent calls to getgrent(3), getgrgid(), or getgrnam().  (Do not pass
       the returned pointer to free(3).)

       On success, getgrnam_r() and getgrgid_r() return zero, and set *result to
       grp.  If no matching group record was found, these functions return 0 and
       store NULL in *result.  In case of error, an error number is returned, and
       NULL is stored in *result.

ERRORS top

       0 or ENOENT or ESRCH or EBADF or EPERM or ...
              The given name or gid was not found.

       EINTR  A signal was caught.

       EIO    I/O error.

       EMFILE The maximum number (OPEN_MAX) of files was open already in the
              calling process.

       ENFILE The maximum number of files was open already in the system.

       ENOMEM Insufficient memory to allocate group structure.

       ERANGE Insufficient buffer space supplied.

FILES top

       /etc/group
              local group database file

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       The formulation given above under "RETURN VALUE" is from POSIX.1-2001.  It
       does not call "not found" an error, hence does not specify what value errno
       might have in this situation.  But that makes it impossible to recognize
       errors.  One might argue that according to POSIX errno should be left
       unchanged if an entry is not found.  Experiments on various UNIX-like
       systems shows that lots of different values occur in this situation: 0,
       ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others.

SEE ALSO top

       endgrent(3), fgetgrent(3), getgrent(3), getpwnam(3), setgrent(3), group(5)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-23                         GETGRNAM(3)


getgrouplist(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETGROUPLIST(3)              Linux Programmer's Manual             GETGROUPLIST(3)

NAME top

       getgrouplist - get list of groups to which a user belongs

SYNOPSIS top

       #include <grp.h>

       int getgrouplist(const char *user, gid_t group,
                        gid_t *groups, int *ngroups);

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

       getgrouplist(): _BSD_SOURCE

DESCRIPTION top

       The getgrouplist() function scans the group database (see group(5)) to
       obtain the list of groups that user belongs to.  Up to *ngroups of these
       groups are returned in the array groups.

       If it was not among the groups defined for user in the group database, then
       group is included in the list of groups returned by getgrouplist();
       typically this argument is specified as the group ID from the password
       record for user.

       The ngroups argument is a value-result argument: on return it always
       contains the number of groups found for user, including group; this value
       may be greater than the number of groups stored in groups.

RETURN VALUE top

       If the number of groups of which user is a member is less than or equal to
       *ngroups, then the value *ngroups is returned.

       If the user is a member of more than *ngroups groups, then getgrouplist()
       returns -1.  In this case the value returned in *ngroups can be used to
       resize the buffer passed to a further call getgrouplist().

VERSIONS top

       This function is present since glibc 2.2.4.

CONFORMING TO top

       This function is nonstandard; it appears on most BSDs.

BUGS top

       In glibc versions before 2.3.3, the implementation of this function
       contains a buffer-overrun bug: it returns the complete list of groups for
       user in the array groups, even when the number of groups exceeds *ngroups.

EXAMPLE top

       The program below displays the group list for the user named in its first
       command-line argument.  The second command-line argument specifies the
       ngroups value to be supplied to getgrouplist().  The following shell
       session shows examples of the use of this program:

           $ ./a.out cecilia 0
           getgrouplist() returned -1; ngroups = 3
           $ ./a.out cecilia 3
           ngroups = 3
           16 (dialout)
           33 (video)
           100 (users)

Program source

       #include <stdio.h>
       #include <stdlib.h>
       #include <grp.h>
       #include <pwd.h>

       int
       main(int argc, char *argv[])
       {
           int j, ngroups;
           gid_t *groups;
           struct passwd *pw;
           struct group *gr;

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

           ngroups = atoi(argv[2]);

           groups = malloc(ngroups * sizeof (gid_t));
           if (groups == NULL) {
               perror("malloc");
               exit(EXIT_FAILURE);
           }

           /* Fetch passwd structure (contains first group ID for user) */

           pw = getpwnam(argv[1]);
           if (pw == NULL) {
               perror("getpwnam");
               exit(EXIT_SUCCESS);
           }

           /* Retrieve group list */

           if (getgrouplist(argv[1], pw->pw_gid, groups, &ngroups) == -1) {
               fprintf(stderr, "getgrouplist() returned -1; ngroups = %d\n",
                       ngroups);
            exit(EXIT_FAILURE);
           }

           /* Display list of retrieved groups, along with group names */

           fprintf(stderr, "ngroups = %d\n", ngroups);
           for (j = 0; j < ngroups; j++) {
               printf("%d", groups[j]);
               gr = getgrgid(groups[j]);
               if (gr != NULL)
                   printf(" (%s)", gr->gr_name);
               printf("\n");
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getgroups(2), setgroups(2), getgrent(3), group(5), passwd(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-07-03                     GETGROUPLIST(3)


getgroups(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETGROUPS(2)                 Linux Programmer's Manual                GETGROUPS(2)

NAME top

       getgroups, setgroups - get/set list of supplementary group IDs

SYNOPSIS top

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

       int getgroups(int size, gid_t list[]);

       #include <grp.h>

       int setgroups(size_t size, const gid_t *list);

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

       setgroups(): _BSD_SOURCE

DESCRIPTION top

       getgroups() returns the supplementary group IDs of the calling process in
       list.  The argument size should be set to the maximum number of items that
       can be stored in the buffer pointed to by list.  If the calling process is
       a member of more than size supplementary groups, then an error results.  It
       is unspecified whether the effective group ID of the calling process is
       included in the returned list.  (Thus, an application should also call
       getegid(2) and add or remove the resulting value.)

       If size is zero, list is not modified, but the total number of
       supplementary group IDs for the process is returned.  This allows the
       caller to determine the size of a dynamically allocated list to be used in
       a further call to getgroups().

       setgroups() sets the supplementary group IDs for the calling process.
       Appropriate privileges (Linux: the CAP_SETGID capability) are required.
       The size argument specifies the number of supplementary group IDs in the
       buffer pointed to by list.

RETURN VALUE top

       On success, getgroups() returns the number of supplementary group IDs.  On
       error, -1 is returned, and errno is set appropriately.

       On success, setgroups() returns 0.  On error, -1 is returned, and errno is
       set appropriately.

ERRORS top

       EFAULT list has an invalid address.

       getgroups() can additionally fail with the following error:

       EINVAL size is less than the number of supplementary group IDs, but is not
              zero.

       setgroups() can additionally fail with the following errors:

       EINVAL size is greater than NGROUPS_MAX (32 before Linux 2.6.4; 65536 since
              Linux 2.6.4).

       ENOMEM Out of memory.

       EPERM  The calling process has insufficient privilege.

CONFORMING TO top

       SVr4, 4.3BSD.  The getgroups() function is in POSIX.1-2001.  Since
       setgroups() requires privilege, it is not covered by POSIX.1-2001.

NOTES top

       A process can have up to NGROUPS_MAX supplementary group IDs in addition to
       the effective group ID.  The set of supplementary group IDs is inherited
       from the parent process, and preserved across an execve(2).

       The maximum number of supplementary group IDs can be found using
       sysconf(3):

           long ngroups_max;
           ngroups_max = sysconf(_SC_NGROUPS_MAX);

       The maximum return value of getgroups() cannot be larger than one more than
       this value.

       The original Linux getgroups() system call supported only 16-bit group IDs.
       Subsequently, Linux 2.4 added getgroups32(), supporting 32-bit IDs.  The
       glibc getgroups() wrapper function transparently deals with the variation
       across kernel versions.

SEE ALSO top

       getgid(2), setgid(2), getgrouplist(3), initgroups(3), capabilities(7),
       credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                        GETGROUPS(2)


gethostid(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETHOSTID(3)                 Linux Programmer's Manual                GETHOSTID(3)

NAME top

       gethostid, sethostid - get or set the unique identifier of the current host

SYNOPSIS top

       #include <unistd.h>

       long gethostid(void);
       int sethostid(long hostid);

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

       gethostid():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
       sethostid():
           _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       gethostid() and sethostid() respectively get or set a unique 32-bit
       identifier for the current machine.  The 32-bit identifier is intended to
       be unique among all UNIX systems in existence.  This normally resembles the
       Internet address for the local machine, as returned by gethostbyname(3),
       and thus usually never needs to be set.

       The sethostid() call is restricted to the superuser.

RETURN VALUE top

       gethostid() returns the 32-bit identifier for the current host as set by
       sethostid().

       On success, sethostid() returns 0; on error, -1 is returned, and errno is
       set to indicate the error.

ERRORS top

       sethostid() can fail with the following errors:

       EACCES The caller did not have permission to write to the file used to
              store the host ID.

       EPERM  The calling process's effective user or group ID is not the same as
              its corresponding real ID.

CONFORMING TO top

       4.2BSD; these functions were dropped in 4.4BSD.  SVr4 includes gethostid()
       but not sethostid().  POSIX.1-2001 specifies gethostid() but not
       sethostid().

NOTES top

       In the glibc implementation, the hostid is stored in the file /etc/hostid.
       (In glibc versions before 2.2, the file /var/adm/hostid was used.)

       In the glibc implementation, if gethostid() cannot open the file containing
       the host ID, then it obtains the hostname using gethostname(2), passes that
       hostname to gethostbyname_r(3) in order to obtain the host's IPv4 address,
       and returns a value obtained by bit-twiddling the IPv4 address.  (This
       value may not be unique.)

BUGS top

       It is impossible to ensure that the identifier is globally unique.

SEE ALSO top

       hostid(1), gethostbyname(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                        GETHOSTID(3)


gethostname(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETHOSTNAME(2)               Linux Programmer's Manual              GETHOSTNAME(2)

NAME top

       gethostname, sethostname - get/set hostname

SYNOPSIS top

       #include <unistd.h>

       int gethostname(char *name, size_t len);
       int sethostname(const char *name, size_t len);

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

       gethostname():
           Since glibc 2.12: _BSD_SOURCE || _XOPEN_SOURCE >= 500
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200112L
       sethostname():
           _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       These system calls are used to access or to change the hostname of the
       current processor.

       sethostname() sets the hostname to the value given in the character array
       name.  The len argument specifies the number of bytes in name.  (Thus, name
       does not require a terminating null byte.)

       gethostname() returns the null-terminated hostname in the character array
       name, which has a length of len bytes.  If the null-terminated hostname is
       too large to fit, then the name is truncated, and no error is returned (but
       see NOTES below).  POSIX.1-2001 says that if such truncation occurs, then
       it is unspecified whether the returned buffer includes a terminating null
       byte.

RETURN VALUE top

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

ERRORS top

       EFAULT name is an invalid address.

       EINVAL len is negative or, for sethostname(), len is larger than the
              maximum allowed size.

       ENAMETOOLONG
              (glibc gethostname()) len is smaller than the actual size.  (Before
              version 2.1, glibc uses EINVAL for this case.)

       EPERM  For sethostname(), the caller did not have the CAP_SYS_ADMIN
              capability.

CONFORMING TO top

       SVr4, 4.4BSD  (these interfaces first appeared in 4.2BSD).  POSIX.1-2001
       specifies gethostname() but not sethostname().

NOTES top

       SUSv2 guarantees that "Host names are limited to 255 bytes".  POSIX.1-2001
       guarantees that "Host names (not including the terminating null byte) are
       limited to HOST_NAME_MAX bytes".  On Linux, HOST_NAME_MAX is defined with
       the value 64, which has been the limit since Linux 1.0 (earlier kernels
       imposed a limit of 8 bytes).

Glibc Notes

       The GNU C library does not employ the gethostname() system call; instead,
       it implements gethostname() as a library function that calls uname(2) and
       copies up to len bytes from the returned nodename field into name.  Having
       performed the copy, the function then checks if the length of the nodename
       was greater than or equal to len, and if it is, then the function returns
       -1 with errno set to ENAMETOOLONG; in this case, a terminating null byte is
       not included in the returned name.

       Versions of glibc before 2.2 handle the case where the length of the
       nodename was greater than or equal to len differently: nothing is copied
       into name and the function returns -1 with errno set to ENAMETOOLONG.

SEE ALSO top

       getdomainname(2), setdomainname(2), uname(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                      GETHOSTNAME(2)


getitimer(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETITIMER(2)                 Linux Programmer's Manual                GETITIMER(2)

NAME top

       getitimer, setitimer - get or set value of an interval timer

SYNOPSIS top

       #include <sys/time.h>

       int getitimer(int which, struct itimerval *curr_value);
       int setitimer(int which, const struct itimerval *new_value,
                     struct itimerval *old_value);

DESCRIPTION top

       The system provides each process with three interval timers, each
       decrementing in a distinct time domain.  When any timer expires, a signal
       is sent to the process, and the timer (potentially) restarts.

       ITIMER_REAL    decrements in real time, and delivers SIGALRM upon
                      expiration.

       ITIMER_VIRTUAL decrements only when the process is executing, and delivers
                      SIGVTALRM upon expiration.

       ITIMER_PROF    decrements both when the process executes and when the
                      system is executing on behalf of the process.  Coupled with
                      ITIMER_VIRTUAL, this timer is usually used to profile the
                      time spent by the application in user and kernel space.
                      SIGPROF is delivered upon expiration.

       Timer values are defined by the following structures:

           struct itimerval {
               struct timeval it_interval; /* next value */
               struct timeval it_value;    /* current value */
           };

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

       The function getitimer() fills the structure pointed to by curr_value with
       the current setting for the timer specified by which (one of ITIMER_REAL,
       ITIMER_VIRTUAL, or ITIMER_PROF).  The element it_value is set to the amount
       of time remaining on the timer, or zero if the timer is disabled.
       Similarly, it_interval is set to the reset value.

       The function setitimer() sets the specified timer to the value in
       new_value.  If old_value is non-NULL, the old value of the timer is stored
       there.

       Timers decrement from it_value to zero, generate a signal, and reset to
       it_interval.  A timer which is set to zero (it_value is zero or the timer
       expires and it_interval is zero) stops.

       Both tv_sec and tv_usec are significant in determining the duration of a
       timer.

       Timers will never expire before the requested time, but may expire some
       (short) time afterward, which depends on the system timer resolution and on
       the system load; see time(7).  (But see BUGS below.)  Upon expiration, a
       signal will be generated and the timer reset.  If the timer expires while
       the process is active (always true for ITIMER_VIRTUAL) the signal will be
       delivered immediately when generated.  Otherwise the delivery will be
       offset by a small time dependent on the system loading.

RETURN VALUE top

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

ERRORS top

       EFAULT new_value, old_value, or curr_value is not valid a pointer.

       EINVAL which is not one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF; or
              (since Linux 2.6.22) one of the tv_usec fields in the structure
              pointed to by new_value contains a value outside the range 0 to
              999999.

CONFORMING TO top

       POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
       POSIX.1-2008 marks getitimer() and setitimer() obsolete, recommending the
       use of the POSIX timers API (timer_gettime(2), timer_settime(2), etc.)
       instead.

NOTES top

       A child created via fork(2) does not inherit its parent's interval timers.
       Interval timers are preserved across an execve(2).

       POSIX.1 leaves the interaction between setitimer() and the three interfaces
       alarm(2), sleep(3), and usleep(3) unspecified.

       The standards are silent on the meaning of the call:

           setitimer(which, NULL, &old_value);

       Many systems (Solaris, the BSDs, and perhaps others) treat this as
       equivalent to:

           getitimer(which, &old_value);

       In Linux, this is treated as being equivalent to a call in which the
       new_value fields are zero; that is, the timer is disabled.  Don't use this
       Linux misfeature: it is nonportable and unnecessary.

BUGS top

       The generation and delivery of a signal are distinct, and only one instance
       of each of the signals listed above may be pending for a process.  Under
       very heavy loading, an ITIMER_REAL timer may expire before the signal from
       a previous expiration has been delivered.  The second signal in such an
       event will be lost.

       On Linux kernels before 2.6.16, timer values are represented in jiffies.
       If a request is made set a timer with a value whose jiffies representation
       exceeds MAX_SEC_IN_JIFFIES (defined in include/linux/jiffies.h), then the
       timer is silently truncated to this ceiling value.  On Linux/i386 (where,
       since Linux 2.6.13, the default jiffy is 0.004 seconds), this means that
       the ceiling value for a timer is approximately 99.42 days.  Since Linux
       2.6.16, the kernel uses a different internal representation for times, and
       this ceiling is removed.

       On certain systems (including i386), Linux kernels before version 2.6.12
       have a bug which will produce premature timer expirations of up to one
       jiffy under some circumstances.  This bug is fixed in kernel 2.6.12.

       POSIX.1-2001 says that setitimer() should fail if a tv_usec value is
       specified that is outside of the range 0 to 999999.  However, in kernels up
       to and including 2.6.21, Linux does not give an error, but instead silently
       adjusts the corresponding seconds value for the timer.  From kernel 2.6.22
       onward, this nonconformance has been repaired: an improper tv_usec value
       results in an EINVAL error.

SEE ALSO top

       gettimeofday(2), sigaction(2), signal(2), timer_create(2),
       timerfd_create(2), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-01                        GETITIMER(2)


getloadavg(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETLOADAVG(3)                Linux Programmer's Manual               GETLOADAVG(3)

NAME top

       getloadavg - get system load averages

SYNOPSIS top

       #define _BSD_SOURCE         /* See feature_test_macros(7) */
       #include <stdlib.h>

       int getloadavg(double loadavg[], int nelem);

DESCRIPTION top

       The getloadavg() function returns the number of processes in the system run
       queue averaged over various periods of time.  Up to nelem samples are
       retrieved and assigned to successive elements of loadavg[].  The system
       imposes a maximum of 3 samples, representing averages over the last 1, 5,
       and 15 minutes, respectively.

RETURN VALUE top

       If the load average was unobtainable, -1 is returned; otherwise, the number
       of samples actually retrieved is returned.

VERSIONS top

       This function is available in glibc since version 2.2.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs and Solaris.

SEE ALSO top

       uptime(1), proc(5)

COLOPHON top

       This page is part of release 3.45 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-12-08                       GETLOADAVG(3)


getnameinfo(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETNAMEINFO(3)               Linux Programmer's Manual              GETNAMEINFO(3)

NAME top

       getnameinfo - address-to-name translation in protocol-independent manner

SYNOPSIS top

       #include <sys/socket.h>
       #include <netdb.h>

       int getnameinfo(const struct sockaddr *sa, socklen_t salen,
                       char *host, size_t hostlen,
                       char *serv, size_t servlen, int flags);

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

       getnameinfo(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The getnameinfo() function is the inverse of getaddrinfo(3): it converts a
       socket address to a corresponding host and service, in a protocol-
       independent manner.  It combines the functionality of gethostbyaddr(3) and
       getservbyport(3), but unlike those functions, getaddrinfo(3) is reentrant
       and allows programs to eliminate IPv4-versus-IPv6 dependencies.

       The sa argument is a pointer to a generic socket address structure (of type
       sockaddr_in or sockaddr_in6) of size salen that holds the input IP address
       and port number.  The arguments host and serv are pointers to caller-
       allocated buffers (of size hostlen and servlen respectively) into which
       getnameinfo() places null-terminated strings containing the host and
       service names respectively.

       The caller can specify that no hostname (or no service name) is required by
       providing a NULL host (or serv) argument or a zero hostlen (or servlen)
       argument.  However, at least one of hostname or service name must be
       requested.

       The flags argument modifies the behavior of getnameinfo() as follows:

       NI_NAMEREQD
              If set, then an error is returned if the hostname cannot be
              determined.

       NI_DGRAM
              If set, then the service is datagram (UDP) based rather than stream
              (TCP) based.  This is required for the few ports (512-514) that have
              different services for UDP and TCP.

       NI_NOFQDN
              If set, return only the hostname part of the fully qualified domain
              name for local hosts.

       NI_NUMERICHOST
              If set, then the numeric form of the hostname is returned.  (When
              not set, this will still happen in case the node's name cannot be
              determined.)

       NI_NUMERICSERV
              If set, then the numeric form of the service address is returned.
              (When not set, this will still happen in case the service's name
              cannot be determined.)

Extensions to getaddrinfo() for Internationalized Domain Names

       Starting with glibc 2.3.4, getnameinfo() has been extended to selectively
       allow hostnames to be transparently converted to and from the
       Internationalized Domain Name (IDN) format (see RFC 3490,
       Internationalizing Domain Names in Applications (IDNA)).  Three new flags
       are defined:

       NI_IDN If this flag is used, then the name found in the lookup process is
              converted from IDN format to the locale's encoding if necessary.
              ASCII-only names are not affected by the conversion, which makes
              this flag usable in existing programs and environments.

       NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
              Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
              unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES (check
              output to make sure it is a STD3 conforming hostname) flags
              respectively to be used in the IDNA handling.

RETURN VALUE top

       On success 0 is returned, and node and service names, if requested, are
       filled with null-terminated strings, possibly truncated to fit the
       specified buffer lengths.  On error one of the following nonzero error
       codes is returned:

       EAI_AGAIN
              The name could not be resolved at this time.  Try again later.

       EAI_BADFLAGS
              The flags argument has an invalid value.

       EAI_FAIL
              A nonrecoverable error occurred.

       EAI_FAMILY
              The address family was not recognized, or the address length was
              invalid for the specified family.

       EAI_MEMORY
              Out of memory.

       EAI_NONAME
              The name does not resolve for the supplied arguments.  NI_NAMEREQD
              is set and the host's name cannot be located, or neither hostname
              nor service name were requested.

       EAI_OVERFLOW
              The buffer pointed to by host or serv was too small.

       EAI_SYSTEM
              A system error occurred.  The error code can be found in errno.

       The gai_strerror(3) function translates these error codes to a human
       readable string, suitable for error reporting.

FILES top

       /etc/hosts
       /etc/nsswitch.conf
       /etc/resolv.conf

VERSIONS top

       getnameinfo() is provided in glibc since version 2.1.

CONFORMING TO top

       RFC 2553, POSIX.1-2001.

NOTES top

       In order to assist the programmer in choosing reasonable sizes for the
       supplied buffers, <netdb.h> defines the constants

           #define NI_MAXHOST      1025
           #define NI_MAXSERV      32

       Since glibc 2.8, these definitions are exposed only if one of the feature
       test macros _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE is defined.

       The former is the constant MAXDNAME in recent versions of BIND's
       <arpa/nameser.h> header file.  The latter is a guess based on the services
       listed in the current Assigned Numbers RFC.

EXAMPLE top

       The following code tries to get the numeric hostname and service name, for
       a given socket address.  Note that there is no hardcoded reference to a
       particular address family.

           struct sockaddr *sa;    /* input */
           socklen_t len;         /* input */
           char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

           if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
                       sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
               printf("host=%s, serv=%s\n", hbuf, sbuf);

       The following version checks if the socket address has a reverse address
       mapping.

           struct sockaddr *sa;    /* input */
           socklen_t len;         /* input */
           char hbuf[NI_MAXHOST];

           if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
                       NULL, 0, NI_NAMEREQD))
               printf("could not resolve hostname");
           else
               printf("host=%s\n", hbuf);

       An example program using getnameinfo() can be found in getaddrinfo(3).

SEE ALSO top

       accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2),
       getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3),
       inet_ntop(3), hosts(5), services(5), hostname(7), named(8)

       R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Interface
       Extensions for IPv6, RFC 2553, March 1999.

       Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
       Addresses, internet draft, work in progress <ftp://ftp.ietf.org
       /internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt>.

       Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the
       freenix track: 2000 USENIX annual technical conference, June 2000
       <http://www.usenix.org/publications/library/proceedings/usenix2000/freenix
       /metzprotocol.html>.

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-05                      GETNAMEINFO(3)


getnetent_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETNETENT_R(3)               Linux Programmer's Manual              GETNETENT_R(3)

NAME top

       getnetent_r, getnetbyname_r, getnetbyaddr_r - get network entry (reentrant)

SYNOPSIS top

       #include <netdb.h>

       int getnetent_r(struct netent *result_buf, char *buf,
                       size_t buflen, struct netent **result,
                       int *h_errnop);

       int getnetbyname_r(const char *name,
                       struct netent *result_buf, char *buf,
                       size_t buflen, struct netent **result,
                       int *h_errnop);

       int getnetbyaddr_r(uint32_t net, int type,
                       struct netent *result_buf, char *buf,
                       size_t buflen, struct netent **result,
                       int *h_errnop);

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

       getnetent_r(), getnetbyname_r(), getnetbyaddr_r():
           _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The getnetent_r(), getnetbyname_r(), and getnetbyaddr_r() functions are the
       reentrant equivalents of, respectively, getnetent(3), getnetbyname(3), and
       getnetbynumber(3).  They differ in the way that the netent structure is
       returned, and in the function calling signature and return value.  This
       manual page describes just the differences from the nonreentrant functions.

       Instead of returning a pointer to a statically allocated netent structure
       as the function result, these functions copy the structure into the
       location pointed to by result_buf.

       The buf array is used to store the string fields pointed to by the returned
       netent structure.  (The nonreentrant functions allocate these strings in
       static storage.)  The size of this array is specified in buflen.  If buf is
       too small, the call fails with the error ERANGE, and the caller must try
       again with a larger buffer.  (A buffer of length 1024 bytes should be
       sufficient for most applications.)

       If the function call successfully obtains a network record, then *result is
       set pointing to result_buf; otherwise, *result is set to NULL.

       The buffer pointed to by h_errnop is used to return the value that would be
       stored in the global variable h_errno by the nonreentrant versions of these
       functions.

RETURN VALUE top

       On success, these functions return 0.  On error, they return one of the
       positive error numbers listed in ERRORS.

       On error, record not found (getnetbyname_r(), getnetbyaddr_r()), or end of
       input (getnetent_r()) result is set to NULL.

ERRORS top

       ENOENT (getnetent_r()) No more records in database.

       ERANGE buf is too small.  Try again with a larger buffer (and increased
              buflen).

CONFORMING TO top

       These functions are GNU extensions.  Functions with similar names exist on
       some other systems, though typically with different calling signatures.

SEE ALSO top

       getnetent(3), networks(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                      GETNETENT_R(3)


getopt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ENVIRONMENT | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETOPT(3)                    Linux Programmer's Manual                   GETOPT(3)

NAME top

       getopt,  getopt_long,  getopt_long_only,  optarg,  optind, opterr, optopt -
       Parse command-line options

SYNOPSIS top

       #include <unistd.h>

       int getopt(int argc, char * const argv[],
                  const char *optstring);

       extern char *optarg;
       extern int optind, opterr, optopt;

       #include <getopt.h>

       int getopt_long(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

       int getopt_long_only(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

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

       getopt(): _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
       getopt_long(), getopt_long_only(): _GNU_SOURCE

DESCRIPTION top

       The getopt() function parses the command-line arguments.  Its arguments
       argc and argv are the argument count and array as passed to the main()
       function on program invocation.  An element of argv that starts with '-'
       (and is not exactly "-" or "--") is an option element.  The characters of
       this element (aside from the initial '-') are option characters.  If
       getopt() is called repeatedly, it returns successively each of the option
       characters from each of the option elements.

       The variable optind is the index of the next element to be processed in
       argv.  The system initializes this value to 1.  The caller can reset it to
       1 to restart scanning of the same argv, or when scanning a new argument
       vector.

       If getopt() finds another option character, it returns that character,
       updating the external variable optind and a static variable nextchar so
       that the next call to getopt() can resume the scan with the following
       option character or argv-element.

       If there are no more option characters, getopt() returns -1.  Then optind
       is the index in argv of the first argv-element that is not an option.

       optstring is a string containing the legitimate option characters.  If such
       a character is followed by a colon, the option requires an argument, so
       getopt() places a pointer to the following text in the same argv-element,
       or the text of the following argv-element, in optarg.  Two colons mean an
       option takes an optional arg; if there is text in the current argv-element
       (i.e., in the same word as the option name itself, for example, "-oarg"),
       then it is returned in optarg, otherwise optarg is set to zero.  This is a
       GNU extension.  If optstring contains W followed by a semicolon, then -W
       foo is treated as the long option --foo.  (The -W option is reserved by
       POSIX.2 for implementation extensions.)  This behavior is a GNU extension,
       not available with libraries before glibc 2.

       By default, getopt() permutes the contents of argv as it scans, so that
       eventually all the nonoptions are at the end.  Two other modes are also
       implemented.  If the first character of optstring is '+' or the environment
       variable POSIXLY_CORRECT is set, then option processing stops as soon as a
       nonoption argument is encountered.  If the first character of optstring is
       '-', then each nonoption argv-element is handled as if it were the argument
       of an option with character code 1.  (This is used by programs that were
       written to expect options and other argv-elements in any order and that
       care about the ordering of the two.)  The special argument "--" forces an
       end of option-scanning regardless of the scanning mode.

       If getopt() does not recognize an option character, it prints an error
       message to stderr, stores the character in optopt, and returns '?'.  The
       calling program may prevent the error message by setting opterr to 0.

       If getopt() finds an option character in argv that was not included in
       optstring, or if it detects a missing option argument, it returns '?' and
       sets the external variable optopt to the actual option character.  If the
       first character (following any optional '+' or '-' described above) of
       optstring is a colon (':'), then getopt() returns ':' instead of '?' to
       indicate a missing option argument.  If an error was detected, and the
       first character of optstring is not a colon, and the external variable
       opterr is nonzero (which is the default), getopt() prints an error message.

getopt_long() and getopt_long_only()

       The getopt_long() function works like getopt() except that it also accepts
       long options, started with two dashes.  (If the program accepts only long
       options, then optstring should be specified as an empty string (""), not
       NULL.)  Long option names may be abbreviated if the abbreviation is unique
       or is an exact match for some defined option.  A long option may take a
       parameter, of the form --arg=param or --arg param.

       longopts is a pointer to the first element of an array of struct option
       declared in <getopt.h> as

           struct option {
               const char *name;
               int         has_arg;
               int        *flag;
               int         val;
           };

       The meanings of the different fields are:

       name   is the name of the long option.

       has_arg
              is: no_argument (or 0) if the option does not take an argument;
              required_argument (or 1) if the option requires an argument; or
              optional_argument (or 2) if the option takes an optional argument.

       flag   specifies how results are returned for a long option.  If flag is
              NULL, then getopt_long() returns val.  (For example, the calling
              program may set val to the equivalent short option character.)
              Otherwise, getopt_long() returns 0, and flag points to a variable
              which is set to val if the option is found, but left unchanged if
              the option is not found.

       val    is the value to return, or to load into the variable pointed to by
              flag.

       The last element of the array has to be filled with zeros.

       If longindex is not NULL, it points to a variable which is set to the index
       of the long option relative to longopts.

       getopt_long_only() is like getopt_long(), but '-' as well as "--" can
       indicate a long option.  If an option that starts with '-' (not "--")
       doesn't match a long option, but does match a short option, it is parsed as
       a short option instead.

RETURN VALUE top

       If an option was successfully found, then getopt() returns the option
       character.  If all command-line options have been parsed, then getopt()
       returns -1.  If getopt() encounters an option character that was not in
       optstring, then '?' is returned.  If getopt() encounters an option with a
       missing argument, then the return value depends on the first character in
       optstring: if it is ':', then ':' is returned; otherwise '?' is returned.

       getopt_long() and getopt_long_only() also return the option character when
       a short option is recognized.  For a long option, they return val if flag
       is NULL, and 0 otherwise.  Error and -1 returns are the same as for
       getopt(), plus '?' for an ambiguous match or an extraneous parameter.

ENVIRONMENT top

       POSIXLY_CORRECT
              If this is set, then option processing stops as soon as a nonoption
              argument is encountered.

       _<PID>_GNU_nonoption_argv_flags_
              This variable was used by bash(1) 2.0 to communicate to glibc which
              arguments are the results of wildcard expansion and so should not be
              considered as options.  This behavior was removed in bash(1) version
              2.01, but the support remains in glibc.

CONFORMING TO top

       getopt():
              POSIX.2 and POSIX.1-2001, provided the environment variable
              POSIXLY_CORRECT is set.  Otherwise, the elements of argv aren't
              really const, because we permute them.  We pretend they're const in
              the prototype to be compatible with other systems.

              The use of '+' and '-' in optstring is a GNU extension.

              On some older implementations, getopt() was declared in <stdio.h>.
              SUSv1 permitted the declaration to appear in either <unistd.h> or
              <stdio.h>.  POSIX.1-2001 marked the use of <stdio.h> for this
              purpose as LEGACY.  POSIX.1-2001 does not allow the declaration to
              appear in <stdio.h>.

       getopt_long() and getopt_long_only():
              These functions are GNU extensions.

NOTES top

       A program that scans multiple argument vectors, or rescans the same vector
       more than once, and wants to make use of GNU extensions such as '+' and '-'
       at the start of optstring, or changes the value of POSIXLY_CORRECT between
       scans, must reinitialize getopt() by resetting optind to 0, rather than the
       traditional value of 1.  (Resetting to 0 forces the invocation of an
       internal initialization routine that rechecks POSIXLY_CORRECT and checks
       for GNU extensions in optstring.)

BUGS top

       The POSIX.2 specification of getopt() has a technical error described in
       POSIX.2 Interpretation 150.  The GNU implementation (and probably all other
       implementations) implements the correct behavior rather than that
       specified.

EXAMPLE top

       The following trivial example program uses getopt() to handle two program
       options: -n, with no associated value; and -t val, which expects an
       associated value.

       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           int flags, opt;
           int nsecs, tfnd;

           nsecs = 0;
           tfnd = 0;
           flags = 0;
           while ((opt = getopt(argc, argv, "nt:")) != -1) {
               switch (opt) {
               case 'n':
                   flags = 1;
                   break;
               case 't':
                   nsecs = atoi(optarg);
                   tfnd = 1;
                   break;
               default: /* '?' */
                   fprintf(stderr, "Usage: %s [-t nsecs] [-n] name\n",
                           argv[0]);
                   exit(EXIT_FAILURE);
               }
           }

           printf("flags=%d; tfnd=%d; optind=%d\n", flags, tfnd, optind);

           if (optind >= argc) {
               fprintf(stderr, "Expected argument after options\n");
               exit(EXIT_FAILURE);
           }

           printf("name argument = %s\n", argv[optind]);

           /* Other code omitted */

           exit(EXIT_SUCCESS);
       }

       The following example program illustrates the use of getopt_long() with
       most of its features.

       #include <stdio.h>     /* for printf */
       #include <stdlib.h>    /* for exit */
       #include <getopt.h>

       int
       main(int argc, char **argv)
       {
           int c;
           int digit_optind = 0;

           while (1) {
               int this_option_optind = optind ? optind : 1;
               int option_index = 0;
               static struct option long_options[] = {
                   {"add",     required_argument, 0,  0 },
                   {"append",  no_argument,       0,  0 },
                   {"delete",  required_argument, 0,  0 },
                   {"verbose", no_argument,       0,  0 },
                   {"create",  required_argument, 0, 'c'},
                   {"file",    required_argument, 0,  0 },
                   {0,         0,                 0,  0 }
               };

               c = getopt_long(argc, argv, "abc:d:012",
                        long_options, &option_index);
               if (c == -1)
                   break;

               switch (c) {
               case 0:
                   printf("option %s", long_options[option_index].name);
                   if (optarg)
                       printf(" with arg %s", optarg);
                   printf("\n");
                   break;

               case '0':
               case '1':
               case '2':
                   if (digit_optind != 0 && digit_optind != this_option_optind)
                     printf("digits occur in two different argv-elements.\n");
                   digit_optind = this_option_optind;
                   printf("option %c\n", c);
                   break;

               case 'a':
                   printf("option a\n");
                   break;

               case 'b':
                   printf("option b\n");
                   break;

               case 'c':
                   printf("option c with value '%s'\n", optarg);
                   break;

               case 'd':
                   printf("option d with value '%s'\n", optarg);
                   break;

               case '?':
                   break;

               default:
                   printf("?? getopt returned character code 0%o ??\n", c);
               }
           }

           if (optind < argc) {
               printf("non-option ARGV-elements: ");
               while (optind < argc)
                   printf("%s ", argv[optind++]);
               printf("\n");
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getsubopt(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-11-01                           GETOPT(3)


getpagesize(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETPAGESIZE(2)               Linux Programmer's Manual              GETPAGESIZE(2)

NAME top

       getpagesize - get memory page size

SYNOPSIS top

       #include <unistd.h>

       int getpagesize(void);

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

       getpagesize():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The function getpagesize() returns the number of bytes in a memory page,
       where "page" is a fixed-length block, the unit for memory allocation and
       file mapping performed by mmap(2).

CONFORMING TO top

       SVr4, 4.4BSD, SUSv2.  In SUSv2 the getpagesize() call is labeled LEGACY,
       and in POSIX.1-2001 it has been dropped; HP-UX does not have this call.

NOTES top

       Portable applications should employ sysconf(_SC_PAGESIZE) instead of
       getpagesize():

           #include <unistd.h>
           long sz = sysconf(_SC_PAGESIZE);

       (Most systems allow the synonym _SC_PAGE_SIZE for _SC_PAGESIZE.)

       Whether getpagesize() is present as a Linux system call depends on the
       architecture.  If it is, it returns the kernel symbol PAGE_SIZE, whose
       value depends on the architecture and machine model.  Generally, one uses
       binaries that are dependent on the architecture but not on the machine
       model, in order to have a single binary distribution per architecture.
       This means that a user program should not find PAGE_SIZE at compile time
       from a header file, but use an actual system call, at least for those
       architectures (like sun4) where this dependency exists.  Here libc4, libc5,
       glibc 2.0 fail because their getpagesize() returns a statically derived
       value, and does not use a system call.  Things are OK in glibc 2.1.

SEE ALSO top

       mmap(2), sysconf(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-16                      GETPAGESIZE(2)


getpass(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETPASS(3)                   Linux Programmer's Manual                  GETPASS(3)

NAME top

       getpass - get a password

SYNOPSIS top

       #include <unistd.h>

       char *getpass( const char *prompt);

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

       getpass():
           Since glibc 2.2.2:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.2.2: none

DESCRIPTION top

       This function is obsolete.  Do not use it.

       The getpass() function opens /dev/tty (the controlling terminal of the
       process), outputs the string prompt, turns off echoing, reads one line (the
       "password"), restores the terminal state and closes /dev/tty again.

RETURN VALUE top

       The function getpass() returns a pointer to a static buffer containing (the
       first PASS_MAX bytes of) the password without the trailing newline,
       terminated by a null byte ('\0').  This buffer may be overwritten by a
       following call.  On error, the terminal state is restored, errno is set
       appropriately, and NULL is returned.

ERRORS top

       The function may fail if

       ENXIO  The process does not have a controlling terminal.

FILES top

       /dev/tty

CONFORMING TO top

       Present in SUSv2, but marked LEGACY.  Removed in POSIX.1-2001.

NOTES top

       For libc4 and libc5, the prompt is not written to /dev/tty but to stderr.
       Moreover, if /dev/tty cannot be opened, the password is read from stdin.
       The static buffer has length 128 so that only the first 127 bytes of the
       password are returned.  While reading the password, signal generation
       (SIGINT, SIGQUIT, SIGSTOP, SIGTSTP) is disabled and the corresponding
       characters (usually control-C, control-\, control-Z and control-Y) are
       transmitted as part of the password.  Since libc 5.4.19 also line editing
       is disabled, so that also backspace and the like will be seen as part of
       the password.

       For glibc2, if /dev/tty cannot be opened, the prompt is written to stderr
       and the password is read from stdin.  There is no limit on the length of
       the password.  Line editing is not disabled.

       According to the SUSv2, the value of PASS_MAX must be defined in <limits.h>
       in case it is smaller than 8, and can in any case be obtained using
       sysconf(_SC_PASS_MAX).  However, POSIX.2 withdraws the constants PASS_MAX
       and _SC_PASS_MAX, and the function getpass().  Libc4 and libc5 have never
       supported PASS_MAX or _SC_PASS_MAX.  Glibc2 accepts _SC_PASS_MAX and
       returns BUFSIZ (e.g., 8192).

BUGS top

       The calling process should zero the password as soon as possible to avoid
       leaving the cleartext password visible in the process's address space.

SEE ALSO top

       crypt(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                          GETPASS(3)


getpeername(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETPEERNAME(2)               Linux Programmer's Manual              GETPEERNAME(2)

NAME top

       getpeername - get name of connected peer socket

SYNOPSIS top

       #include <sys/socket.h>

       int getpeername(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

DESCRIPTION top

       getpeername() returns the address of the peer connected to the socket
       sockfd, in the buffer pointed to by addr.  The addrlen argument should be
       initialized to indicate the amount of space pointed to by addr.  On return
       it contains the actual size of the name returned (in bytes).  The name is
       truncated if the buffer provided is too small.

       The returned address is truncated if the buffer provided is too small; in
       this case, addrlen will return a value greater than was supplied to the
       call.

RETURN VALUE top

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

ERRORS top

       EBADF  The argument sockfd is not a valid descriptor.

       EFAULT The addr argument points to memory not in a valid part of the
              process address space.

       EINVAL addrlen is invalid (e.g., is negative).

       ENOBUFS
              Insufficient resources were available in the system to perform the
              operation.

       ENOTCONN
              The socket is not connected.

       ENOTSOCK
              The argument sockfd is a file, not a socket.

CONFORMING TO top

       SVr4, 4.4BSD (the getpeername() function call first appeared in 4.2BSD),
       POSIX.1-2001.

NOTES top

       The third argument of getpeername() is in reality an int * (and this is
       what 4.x BSD and libc4 and libc5 have).  Some POSIX confusion resulted in
       the present socklen_t, also used by glibc.  See also accept(2).

SEE ALSO top

       accept(2), bind(2), getsockname(2), ip(7), socket(7), unix(7)

COLOPHON top

       This page is part of release 3.45 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-03                      GETPEERNAME(2)


setpgid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETPGID(2)                   Linux Programmer's Manual                  SETPGID(2)

NAME top

       setpgid, getpgid, setpgrp, getpgrp - set/get process group

SYNOPSIS top

       #include <unistd.h>

       int setpgid(pid_t pid, pid_t pgid);
       pid_t getpgid(pid_t pid);

       pid_t getpgrp(void);                 /* POSIX.1 version */
       pid_t getpgrp(pid_t pid);            /* BSD version */

       int setpgrp(void);                   /* System V version */
       int setpgrp(pid_t pid, pid_t pgid);  /* BSD version */

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

       getpgid():
           _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

       setpgrp() (POSIX.1):
           _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

       setpgrp() (BSD), getpgrp() (BSD):
           _BSD_SOURCE &&
               ! (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE ||
                  _XOPEN_SOURCE_EXTENDED || _GNU_SOURCE || _SVID_SOURCE)

DESCRIPTION top

       All of these interfaces are available on Linux, and are used for getting
       and setting the process group ID (PGID) of a process.  The preferred,
       POSIX.1-specified ways of doing this are: getpgrp(void), for retrieving the
       calling process's PGID; and setpgid(), for setting a process's PGID.

       setpgid() sets the PGID of the process specified by pid to pgid.  If pid is
       zero, then the process ID of the calling process is used.  If pgid is zero,
       then the PGID of the process specified by pid is made the same as its
       process ID.  If setpgid() is used to move a process from one process group
       to another (as is done by some shells when creating pipelines), both
       process groups must be part of the same session (see setsid(2) and
       credentials(7)).  In this case, the pgid specifies an existing process
       group to be joined and the session ID of that group must match the session
       ID of the joining process.

       The POSIX.1 version of getpgrp(), which takes no arguments, returns the
       PGID of the calling process.

       getpgid() returns the PGID of the process specified by pid.  If pid is
       zero, the process ID of the calling process is used.  (Retrieving the PGID
       of a process other than the caller is rarely necessary, and the POSIX.1
       getpgrp() is preferred for that task.)

       The System V-style setpgrp(), which takes no arguments, is equivalent to
       setpgid(0, 0).

       The BSD-specific setpgrp() call, which takes arguments pid and pgid, is
       equivalent to setpgid(pid, pgid).

       The BSD-specific getpgrp() call, which takes a single pid argument, is
       equivalent to getpgid(pid).

RETURN VALUE top

       On success, setpgid() and setpgrp() return zero.  On error, -1 is returned,
       and errno is set appropriately.

       The POSIX.1 getpgrp() always returns the PGID of the caller.

       getpgid(), and the BSD-specific getpgrp() return a process group on
       success.  On error, -1 is returned, and errno is set appropriately.

ERRORS top

       EACCES An attempt was made to change the process group ID of one of the
              children of the calling process and the child had already performed
              an execve(2) (setpgid(), setpgrp()).

       EINVAL pgid is less than 0 (setpgid(), setpgrp()).

       EPERM  An attempt was made to move a process into a process group in a
              different session, or to change the process group ID of one of the
              children of the calling process and the child was in a different
              session, or to change the process group ID of a session leader
              (setpgid(), setpgrp()).

       ESRCH  For getpgid(): pid does not match any process.  For setpgid(): pid
              is not the calling process and not a child of the calling process.

CONFORMING TO top

       setpgid() and the version of getpgrp() with no arguments conform to
       POSIX.1-2001.

       POSIX.1-2001 also specifies getpgid() and the version of setpgrp() that
       takes no arguments.  (POSIX.1-2008 marks this setpgrp() specification as
       obsolete.)

       The version of getpgrp() with one argument and the version of setpgrp()
       that takes two arguments derive from 4.2BSD, and are not specified by
       POSIX.1.

NOTES top

       A child created via fork(2) inherits its parent's process group ID.  The
       PGID is preserved across an execve(2).

       Each process group is a member of a session and each process is a member of
       the session of which its process group is a member.

       A session can have a controlling terminal.  At any time, one (and only one)
       of the process groups in the session can be the foreground process group
       for the terminal; the remaining process groups are in the background.  If a
       signal is generated from the terminal (e.g., typing the interrupt key to
       generate SIGINT), that signal is sent to the foreground process group.
       (See termios(3) for a description of the characters that generate signals.)
       Only the foreground process group may read(2) from the terminal; if a
       background process group tries to read(2) from the terminal, then the group
       is sent a SIGTSTP signal, which suspends it.  The tcgetpgrp(3) and
       tcsetpgrp(3) functions are used to get/set the foreground process group of
       the controlling terminal.

       The setpgid() and getpgrp() calls are used by programs such as bash(1) to
       create process groups in order to implement shell job control.

       If a session has a controlling terminal, and the CLOCAL flag for that
       terminal is not set, and a terminal hangup occurs, then the session leader
       is sent a SIGHUP.  If the session leader exits, then a SIGHUP signal will
       also be sent to each process in the foreground process group of the
       controlling terminal.

       If the exit of the process causes a process group to become orphaned, and
       if any member of the newly orphaned process group is stopped, then a SIGHUP
       signal followed by a SIGCONT signal will be sent to each process in the
       newly orphaned process group.  An orphaned process group is one in which
       the parent of every member of process group is either itself also a member
       of the process group or is a member of a process group in a different
       session (see also credentials(7)).

SEE ALSO top

       getuid(2), setsid(2), tcgetpgrp(3), tcsetpgrp(3), termios(3),
       credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                          SETPGID(2)


getpid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETPID(2)                    Linux Programmer's Manual                   GETPID(2)

NAME top

       getpid, getppid - get process identification

SYNOPSIS top

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

       pid_t getpid(void);
       pid_t getppid(void);

DESCRIPTION top

       getpid() returns the process ID of the calling process.  (This is often
       used by routines that generate unique temporary filenames.)

       getppid() returns the process ID of the parent of the calling process.

ERRORS top

       These functions are always successful.

CONFORMING TO top

       POSIX.1-2001, 4.3BSD, SVr4.

NOTES top

       Since glibc version 2.3.4, the glibc wrapper function for getpid() caches
       PIDs, so as to avoid additional system calls when a process calls getpid()
       repeatedly.  Normally this caching is invisible, but its correct operation
       relies on support in the wrapper functions for fork(2), vfork(2), and
       clone(2): if an application bypasses the glibc wrappers for these system
       calls by using syscall(2), then a call to getpid() in the child will return
       the wrong value (to be precise: it will return the PID of the parent
       process).  See also clone(2) for discussion of a case where getpid() may
       return the wrong value even when invoking clone(2) via the glibc wrapper
       function.

SEE ALSO top

       clone(2), fork(2), kill(2), exec(3), mkstemp(3), tempnam(3), tmpfile(3),
       tmpnam(3), credentials(7)

COLOPHON top

       This page is part of release 3.45 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-23                           GETPID(2)


getpriority(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETPRIORITY(2)               Linux Programmer's Manual              GETPRIORITY(2)

NAME top

       getpriority, setpriority - get/set program scheduling priority

SYNOPSIS top

       #include <sys/time.h>
       #include <sys/resource.h>

       int getpriority(int which, int who);
       int setpriority(int which, int who, int prio);

DESCRIPTION top

       The scheduling priority of the process, process group, or user, as
       indicated by which and who is obtained with the getpriority() call and set
       with the setpriority() call.

       The value which is one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and who is
       interpreted relative to which (a process identifier for PRIO_PROCESS,
       process group identifier for PRIO_PGRP, and a user ID for PRIO_USER).  A
       zero value for who denotes (respectively) the calling process, the process
       group of the calling process, or the real user ID of the calling process.
       Prio is a value in the range -20 to 19 (but see the Notes below).  The
       default priority is 0; lower priorities cause more favorable scheduling.

       The getpriority() call returns the highest priority (lowest numerical
       value) enjoyed by any of the specified processes.  The setpriority() call
       sets the priorities of all of the specified processes to the specified
       value.  Only the superuser may lower priorities.

RETURN VALUE top

       Since getpriority() can legitimately return the value -1, it is necessary
       to clear the external variable errno prior to the call, then check it
       afterward to determine if -1 is an error or a legitimate value.  The
       setpriority() call returns 0 if there is no error, or -1 if there is.

ERRORS top

       EINVAL which was not one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER.

       ESRCH  No process was located using the which and who values specified.

       In addition to the errors indicated above, setpriority() may fail if:

       EACCES The caller attempted to lower a process priority, but did not have
              the required privilege (on Linux: did not have the CAP_SYS_NICE
              capability).  Since Linux 2.6.12, this error only occurs if the
              caller attempts to set a process priority outside the range of the
              RLIMIT_NICE soft resource limit of the target process; see
              getrlimit(2) for details.

       EPERM  A process was located, but its effective user ID did not match
              either the effective or the real user ID of the caller, and was not
              privileged (on Linux: did not have the CAP_SYS_NICE capability).
              But see NOTES below.

CONFORMING TO top

       SVr4, 4.4BSD (these function calls first appeared in 4.2BSD), POSIX.1-2001.

NOTES top

       A child created by fork(2) inherits its parent's nice value.  The nice
       value is preserved across execve(2).

       The degree to which their relative nice value affects the scheduling of
       processes varies across UNIX systems, and, on Linux, across kernel
       versions.  Starting with kernel 2.6.23, Linux adopted an algorithm that
       causes relative differences in nice values to have a much stronger effect.
       This causes very low nice values (+19) to truly provide little CPU to a
       process whenever there is any other higher priority load on the system, and
       makes high nice values (-20) deliver most of the CPU to applications that
       require it (e.g., some audio applications).

       The details on the condition for EPERM depend on the system.  The above
       description is what POSIX.1-2001 says, and seems to be followed on all
       System V-like systems.  Linux kernels before 2.6.12 required the real or
       effective user ID of the caller to match the real user of the process who
       (instead of its effective user ID).  Linux 2.6.12 and later require the
       effective user ID of the caller to match the real or effective user ID of
       the process who.  All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, 4.3BSD,
       FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same manner as Linux 2.6.12
       and later.

       The actual priority range varies between kernel versions.  Linux before
       1.3.36 had -infinity..15.  Since kernel 1.3.43 Linux has the range -20..19.
       Within the kernel, nice values are actually represented using the
       corresponding range 40..1 (since negative numbers are error codes) and
       these are the values employed by the setpriority() and getpriority() system
       calls.  The glibc wrapper functions for these system calls handle the
       translations between the user-land and kernel representations of the nice
       value according to the formula unice = 20 - knice.

       On some systems, the range of nice values is -20..20.

       Including <sys/time.h> is not required these days, but increases
       portability.  (Indeed, <sys/resource.h> defines the rusage structure with
       fields of type struct timeval defined in <sys/time.h>.)

SEE ALSO top

       nice(1), renice(1), fork(2), capabilities(7)

       Documentation/scheduler/sched-nice-design.txt in the Linux kernel source
       tree (since Linux 2.6.23)

COLOPHON top

       This page is part of release 3.45 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-05-29                      GETPRIORITY(2)


getprotoent_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETPROTOENT_R(3)             Linux Programmer's Manual            GETPROTOENT_R(3)

NAME top

       getprotoent_r,  getprotobyname_r,  getprotobynumber_r  - get protocol entry
       (reentrant)

SYNOPSIS top

       #include <netdb.h>

       int getprotoent_r(struct protoent *result_buf, char *buf,
                       size_t buflen, struct protoent **result);

       int getprotobyname_r(const char *name,
                       struct protoent *result_buf, char *buf,
                       size_t buflen, struct protoent **result);

       int getprotobynumber_r(int proto,
                       struct protoent *result_buf, char *buf,
                       size_t buflen, struct protoent **result);

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

       getprotoent_r(), getprotobyname_r(), getprotobynumber_r():
           _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The getprotoent_r(), getprotobyname_r(), and getprotobynumber_r() functions
       are the reentrant equivalents of, respectively, getprotoent(3),
       getprotobyname(3), and getprotobynumber(3).  They differ in the way that
       the protoent structure is returned, and in the function calling signature
       and return value.  This manual page describes just the differences from the
       nonreentrant functions.

       Instead of returning a pointer to a statically allocated protoent structure
       as the function result, these functions copy the structure into the
       location pointed to by result_buf.

       The buf array is used to store the string fields pointed to by the returned
       protoent structure.  (The nonreentrant functions allocate these strings in
       static storage.)  The size of this array is specified in buflen.  If buf is
       too small, the call fails with the error ERANGE, and the caller must try
       again with a larger buffer.  (A buffer of length 1024 bytes should be
       sufficient for most applications.)

       If the function call successfully obtains a protocol record, then *result
       is set pointing to result_buf; otherwise, *result is set to NULL.

RETURN VALUE top

       On success, these functions return 0.  On error, they return one of the
       positive error numbers listed in ERRORS.

       On error, record not found (getprotobyname_r(), getprotobynumber_r()), or
       end of input (getprotoent_r()) result is set to NULL.

ERRORS top

       ENOENT (getprotoent_r()) No more records in database.

       ERANGE buf is too small.  Try again with a larger buffer (and increased
              buflen).

CONFORMING TO top

       These functions are GNU extensions.  Functions with similar names exist on
       some other systems, though typically with different calling signatures.

EXAMPLE top

       The program below uses getprotobyname_r() to retrieve the protocol record
       for the protocol named in its first command-line argument.  If a second
       (integer) command-line argument is supplied, it is used as the initial
       value for buflen; if getprotobyname_r() fails with the error ERANGE, the
       program retries with larger buffer sizes.  The following shell session
       shows a couple of sample runs:

           $ ./a.out tcp 1
           ERANGE! Retrying with larger buffer
           getprotobyname_r() returned: 0 (success)  (buflen=78)
           p_name=tcp; p_proto=6; aliases=TCP
           $ ./a.out xxx 1
           ERANGE! Retrying with larger buffer
           getprotobyname_r() returned: 0 (success)  (buflen=100)
           Call failed/record not found

Program source

       #define _GNU_SOURCE
       #include <ctype.h>
       #include <netdb.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <errno.h>
       #include <string.h>

       #define MAX_BUF 10000

       int
       main(int argc, char *argv[])
       {
           int buflen, erange_cnt, s;
           struct protoent result_buf;
           struct protoent *result;
           char buf[MAX_BUF];
           char **p;

           if (argc < 2) {
               printf("Usage: %s proto-name [buflen]\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           buflen = 1024;
           if (argc > 2)
               buflen = atoi(argv[2]);

           if (buflen > MAX_BUF) {
               printf("Exceeded buffer limit (%d)\n", MAX_BUF);
               exit(EXIT_FAILURE);
           }

           erange_cnt = 0;
           do {
               s = getprotobyname_r(argv[1], &result_buf,
                            buf, buflen, &result);
               if (s == ERANGE) {
                   if (erange_cnt == 0)
                       printf("ERANGE! Retrying with larger buffer\n");
                   erange_cnt++;

                   /* Increment a byte at a time so we can see exactly
                      what size buffer was required */

                   buflen++;

                   if (buflen > MAX_BUF) {
                       printf("Exceeded buffer limit (%d)\n", MAX_BUF);
                       exit(EXIT_FAILURE);
                   }
               }
           } while (s == ERANGE);

           printf("getprotobyname_r() returned: %s  (buflen=%d)\n",
                   (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
                   strerror(s), buflen);

           if (s != 0 || result == NULL) {
               printf("Call failed/record not found\n");
               exit(EXIT_FAILURE);
           }

           printf("p_name=%s; p_proto=%d; aliases=",
                       result_buf.p_name, result_buf.p_proto);
           for (p = result_buf.p_aliases; *p != NULL; p++)
               printf("%s ", *p);
           printf("\n");

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getprotoent(3), protocols(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                    GETPROTOENT_R(3)


getpt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETPT(3)                     Linux Programmer's Manual                    GETPT(3)

NAME top

       getpt - open the pseudoterminal master (PTM)

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <stdlib.h>

       int getpt(void);

DESCRIPTION top

       getpt() opens a pseudoterminal master and returns its file descriptor.  It
       is equivalent to

           open(/dev/ptmx, O_RDWR | O_NOCTTY);

       on Linux systems, though the pseudoterminal master is located elsewhere on
       some systems that use GNU Libc.

RETURN VALUE top

       getpt() returns an open file descriptor upon successful completion.
       Otherwise, it returns -1 and sets errno to indicate the error.

ERRORS top

       getpt() can fail with various errors described in open(2).

VERSIONS top

       getpt() is provided in glibc since version 2.1.

CONFORMING TO top

       getpt() is glibc-specific; use posix_openpt(3) instead.

SEE ALSO top

       grantpt(3), posix_openpt(3), ptsname(3), unlockpt(3), ptmx(4), pty(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                            GETPT(3)


getpw(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETPW(3)                     Linux Programmer's Manual                    GETPW(3)

NAME top

       getpw - reconstruct password line entry

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/types.h>
       #include <pwd.h>

       int getpw(uid_t uid, char *buf);

DESCRIPTION top

       The getpw() function reconstructs the password line entry for the given
       user ID uid in the buffer buf.  The returned buffer contains a line of
       format

              name:passwd:uid:gid:gecos:dir:shell

       The passwd structure is defined in <pwd.h> as follows:

           struct passwd {
               char   *pw_name;       /* username */
               char   *pw_passwd;     /* user password */
               uid_t   pw_uid;        /* user ID */
               gid_t   pw_gid;        /* group ID */
               char   *pw_gecos;      /* user information */
               char   *pw_dir;        /* home directory */
               char   *pw_shell;      /* shell program */
           };

       For more information about the fields of this structure, see passwd(5).

RETURN VALUE top

       The getpw() function returns 0 on success; on error, it returns -1, and
       errno is set to indicate the error.

ERRORS top

       EINVAL buf is NULL.

       ENOENT No user corresponding to uid.

       ENOMEM Insufficient memory to allocate passwd structure.

FILES top

       /etc/passwd
              password database file

CONFORMING TO top

       SVr2.

BUGS top

       The getpw() function is dangerous as it may overflow the provided buffer
       buf.  It is obsoleted by getpwuid(3).

SEE ALSO top

       endpwent(3), fgetpwent(3), getpwent(3), getpwnam(3), getpwuid(3),
       putpwent(3), setpwent(3), passwd(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-21                            GETPW(3)


getpwnam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETPWNAM(3)                  Linux Programmer's Manual                 GETPWNAM(3)

NAME top

       getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file entry

SYNOPSIS top

       #include <sys/types.h>
       #include <pwd.h>

       struct passwd *getpwnam(const char *name);

       struct passwd *getpwuid(uid_t uid);

       int getpwnam_r(const char *name, struct passwd *pwd,
                   char *buf, size_t buflen, struct passwd **result);

       int getpwuid_r(uid_t uid, struct passwd *pwd,
                   char *buf, size_t buflen, struct passwd **result);

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

       getpwnam_r(), getpwuid_r():
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||
           _POSIX_SOURCE

DESCRIPTION top

       The getpwnam() function returns a pointer to a structure containing the
       broken-out fields of the record in the password database (e.g., the local
       password file /etc/passwd, NIS, and LDAP) that matches the username name.

       The getpwuid() function returns a pointer to a structure containing the
       broken-out fields of the record in the password database that matches the
       user ID uid.

       The passwd structure is defined in <pwd.h> as follows:

           struct passwd {
               char   *pw_name;       /* username */
               char   *pw_passwd;     /* user password */
               uid_t   pw_uid;        /* user ID */
               gid_t   pw_gid;        /* group ID */
               char   *pw_gecos;      /* user information */
               char   *pw_dir;        /* home directory */
               char   *pw_shell;      /* shell program */
           };

       See passwd(5) for more information about these fields.

       The getpwnam_r() and getpwuid_r() functions obtain the same information as
       getpwnam() and getpwuid(), but store the retrieved passwd structure in the
       space pointed to by pwd.  The string fields pointed to by the members of
       the passwd structure are stored in the buffer buf of size buflen.  A
       pointer to the result (in case of success) or NULL (in case no entry was
       found or an error occurred) is stored in *result.

       The call

           sysconf(_SC_GETPW_R_SIZE_MAX)

       returns either -1, without changing errno, or an initial suggested size for
       buf.  (If this size is too small, the call fails with ERANGE, in which case
       the caller can retry with a larger buffer.)

RETURN VALUE top

       The getpwnam() and getpwuid() functions return a pointer to a passwd
       structure, or NULL if the matching entry is not found or an error occurs.
       If an error occurs, errno is set appropriately.  If one wants to check
       errno after the call, it should be set to zero before the call.

       The return value may point to a static area, and may be overwritten by
       subsequent calls to getpwent(3), getpwnam(), or getpwuid().  (Do not pass
       the returned pointer to free(3).)

       On success, getpwnam_r() and getpwuid_r() return zero, and set *result to
       pwd.  If no matching password record was found, these functions return 0
       and store NULL in *result.  In case of error, an error number is returned,
       and NULL is stored in *result.

ERRORS top

       0 or ENOENT or ESRCH or EBADF or EPERM or ...
              The given name or uid was not found.

       EINTR  A signal was caught.

       EIO    I/O error.

       EMFILE The maximum number (OPEN_MAX) of files was open already in the
              calling process.

       ENFILE The maximum number of files was open already in the system.

       ENOMEM Insufficient memory to allocate passwd structure.

       ERANGE Insufficient buffer space supplied.

FILES top

       /etc/passwd
              local password database file

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  The pw_gecos field is not specified in POSIX,
       but is present on most implementations.

NOTES top

       The formulation given above under "RETURN VALUE" is from POSIX.1-2001.  It
       does not call "not found" an error, and hence does not specify what value
       errno might have in this situation.  But that makes it impossible to
       recognize errors.  One might argue that according to POSIX errno should be
       left unchanged if an entry is not found.  Experiments on various UNIX-like
       systems show that lots of different values occur in this situation: 0,
       ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others.

       The pw_dir field contains the name of the initial working directory of the
       user.  Login programs use the value of this field to initialize the HOME
       environment variable for the login shell.  An application that wants to
       determine its user's home directory should inspect the value of HOME
       (rather than the value getpwuid(getuid())->pw_dir) since this allows the
       user to modify their notion of "the home directory" during a login session.
       To determine the (initial) home directory of another user, it is necessary
       to use getpwnam("username")->pw_dir or similar.

EXAMPLE top

       The program below demonstrates the use of getpwnam_r() to find the full
       username and user ID for the username supplied as a command-line argument.

       #include <pwd.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>

       int
       main(int argc, char *argv[])
       {
           struct passwd pwd;
           struct passwd *result;
           char *buf;
           size_t bufsize;
           int s;

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

           bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
           if (bufsize == -1)          /* Value was indeterminate */
               bufsize = 16384;        /* Should be more than enough */

           buf = malloc(bufsize);
           if (buf == NULL) {
               perror("malloc");
               exit(EXIT_FAILURE);
           }

           s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
           if (result == NULL) {
               if (s == 0)
                   printf("Not found\n");
               else {
                   errno = s;
                   perror("getpwnam_r");
               }
               exit(EXIT_FAILURE);
           }

           printf("Name: %s; UID: %ld\n", pwd.pw_gecos, (long) pwd.pw_uid);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getspnam(3),
       putpwent(3), setpwent(3), passwd(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-23                         GETPWNAM(3)


getresuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETRESUID(2)                 Linux Programmer's Manual                GETRESUID(2)

NAME top

       getresuid, getresgid - get real, effective and saved user/group IDs

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>

       int getresuid(uid_t *ruid, uid_t *euid, uid_t *suid);
       int getresgid(gid_t *rgid, gid_t *egid, gid_t *sgid);

DESCRIPTION top

       getresuid() returns the real UID, the effective UID, and the saved set-
       user-ID of the calling process, in the arguments ruid, euid, and suid,
       respectively.  getresgid() performs the analogous task for the process's
       group IDs.

RETURN VALUE top

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

ERRORS top

       EFAULT One of the arguments specified an address outside the calling
              program's address space.

VERSIONS top

       These system calls appeared on Linux starting with kernel 2.1.44.

       The prototypes are given by glibc since version 2.3.2, provided _GNU_SOURCE
       is defined.

CONFORMING TO top

       These calls are nonstandard; they also appear on HP-UX and some of the
       BSDs.

NOTES top

       The original Linux getresuid() and getresgid() system calls supported only
       16-bit user and group IDs.  Subsequently, Linux 2.4 added getresuid32() and
       getresgid32(), supporting 32-bit IDs.  The glibc getresuid() and
       getresgid() wrapper functions transparently deal with the variations across
       kernel versions.

SEE ALSO top

       getuid(2), setresuid(2), setreuid(2), setuid(2), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                        GETRESUID(2)


getrlimit(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETRLIMIT(2)                 Linux Programmer's Manual                GETRLIMIT(2)

NAME top

       getrlimit, setrlimit, prlimit - get/set resource limits

SYNOPSIS top

       #include <sys/time.h>
       #include <sys/resource.h>

       int getrlimit(int resource, struct rlimit *rlim);
       int setrlimit(int resource, const struct rlimit *rlim);

       int prlimit(pid_t pid, int resource, const struct rlimit *new_limit,
                   struct rlimit *old_limit);

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

       prlimit(): _GNU_SOURCE && _FILE_OFFSET_BITS == 64

DESCRIPTION top

       The getrlimit() and setrlimit() system calls get and set resource limits
       respectively.  Each resource has an associated soft and hard limit, as
       defined by the rlimit structure:

           struct rlimit {
               rlim_t rlim_cur;  /* Soft limit */
               rlim_t rlim_max;  /* Hard limit (ceiling for rlim_cur) */
           };

       The soft limit is the value that the kernel enforces for the corresponding
       resource.  The hard limit acts as a ceiling for the soft limit: an
       unprivileged process may only set its soft limit to a value in the range
       from 0 up to the hard limit, and (irreversibly) lower its hard limit.  A
       privileged process (under Linux: one with the CAP_SYS_RESOURCE capability)
       may make arbitrary changes to either limit value.

       The value RLIM_INFINITY denotes no limit on a resource (both in the
       structure returned by getrlimit() and in the structure passed to
       setrlimit()).

       The resource argument must be one of:

       RLIMIT_AS
              The maximum size of the process's virtual memory (address space) in
              bytes.  This limit affects calls to brk(2), mmap(2) and mremap(2),
              which fail with the error ENOMEM upon exceeding this limit.  Also
              automatic stack expansion will fail (and generate a SIGSEGV that
              kills the process if no alternate stack has been made available via
              sigaltstack(2)).  Since the value is a long, on machines with a
              32-bit long either this limit is at most 2 GiB, or this resource is
              unlimited.

       RLIMIT_CORE
              Maximum size of core file.  When 0 no core dump files are created.
              When nonzero, larger dumps are truncated to this size.

       RLIMIT_CPU
              CPU time limit in seconds.  When the process reaches the soft limit,
              it is sent a SIGXCPU signal.  The default action for this signal is
              to terminate the process.  However, the signal can be caught, and
              the handler can return control to the main program.  If the process
              continues to consume CPU time, it will be sent SIGXCPU once per
              second until the hard limit is reached, at which time it is sent
              SIGKILL.  (This latter point describes Linux behavior.
              Implementations vary in how they treat processes which continue to
              consume CPU time after reaching the soft limit.  Portable
              applications that need to catch this signal should perform an
              orderly termination upon first receipt of SIGXCPU.)

       RLIMIT_DATA
              The maximum size of the process's data segment (initialized data,
              uninitialized data, and heap).  This limit affects calls to brk(2)
              and sbrk(2), which fail with the error ENOMEM upon encountering the
              soft limit of this resource.

       RLIMIT_FSIZE
              The maximum size of files that the process may create.  Attempts to
              extend a file beyond this limit result in delivery of a SIGXFSZ
              signal.  By default, this signal terminates a process, but a process
              can catch this signal instead, in which case the relevant system
              call (e.g., write(2), truncate(2)) fails with the error EFBIG.

       RLIMIT_LOCKS (Early Linux 2.4 only)
              A limit on the combined number of flock(2) locks and fcntl(2) leases
              that this process may establish.

       RLIMIT_MEMLOCK
              The maximum number of bytes of memory that may be locked into RAM.
              In effect this limit is rounded down to the nearest multiple of the
              system page size.  This limit affects mlock(2) and mlockall(2) and
              the mmap(2) MAP_LOCKED operation.  Since Linux 2.6.9 it also affects
              the shmctl(2) SHM_LOCK operation, where it sets a maximum on the
              total bytes in shared memory segments (see shmget(2)) that may be
              locked by the real user ID of the calling process.  The shmctl(2)
              SHM_LOCK locks are accounted for separately from the per-process
              memory locks established by mlock(2), mlockall(2), and mmap(2)
              MAP_LOCKED; a process can lock bytes up to this limit in each of
              these two categories.  In Linux kernels before 2.6.9, this limit
              controlled the amount of memory that could be locked by a privileged
              process.  Since Linux 2.6.9, no limits are placed on the amount of
              memory that a privileged process may lock, and this limit instead
              governs the amount of memory that an unprivileged process may lock.

       RLIMIT_MSGQUEUE (Since Linux 2.6.8)
              Specifies the limit on the number of bytes that can be allocated for
              POSIX message queues for the real user ID of the calling process.
              This limit is enforced for mq_open(3).  Each message queue that the
              user creates counts (until it is removed) against this limit
              according to the formula:

                  bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) +
                          attr.mq_maxmsg * attr.mq_msgsize

              where attr is the mq_attr structure specified as the fourth argument
              to mq_open(3).

              The first addend in the formula, which includes sizeof(struct
              msg_msg *) (4 bytes on Linux/i386), ensures that the user cannot
              create an unlimited number of zero-length messages (such messages
              nevertheless each consume some system memory for bookkeeping
              overhead).

       RLIMIT_NICE (since Linux 2.6.12, but see BUGS below)
              Specifies a ceiling to which the process's nice value can be raised
              using setpriority(2) or nice(2).  The actual ceiling for the nice
              value is calculated as 20 - rlim_cur.  (This strangeness occurs
              because negative numbers cannot be specified as resource limit
              values, since they typically have special meanings.  For example,
              RLIM_INFINITY typically is the same as -1.)

       RLIMIT_NOFILE
              Specifies a value one greater than the maximum file descriptor
              number that can be opened by this process.  Attempts (open(2),
              pipe(2), dup(2), etc.)  to exceed this limit yield the error EMFILE.
              (Historically, this limit was named RLIMIT_OFILE on BSD.)

       RLIMIT_NPROC
              The maximum number of processes (or, more precisely on Linux,
              threads) that can be created for the real user ID of the calling
              process.  Upon encountering this limit, fork(2) fails with the error
              EAGAIN.

       RLIMIT_RSS
              Specifies the limit (in pages) of the process's resident set (the
              number of virtual pages resident in RAM).  This limit only has
              effect in Linux 2.4.x, x < 30, and there only affects calls to
              madvise(2) specifying MADV_WILLNEED.

       RLIMIT_RTPRIO (Since Linux 2.6.12, but see BUGS)
              Specifies a ceiling on the real-time priority that may be set for
              this process using sched_setscheduler(2) and sched_setparam(2).

       RLIMIT_RTTIME (Since Linux 2.6.25)
              Specifies a limit (in microseconds) on the amount of CPU time that a
              process scheduled under a real-time scheduling policy may consume
              without making a blocking system call.  For the purpose of this
              limit, each time a process makes a blocking system call, the count
              of its consumed CPU time is reset to zero.  The CPU time count is
              not reset if the process continues trying to use the CPU but is
              preempted, its time slice expires, or it calls sched_yield(2).

              Upon reaching the soft limit, the process is sent a SIGXCPU signal.
              If the process catches or ignores this signal and continues
              consuming CPU time, then SIGXCPU will be generated once each second
              until the hard limit is reached, at which point the process is sent
              a SIGKILL signal.

              The intended use of this limit is to stop a runaway real-time
              process from locking up the system.

       RLIMIT_SIGPENDING (Since Linux 2.6.8)
              Specifies the limit on the number of signals that may be queued for
              the real user ID of the calling process.  Both standard and real-
              time signals are counted for the purpose of checking this limit.
              However, the limit is only enforced for sigqueue(3); it is always
              possible to use kill(2) to queue one instance of any of the signals
              that are not already queued to the process.

       RLIMIT_STACK
              The maximum size of the process stack, in bytes.  Upon reaching this
              limit, a SIGSEGV signal is generated.  To handle this signal, a
              process must employ an alternate signal stack (sigaltstack(2)).

              Since Linux 2.6.23, this limit also determines the amount of space
              used for the process's command-line arguments and environment
              variables; for details, see execve(2).

prlimit()

       The Linux-specific prlimit() system call combines and extends the
       functionality of setrlimit() and getrlimit().  It can be used to both set
       and get the resource limits of an arbitrary process.

       The resource argument has the same meaning as for setrlimit() and
       getrlimit().

       If the new_limit argument is a not NULL, then the rlimit structure to which
       it points is used to set new values for the soft and hard limits for
       resource.  If the old_limit argument is a not NULL, then a successful call
       to prlimit() places the previous soft and hard limits for resource in the
       rlimit structure pointed to by old_limit.

       The pid argument specifies the ID of the process on which the call is to
       operate.  If pid is 0, then the call applies to the calling process.  To
       set or get the resources of a process other than itself, the caller must
       have the CAP_SYS_RESOURCE capability, or the real, effective, and saved set
       user IDs of the target process must match the real user ID of the caller
       and the real, effective, and saved set group IDs of the target process must
       match the real group ID of the caller.

RETURN VALUE top

       On success, these system calls return 0.  On error, -1 is returned, and
       errno is set appropriately.

ERRORS top

       EFAULT A pointer argument points to a location outside the accessible
              address space.

       EINVAL The value specified in resource is not valid; or, for setrlimit() or
              prlimit(): rlim->rlim_cur was greater than rlim->rlim_max.

       EPERM  An unprivileged process tried to raise the hard limit; the
              CAP_SYS_RESOURCE capability is required to do this.  Or, the caller
              tried to increase the hard RLIMIT_NOFILE limit above the current
              kernel maximum (NR_OPEN).  Or, the calling process did not have
              permission to set limits for the process specified by pid.

       ESRCH  Could not find a process with the ID specified in pid.

VERSIONS top

       The prlimit() system call is available since Linux 2.6.36.  Library support
       is available since glibc 2.13.

CONFORMING TO top

       getrlimit(), setrlimit(): SVr4, 4.3BSD, POSIX.1-2001.
       prlimit(): Linux-specific.

       RLIMIT_MEMLOCK and RLIMIT_NPROC derive from BSD and are not specified in
       POSIX.1-2001; they are present on the BSDs and Linux, but on few other
       implementations.  RLIMIT_RSS derives from BSD and is not specified in
       POSIX.1-2001; it is nevertheless present on most implementations.
       RLIMIT_MSGQUEUE, RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_RTTIME, and
       RLIMIT_SIGPENDING are Linux-specific.

NOTES top

       A child process created via fork(2) inherits its parent's resource limits.
       Resource limits are preserved across execve(2).

       One can set the resource limits of the shell using the built-in ulimit
       command (limit in csh(1)).  The shell's resource limits are inherited by
       the processes that it creates to execute commands.

       Since Linux 2.6.24, the resource limits of any process can be inspected via
       /proc/[pid]/limits; see proc(5).

       Ancient systems provided a vlimit() function with a similar purpose to
       setrlimit().  For backward compatibility, glibc also provides vlimit().
       All new applications should be written using setrlimit().

EXAMPLE top

       The program below demonstrates the use of prlimit().

       #define _GNU_SOURCE
       #define _FILE_OFFSET_BITS 64
       #include <stdio.h>
       #include <time.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <sys/resource.h>

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

       int
       main(int argc, char *argv[])
       {
           struct rlimit old, new;
           struct rlimit *newp;
           pid_t pid;

           if (!(argc == 2 || argc == 4)) {
               fprintf(stderr, "Usage: %s <pid> [<new-soft-limit> "
                       "<new-hard-limit>]\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           pid = atoi(argv[1]);        /* PID of target process */

           newp = NULL;
           if (argc == 4) {
               new.rlim_cur = atoi(argv[2]);
               new.rlim_max = atoi(argv[3]);
               newp = &new;
           }

           /* Set CPU time limit of target process; retrieve and display
              previous limit */

           if (prlimit(pid, RLIMIT_CPU, newp, &old) == -1)
               errExit("prlimit-1");
           printf("Previous limits: soft=%lld; hard=%lld\n",
                   (long long) old.rlim_cur, (long long) old.rlim_max);

           /* Retrieve and display new CPU time limit */

           if (prlimit(pid, RLIMIT_CPU, NULL, &old) == -1)
               errExit("prlimit-2");
           printf("New limits: soft=%lld; hard=%lld\n",
                   (long long) old.rlim_cur, (long long) old.rlim_max);

           exit(EXIT_FAILURE);
       }

BUGS top

       In older Linux kernels, the SIGXCPU and SIGKILL signals delivered when a
       process encountered the soft and hard RLIMIT_CPU limits were delivered one
       (CPU) second later than they should have been.  This was fixed in kernel
       2.6.8.

       In 2.6.x kernels before 2.6.17, a RLIMIT_CPU limit of 0 is wrongly treated
       as "no limit" (like RLIM_INFINITY).  Since Linux 2.6.17, setting a limit of
       0 does have an effect, but is actually treated as a limit of 1 second.

       A kernel bug means that RLIMIT_RTPRIO does not work in kernel 2.6.12; the
       problem is fixed in kernel 2.6.13.

       In kernel 2.6.12, there was an off-by-one mismatch between the priority
       ranges returned by getpriority(2) and RLIMIT_NICE.  This had the effect
       that the actual ceiling for the nice value was calculated as 19 - rlim_cur.
       This was fixed in kernel 2.6.13.

       Since Linux 2.6.12, if a process reaches its soft RLIMIT_CPU limit and has
       a handler installed for SIGXCPU, then, in addition to invoking the signal
       handler, the kernel increases the soft limit by one second.  This behavior
       repeats if the process continues to consume CPU time, until the hard limit
       is reached, at which point the process is killed.  Other implementations do
       not change the RLIMIT_CPU soft limit in this manner, and the Linux behavior
       is probably not standards conformant; portable applications should avoid
       relying on this Linux-specific behavior.  The Linux-specific RLIMIT_RTTIME
       limit exhibits the same behavior when the soft limit is encountered.

       Kernels before 2.4.22 did not diagnose the error EINVAL for setrlimit()
       when rlim->rlim_cur was greater than rlim->rlim_max.

SEE ALSO top

       dup(2), fcntl(2), fork(2), getrusage(2), mlock(2), mmap(2), open(2),
       quotactl(2), sbrk(2), shmctl(2), malloc(3), sigqueue(3), ulimit(3),
       core(5), capabilities(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-11-25                        GETRLIMIT(2)


getrpcent_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GETRPCENT_R(3)               Linux Programmer's Manual              GETRPCENT_R(3)

NAME top

       getrpcent_r, getrpcbyname_r, getrpcbynumber_r - get RPC entry (reentrant)

SYNOPSIS top

       #include <netdb.h>

       int getrpcent_r(struct rpcent *result_buf, char *buf,
                       size_t buflen, struct rpcent **result);

       int getrpcbyname_r(const char *name,
                       struct rpcent *result_buf, char *buf,
                       size_t buflen, struct rpcent **result);

       int getrpcbynumber_r(int number,
                       struct rpcent *result_buf, char *buf,
                       size_t buflen, struct rpcent **result);

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

       getrpcent_r(), getrpcbyname_r(), getrpcbynumber_r():
           _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The getrpcent_r(), getrpcbyname_r(), and getrpcbynumber_r() functions are
       the reentrant equivalents of, respectively, getrpcent(3), getrpcbyname(3),
       and getrpcbynumber(3).  They differ in the way that the rpcent structure is
       returned, and in the function calling signature and return value.  This
       manual page describes just the differences from the nonreentrant functions.

       Instead of returning a pointer to a statically allocated rpcent structure
       as the function result, these functions copy the structure into the
       location pointed to by result_buf.

       The buf array is used to store the string fields pointed to by the returned
       rpcent structure.  (The nonreentrant functions allocate these strings in
       static storage.)  The size of this array is specified in buflen.  If buf is
       too small, the call fails with the error ERANGE, and the caller must try
       again with a larger buffer.  (A buffer of length 1024 bytes should be
       sufficient for most applications.)

       If the function call successfully obtains an RPC record, then *result is
       set pointing to result_buf; otherwise, *result is set to NULL.

RETURN VALUE top

       On success, these functions return 0.  On error, they return one of the
       positive error numbers listed in ERRORS.

       On error, record not found (getrpcbyname_r(), getrpcbynumber_r()), or end
       of input (getrpcent_r()) result is set to NULL.

ERRORS top

       ENOENT (getrpcent_r()) No more records in database.

       ERANGE buf is too small.  Try again with a larger buffer (and increased
              buflen).

CONFORMING TO top

       These functions are GNU extensions.  Functions with similar names exist on
       some other systems, though typically with different calling signatures.

SEE ALSO top

       getrpcent(3), rpc(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                      GETRPCENT_R(3)


getrpcport(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | COLOPHON The Linux Programming Interface

GETRPCPORT(3)                Linux Programmer's Manual               GETRPCPORT(3)

NAME top

       getrpcport - get RPC port number

SYNOPSIS top

       int getrpcport(char *host, int prognum, int versnum, int proto);

DESCRIPTION top

       getrpcport() returns the port number for version versnum of the RPC program
       prognum running on host and using protocol proto.  It returns 0 if it
       cannot contact the portmapper, or if prognum is not registered.  If prognum
       is registered but not with version versnum, it will still return a port
       number (for some version of the program) indicating that the program is
       indeed registered.  The version mismatch will be detected upon the first
       call to the service.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs, Solaris, and many other systems.

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-12-23                       GETRPCPORT(3)


getrusage(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETRUSAGE(2)                 Linux Programmer's Manual                GETRUSAGE(2)

NAME top

       getrusage - get resource usage

SYNOPSIS top

       #include <sys/time.h>
       #include <sys/resource.h>

       int getrusage(int who, struct rusage *usage);

DESCRIPTION top

       getrusage() returns resource usage measures for who, which can be one of
       the following:

       RUSAGE_SELF
              Return resource usage statistics for the calling process, which is
              the sum of resources used by all threads in the process.

       RUSAGE_CHILDREN
              Return resource usage statistics for all children of the calling
              process that have terminated and been waited for.  These statistics
              will include the resources used by grandchildren, and further
              removed descendants, if all of the intervening descendants waited on
              their terminated children.

       RUSAGE_THREAD (since Linux 2.6.26)
              Return resource usage statistics for the calling thread.

       The resource usages are returned in the structure pointed to by usage,
       which has the following form:

           struct rusage {
               struct timeval ru_utime; /* user CPU time used */
               struct timeval ru_stime; /* system CPU time used */
               long   ru_maxrss;        /* maximum resident set size */
               long   ru_ixrss;         /* integral shared memory size */
               long   ru_idrss;         /* integral unshared data size */
               long   ru_isrss;         /* integral unshared stack size */
               long   ru_minflt;        /* page reclaims (soft page faults) */
               long   ru_majflt;        /* page faults (hard page faults) */
               long   ru_nswap;         /* swaps */
               long   ru_inblock;       /* block input operations */
               long   ru_oublock;       /* block output operations */
               long   ru_msgsnd;        /* IPC messages sent */
               long   ru_msgrcv;        /* IPC messages received */
               long   ru_nsignals;      /* signals received */
               long   ru_nvcsw;         /* voluntary context switches */
               long   ru_nivcsw;        /* involuntary context switches */
           };

       Not all fields are completed; unmaintained fields are set to zero by the
       kernel.  (The unmaintained fields are provided for compatibility with other
       systems, and because they may one day be supported on Linux.)  The fields
       are interpreted as follows:

       ru_utime
              This is the total amount of time spent executing in user mode,
              expressed in a timeval structure (seconds plus microseconds).

       ru_stime
              This is the total amount of time spent executing in kernel mode,
              expressed in a timeval structure (seconds plus microseconds).

       ru_maxrss (since Linux 2.6.32)
              This is the maximum resident set size used (in kilobytes). For
              RUSAGE_CHILDREN, this is the resident set size of the largest child,
              not the maximum resident set size of the process tree.

       ru_ixrss (unmaintained)
              This field is currently unused on Linux.

       ru_idrss (unmaintained)
              This field is currently unused on Linux.

       ru_isrss (unmaintained)
              This field is currently unused on Linux.

       ru_minflt
              The number of page faults serviced without any I/O activity; here
              I/O activity is avoided by "reclaiming" a page frame from the list
              of pages awaiting reallocation.

       ru_majflt
              The number of page faults serviced that required I/O activity.

       ru_nswap (unmaintained)
              This field is currently unused on Linux.

       ru_inblock (since Linux 2.6.22)
              The number of times the file system had to perform input.

       ru_oublock (since Linux 2.6.22)
              The number of times the file system had to perform output.

       ru_msgsnd (unmaintained)
              This field is currently unused on Linux.

       ru_msgrcv (unmaintained)
              This field is currently unused on Linux.

       ru_nsignals (unmaintained)
              This field is currently unused on Linux.

       ru_nvcsw (since Linux 2.6)
              The number of times a context switch resulted due to a process
              voluntarily giving up the processor before its time slice was
              completed (usually to await availability of a resource).

       ru_nivcsw (since Linux 2.6)
              The number of times a context switch resulted due to a higher
              priority process becoming runnable or because the current process
              exceeded its time slice.

RETURN VALUE top

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

ERRORS top

       EFAULT usage points outside the accessible address space.

       EINVAL who is invalid.

CONFORMING TO top

       SVr4, 4.3BSD.  POSIX.1-2001 specifies getrusage(), but only specifies the
       fields ru_utime and ru_stime.

       RUSAGE_THREAD is Linux-specific.

NOTES top

       Resource usage metrics are preserved across an execve(2).

       Including <sys/time.h> is not required these days, but increases
       portability.  (Indeed, struct timeval is defined in <sys/time.h>.)

       In Linux kernel versions before 2.6.9, if the disposition of SIGCHLD is set
       to SIG_IGN then the resource usages of child processes are automatically
       included in the value returned by RUSAGE_CHILDREN, although POSIX.1-2001
       explicitly prohibits this.  This nonconformance is rectified in Linux 2.6.9
       and later.

       The structure definition shown at the start of this page was taken from
       4.3BSD Reno.

       Ancient systems provided a vtimes() function with a similar purpose to
       getrusage().  For backward compatibility, glibc also provides vtimes().
       All new applications should be written using getrusage().

       See also the description of /proc/PID/stat in proc(5).

SEE ALSO top

       clock_gettime(2), getrlimit(2), times(2), wait(2), wait4(2), clock(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                        GETRUSAGE(2)


getservent_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETSERVENT_R(3)              Linux Programmer's Manual             GETSERVENT_R(3)

NAME top

       getservent_r,  getservbyname_r,  getservbyport_r - get service entry (reen-
       trant)

SYNOPSIS top

       #include <netdb.h>

       int getservent_r(struct servent *result_buf, char *buf,
                       size_t buflen, struct servent **result);

       int getservbyname_r(const char *name, const char *proto,
                       struct servent *result_buf, char *buf,
                       size_t buflen, struct servent **result);

       int getservbyport_r(int port, const char *proto,
                       struct servent *result_buf, char *buf,
                       size_t buflen, struct servent **result);

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

       getservent_r(), getservbyname_r(), getservbyport_r():
           _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The getservent_r(), getservbyname_r(), and getservbyport_r() functions are
       the reentrant equivalents of, respectively, getservent(3),
       getservbyname(3), and getservbyport(3).  They differ in the way that the
       servent structure is returned, and in the function calling signature and
       return value.  This manual page describes just the differences from the
       nonreentrant functions.

       Instead of returning a pointer to a statically allocated servent structure
       as the function result, these functions copy the structure into the
       location pointed to by result_buf.

       The buf array is used to store the string fields pointed to by the returned
       servent structure.  (The nonreentrant functions allocate these strings in
       static storage.)  The size of this array is specified in buflen.  If buf is
       too small, the call fails with the error ERANGE, and the caller must try
       again with a larger buffer.  (A buffer of length 1024 bytes should be
       sufficient for most applications.)

       If the function call successfully obtains a service record, then *result is
       set pointing to result_buf; otherwise, *result is set to NULL.

RETURN VALUE top

       On success, these functions return 0.  On error, they return one of the
       positive error numbers listed in errors.

       On error, record not found (getservbyname_r(), getservbyport_r()), or end
       of input (getservent_r()) result is set to NULL.

ERRORS top

       ENOENT (getservent_r()) No more records in database.

       ERANGE buf is too small.  Try again with a larger buffer (and increased
              buflen).

CONFORMING TO top

       These functions are GNU extensions.  Functions with similar names exist on
       some other systems, though typically with different calling signatures.

EXAMPLE top

       The program below uses getservbyport_r() to retrieve the service record for
       the port and protocol named in its first command-line argument.  If a third
       (integer) command-line argument is supplied, it is used as the initial
       value for buflen; if getservbyport_r() fails with the error ERANGE, the
       program retries with larger buffer sizes.  The following shell session
       shows a couple of sample runs:

           $ ./a.out 7 tcp 1
           ERANGE! Retrying with larger buffer
           getservbyport_r() returned: 0 (success)  (buflen=87)
           s_name=echo; s_proto=tcp; s_port=7; aliases=
           $ ./a.out 77777 tcp
           getservbyport_r() returned: 0 (success)  (buflen=1024)
           Call failed/record not found

Program source

       #define _GNU_SOURCE
       #include <ctype.h>
       #include <netdb.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <errno.h>
       #include <string.h>

       #define MAX_BUF 10000

       int
       main(int argc, char *argv[])
       {
           int buflen, erange_cnt, port, s;
           struct servent result_buf;
           struct servent *result;
           char buf[MAX_BUF];
           char *protop;
           char **p;

           if (argc < 3) {
               printf("Usage: %s port-num proto-name [buflen]\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           port = htons(atoi(argv[1]));
           protop = (strcmp(argv[2], "null") == 0 ||
                  strcmp(argv[2], "NULL") == 0) ?  NULL : argv[2];

           buflen = 1024;
           if (argc > 3)
               buflen = atoi(argv[3]);

           if (buflen > MAX_BUF) {
               printf("Exceeded buffer limit (%d)\n", MAX_BUF);
               exit(EXIT_FAILURE);
           }

           erange_cnt = 0;
           do {
               s = getservbyport_r(port, protop, &result_buf,
                            buf, buflen, &result);
               if (s == ERANGE) {
                   if (erange_cnt == 0)
                       printf("ERANGE! Retrying with larger buffer\n");
                   erange_cnt++;

                   /* Increment a byte at a time so we can see exactly
                      what size buffer was required */

                   buflen++;

                   if (buflen > MAX_BUF) {
                       printf("Exceeded buffer limit (%d)\n", MAX_BUF);
                       exit(EXIT_FAILURE);
                   }
               }
           } while (s == ERANGE);

           printf("getservbyport_r() returned: %s  (buflen=%d)\n",
                   (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
                   strerror(s), buflen);

           if (s != 0 || result == NULL) {
               printf("Call failed/record not found\n");
               exit(EXIT_FAILURE);
           }

           printf("s_name=%s; s_proto=%s; s_port=%d; aliases=",
                       result_buf.s_name, result_buf.s_proto,
                       ntohs(result_buf.s_port));
           for (p = result_buf.s_aliases; *p != NULL; p++)
               printf("%s ", *p);
           printf("\n");

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getservent(3), services(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                     GETSERVENT_R(3)


getsid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETSID(2)                    Linux Programmer's Manual                   GETSID(2)

NAME top

       getsid - get session ID

SYNOPSIS top

       #include <unistd.h>

       pid_t getsid(pid_t pid);

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

       getsid():
           _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       getsid(0) returns the session ID of the calling process.  getsid(p) returns
       the session ID of the process with process ID p.  (The session ID of a
       process is the process group ID of the session leader.)

RETURN VALUE top

       On success, a session ID is returned.  On error, (pid_t) -1 will be
       returned, and errno is set appropriately.

ERRORS top

       EPERM  A process with process ID p exists, but it is not in the same
              session as the calling process, and the implementation considers
              this an error.

       ESRCH  No process with process ID p was found.

VERSIONS top

       This system call is available on Linux since version 2.0.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       Linux does not return EPERM.

SEE ALSO top

       getpgid(2), setsid(2), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                           GETSID(2)


getsockname(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETSOCKNAME(2)               Linux Programmer's Manual              GETSOCKNAME(2)

NAME top

       getsockname - get socket name

SYNOPSIS top

       #include <sys/socket.h>

       int getsockname(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

DESCRIPTION top

       getsockname() returns the current address to which the socket sockfd is
       bound, in the buffer pointed to by addr.  The addrlen argument should be
       initialized to indicate the amount of space (in bytes) pointed to by addr.
       On return it contains the actual size of the socket address.

       The returned address is truncated if the buffer provided is too small; in
       this case, addrlen will return a value greater than was supplied to the
       call.

RETURN VALUE top

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

ERRORS top

       EBADF  The argument sockfd is not a valid descriptor.

       EFAULT The addr argument points to memory not in a valid part of the
              process address space.

       EINVAL addrlen is invalid (e.g., is negative).

       ENOBUFS
              Insufficient resources were available in the system to perform the
              operation.

       ENOTSOCK
              The argument sockfd is a file, not a socket.

CONFORMING TO top

       SVr4, 4.4BSD (the getsockname() function call appeared in 4.2BSD),
       POSIX.1-2001.

NOTES top

       The third argument of getsockname() is in reality an int * (and this is
       what 4.x BSD and libc4 and libc5 have).  Some POSIX confusion resulted in
       the present socklen_t, also used by glibc.  See also accept(2).

SEE ALSO top

       bind(2), socket(2), getifaddrs(3), ip(7), socket(7), unix(7)

COLOPHON top

       This page is part of release 3.45 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-03                      GETSOCKNAME(2)


getsockopt(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETSOCKOPT(2)                Linux Programmer's Manual               GETSOCKOPT(2)

NAME top

       getsockopt, setsockopt - get and set options on sockets

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int getsockopt(int sockfd, int level, int optname,
                      void *optval, socklen_t *optlen);
       int setsockopt(int sockfd, int level, int optname,
                      const void *optval, socklen_t optlen);

DESCRIPTION top

       getsockopt() and setsockopt() manipulate options for the socket referred to
       by the file descriptor sockfd.  Options may exist at multiple protocol
       levels; they are always present at the uppermost socket level.

       When manipulating socket options, the level at which the option resides and
       the name of the option must be specified.  To manipulate options at the
       sockets API level, level is specified as SOL_SOCKET.  To manipulate options
       at any other level the protocol number of the appropriate protocol
       controlling the option is supplied.  For example, to indicate that an
       option is to be interpreted by the TCP protocol, level should be set to the
       protocol number of TCP; see getprotoent(3).

       The arguments optval and optlen are used to access option values for
       setsockopt().  For getsockopt() they identify a buffer in which the value
       for the requested option(s) are to be returned.  For getsockopt(), optlen
       is a value-result argument, initially containing the size of the buffer
       pointed to by optval, and modified on return to indicate the actual size of
       the value returned.  If no option value is to be supplied or returned,
       optval may be NULL.

       Optname and any specified options are passed uninterpreted to the
       appropriate protocol module for interpretation.  The include file
       <sys/socket.h> contains definitions for socket level options, described
       below.  Options at other protocol levels vary in format and name; consult
       the appropriate entries in section 4 of the manual.

       Most socket-level options utilize an int argument for optval.  For
       setsockopt(), the argument should be nonzero to enable a boolean option, or
       zero if the option is to be disabled.

       For a description of the available socket options see socket(7) and the
       appropriate protocol man pages.

RETURN VALUE top

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

ERRORS top

       EBADF     The argument sockfd is not a valid descriptor.

       EFAULT    The address pointed to by optval is not in a valid part of the
                 process address space.  For getsockopt(), this error may also be
                 returned if optlen is not in a valid part of the process address
                 space.

       EINVAL    optlen invalid in setsockopt().  In some cases this error can
                 also occur for an invalid value in optval (e.g., for the
                 IP_ADD_MEMBERSHIP option described in ip(7)).

       ENOPROTOOPT
                 The option is unknown at the level indicated.

       ENOTSOCK  The argument sockfd is a file, not a socket.

CONFORMING TO top

       SVr4, 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001.

NOTES top

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

       The optlen argument of getsockopt() and setsockopt() is in reality an int
       [*] (and this is what 4.x BSD and libc4 and libc5 have).  Some POSIX
       confusion resulted in the present socklen_t, also used by glibc.  See also
       accept(2).

BUGS top

       Several of the socket options should be handled at lower levels of the
       system.

SEE ALSO top

       ioctl(2), socket(2), getprotoent(3), protocols(5), socket(7), tcp(7),
       unix(7)

COLOPHON top

       This page is part of release 3.45 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-03                       GETSOCKOPT(2)


getsubopt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GETSUBOPT(3)                 Linux Programmer's Manual                GETSUBOPT(3)

NAME top

       getsubopt - parse suboption arguments from a string

SYNOPSIS top

       #include <stdlib.h>

       int getsubopt(char **optionp, char * const *tokens, char **valuep);

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

       getsubopt():
           _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       getsubopt() parses the list of comma-separated suboptions provided in
       optionp.  (Such a suboption list is typically produced when getopt(3) is
       used to parse a command line; see for example the -o option of mount(8).)
       Each suboption may include an associated value, which is separated from the
       suboption name by an equal sign.  The following is an example of the kind
       of string that might be passed in optionp:

           ro,name=xyz

       The tokens argument is a pointer to a NULL-terminated array of pointers to
       the tokens that getsubopt() will look for in optionp.  The tokens should be
       distinct, null-terminated strings containing at least one character, with
       no embedded equal signs or commas.

       Each call to getsubopt() returns information about the next unprocessed
       suboption in optionp.  The first equal sign in a suboption (if any) is
       interpreted as a separator between the name and the value of that
       suboption.  The value extends to the next comma, or (for the last
       suboption) to the end of the string.  If the name of the suboption matches
       a known name from tokens, and a value string was found, getsubopt() sets
       *valuep to the address of that string.  The first comma in optionp is
       overwritten with a null byte, so *valuep is precisely the "value string"
       for that suboption.

       If the suboption is recognized, but no value string was found, *valuep is
       set to NULL.

       When getsubopt() returns, optionp points to the next suboption, or to the
       null byte ('\0') at the end of the string if the last suboption was just
       processed.

RETURN VALUE top

       If the first suboption in optionp is recognized, getsubopt() returns the
       index of the matching suboption element in tokens.  Otherwise, -1 is
       returned and *valuep is the entire name[=value] string.

       Since *optionp is changed, the first suboption before the call to
       getsubopt() is not (necessarily) the same as the first suboption after
       getsubopt().

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Since getsubopt() overwrites any commas it finds in the string *optionp,
       that string must be writable; it cannot be a string constant.

EXAMPLE top

       The following program expects suboptions following a "-o" option.

       #define _XOPEN_SOURCE 500
       #include <stdlib.h>
       #include <assert.h>
       #include <stdio.h>

       int main(int argc, char **argv)
       {
           enum {
               RO_OPT = 0,
               RW_OPT,
               NAME_OPT
           };
           char *const token[] = {
               [RO_OPT]   = "ro",
               [RW_OPT]   = "rw",
               [NAME_OPT] = "name",
               NULL
           };
           char *subopts;
           char *value;
           int opt;

           int readonly = 0;
           int readwrite = 0;
           char *name = NULL;
           int errfnd = 0;

           while ((opt = getopt(argc, argv, "o:")) != -1) {
               switch (opt) {
               case 'o':
                   subopts = optarg;
                   while (*subopts != '\0' && !errfnd) {

                   switch (getsubopt(&subopts, token, &value)) {
                   case RO_OPT:
                       readonly = 1;
                       break;

                   case RW_OPT:
                       readwrite = 1;
                       break;

                   case NAME_OPT:
                       if (value == NULL) {
                           fprintf(stderr, "Missing value for "
                                   "suboption '%s'\n", token[NAME_OPT]);
                           errfnd = 1;
                           continue;
                       }

                       name = value;
                       break;

                   default:
                       fprintf(stderr, "No match found "
                               "for token: /%s/\n", value);
                       errfnd = 1;
                       break;
                   }
               }
               if (readwrite && readonly) {
                   fprintf(stderr, "Only one of '%s' and '%s' can be "
                           "specified\n", token[RO_OPT], token[RW_OPT]);
                   errfnd = 1;
               }
               break;

               default:
                   errfnd = 1;
               }
           }

           if (errfnd || argc == 1) {
               fprintf(stderr, "\nUsage: %s -o <suboptstring>\n", argv[0]);
               fprintf(stderr, "suboptions are 'ro', 'rw', "
                       "and 'name=<value>'\n");
               exit(EXIT_FAILURE);
           }

           /* Remainder of program... */

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getopt(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-26                        GETSUBOPT(3)


gettid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETTID(2)                    Linux Programmer's Manual                   GETTID(2)

NAME top

       gettid - get thread identification

SYNOPSIS top

       #include <sys/types.h>

       pid_t gettid(void);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       gettid() returns the caller's thread ID (TID).  In a single-threaded
       process, the thread ID is equal to the process ID (PID, as returned by
       getpid(2)).  In a multithreaded process, all threads have the same PID, but
       each one has a unique TID.  For further details, see the discussion of
       CLONE_THREAD in clone(2).

RETURN VALUE top

       On success, returns the thread ID of the calling process.

ERRORS top

       This call is always successful.

VERSIONS top

       The gettid() system call first appeared on Linux in kernel 2.4.11.

CONFORMING TO top

       gettid() is Linux-specific and should not be used in programs that are
       intended to be portable.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

       The thread ID returned by this call is not the same thing as a POSIX thread
       ID (i.e., the opaque value returned by pthread_self(3)).

SEE ALSO top

       clone(2), fork(2), getpid(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                           GETTID(2)


gettimeofday(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETTIMEOFDAY(2)              Linux Programmer's Manual             GETTIMEOFDAY(2)

NAME top

       gettimeofday, settimeofday - get / set time

SYNOPSIS top

       #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 top

       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 timezone:

           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.  (However, compilation warnings will result if tv is NULL.)

       The use of the timezone structure is obsolete; the tz argument should
       normally be specified as NULL.  (See NOTES below.)

       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_minuteswest field is nonzero.  (The tz_dsttime field should be zero for
       this case.)  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.

RETURN VALUE top

       gettimeofday() and settimeofday() return 0 for success, or -1 for failure
       (in which case errno is set appropriately).

ERRORS top

       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 capability is required.

CONFORMING TO top

       SVr4, 4.3BSD.  POSIX.1-2001 describes gettimeofday() but not
       settimeofday().  POSIX.1-2008 marks gettimeofday() as obsolete,
       recommending the use of clock_gettime(2) instead.

NOTES top

       The time returned by gettimeofday(2) is affected by discontinuous jumps in
       the system time (e.g., if the system administrator manually changes the
       system time).  If you need a monotonically increasing clock, see
       clock_gettime(2).

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

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

       The tz_dsttime field has never been used under Linux.  Thus, the following
       is purely of historic interest.

       On old systems, 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: this 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      /* Romania */
           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.

SEE ALSO top

       date(1), adjtimex(2), clock_gettime(2), time(2), ctime(3), ftime(3),
       timeradd(3), capabilities(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-26                     GETTIMEOFDAY(2)


getumask(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETUMASK(3)                  Linux Programmer's Manual                 GETUMASK(3)

NAME top

       getumask - get file creation mask

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/types.h>
       #include <sys/stat.h>

       mode_t getumask(void);

DESCRIPTION top

       This function returns the current file creation mask.  It is equivalent to

           mode_t getumask(void)
           {
               mode_t mask = umask( 0 );
               umask(mask);
               return mask;
           }

       except that it is documented to be thread-safe (that is, shares a lock with
       the umask(2) library call).

CONFORMING TO top

       This is a vaporware GNU extension.

NOTES top

       This function is documented but not implemented yet in glibc, as at version
       2.9.

SEE ALSO top

       umask(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                         GETUMASK(3)


getutmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETUTMP(3)                   Linux Programmer's Manual                  GETUTMP(3)

NAME top

       getutmp, getutmpx - copy utmp structure to utmpx, and vice versa

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <utmpx.h>

        void getutmp(const struct utmpx *ux, struct utmp *u);
        void getutmpx(const struct utmp *u, struct utmpx *ux);

DESCRIPTION top

       The getutmp() function copies the fields of the utmpx structure pointed to
       by ux to the corresponding fields of the utmp structure pointed to by u.
       The getutmpx() function performs the converse operation.

RETURN VALUE top

       These functions do not return a value.

VERSIONS top

       These functions first appeared in glibc in version 2.1.1.

CONFORMING TO top

       These functions are nonstandard, but appear on a few other systems, such as
       Solaris and NetBSD.

NOTES top

       These functions exist primarily for compatibility with other systems where
       the utmp and utmpx structures contain different fields, or the size of
       corresponding fields differs.  On Linux, the two structures contain the
       same fields, and the fields have the same sizes.

SEE ALSO top

       getutent(3), utmp(5)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10                          GETUTMP(3)


getw(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GETW(3)                      Linux Programmer's Manual                     GETW(3)

NAME top

       getw, putw - input and output of words (ints)

SYNOPSIS top

       #include <stdio.h>

       int getw(FILE *stream);

       int putw(int w, FILE *stream);

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

       getw(), putw():
           Since glibc 2.3.3:
               _SVID_SOURCE || _BSD_SOURCE ||
               (_XOPEN_SOURCE &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600))
           Before glibc 2.3.3:
               _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       getw() reads a word (that is, an int) from stream.  It's provided for
       compatibility with SVr4.  We recommend you use fread(3) instead.

       putw() writes the word w (that is, an int) to stream.  It is provided for
       compatibility with SVr4, but we recommend you use fwrite(3) instead.

RETURN VALUE top

       Normally, getw() returns the word read, and putw() returns 0.  On error,
       they return EOF.

CONFORMING TO top

       SVr4, SUSv2.  Not present in POSIX.1-2001.

BUGS top

       The value returned on error is also a legitimate data value.  ferror(3) can
       be used to distinguish between the two cases.

SEE ALSO top

       ferror(3), fread(3), fwrite(3), getc(3), putc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-26                             GETW(3)


getwchar(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GETWCHAR(3)                  Linux Programmer's Manual                 GETWCHAR(3)

NAME top

       getwchar - read a wide character from standard input

SYNOPSIS top

       #include <wchar.h>

       wint_t getwchar(void);

DESCRIPTION top

       The getwchar() function is the wide-character equivalent of the getchar(3)
       function.  It reads a wide character from stdin and returns it.  If the end
       of stream is reached, or if ferror(stdin) becomes true, it returns WEOF.
       If a wide-character conversion error occurs, it sets errno to EILSEQ and
       returns WEOF.

       For a nonlocking counterpart, see unlocked_stdio(3).

RETURN VALUE top

       The getwchar() function returns the next wide-character from standard
       input, or WEOF.

CONFORMING TO top

       C99.

NOTES top

       The behavior of getwchar() depends on the LC_CTYPE category of the current
       locale.

       It is reasonable to expect that getwchar() will actually read a multibyte
       sequence from standard input and then convert it to a wide character.

SEE ALSO top

       fgetwc(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         GETWCHAR(3)


get_kernel_syms(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GET_KERNEL_SYMS(2)           Linux Programmer's Manual          GET_KERNEL_SYMS(2)

NAME top

       get_kernel_syms - retrieve exported kernel and module symbols

SYNOPSIS top

       #include <linux/module.h>

       int get_kernel_syms(struct kernel_sym *table);

DESCRIPTION top

       Note: This system call is present only in kernels before Linux 2.6.

       If table is NULL, get_kernel_syms() returns the number of symbols available
       for query.  Otherwise it fills in a table of structures:

           struct kernel_sym {
               unsigned long value;
               char          name[60];
           };

       The symbols are interspersed with magic symbols of the form #[22mmodule-name[0m
       with the kernel having an empty name.  The value associated with a symbol
       of this form is the address at which the module is loaded.

       The symbols exported from each module follow their magic module tag and the
       modules are returned in the reverse of the order in which they were loaded.

RETURN VALUE top

       On success, returns the number of symbols copied to table.  On error, -1 is
       returned and errno is set appropriately.

ERRORS top

       There is only one possible error return:

       ENOSYS get_kernel_syms() is not supported in this version of the kernel.

VERSIONS top

       This system call is only present on Linux up until kernel 2.4; it was
       removed in Linux 2.6.

CONFORMING TO top

       get_kernel_syms() is Linux-specific.

BUGS top

       There is no way to indicate the size of the buffer allocated for table.  If
       symbols have been added to the kernel since the program queried for the
       symbol table size, memory will be corrupted.

       The length of exported symbol names is limited to 59 characters.

       Because of these limitations, this system call is deprecated in favor of
       query_module(2) (which is itself nowadays deprecated in favor of other
       interfaces described on its manual page).

SEE ALSO top

       create_module(2), delete_module(2), init_module(2), query_module(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-18                  GET_KERNEL_SYMS(2)


get_mempolicy(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GET_MEMPOLICY(2)             Linux Programmer's Manual            GET_MEMPOLICY(2)

NAME top

       get_mempolicy - retrieve NUMA memory policy for a process

SYNOPSIS top

       #include <numaif.h>

       int get_mempolicy(int *mode, unsigned long *nodemask,
                         unsigned long maxnode, unsigned long addr,
                         unsigned long flags);

       Link with -lnuma.

DESCRIPTION top

       get_mempolicy() retrieves the NUMA policy of the calling process or of a
       memory address, depending on the setting of flags.

       A NUMA machine has different memory controllers with different distances to
       specific CPUs.  The memory policy defines from which node memory is
       allocated for the process.

       If flags is specified as 0, then information about the calling process's
       default policy (as set by set_mempolicy(2)) is returned.  The policy
       returned [mode and nodemask] may be used to restore the process's policy to
       its state at the time of the call to get_mempolicy() using
       set_mempolicy(2).

       If flags specifies MPOL_F_MEMS_ALLOWED (available since Linux 2.6.24), the
       mode argument is ignored and the set of nodes [memories] that the process
       is allowed to specify in subsequent calls to mbind(2) or set_mempolicy(2)
       [in the absence of any mode flags] is returned in nodemask.  It is not
       permitted to combine MPOL_F_MEMS_ALLOWED with either MPOL_F_ADDR or
       MPOL_F_NODE.

       If flags specifies MPOL_F_ADDR, then information is returned about the
       policy governing the memory address given in addr.  This policy may be
       different from the process's default policy if mbind(2) or one of the
       helper functions described in numa(3) has been used to establish a policy
       for the memory range containing addr.

       If the mode argument is not NULL, then get_mempolicy() will store the
       policy mode and any optional mode flags of the requested NUMA policy in the
       location pointed to by this argument.  If nodemask is not NULL, then the
       nodemask associated with the policy will be stored in the location pointed
       to by this argument.  maxnode specifies the number of node IDs that can be
       stored into nodemask--that is, the maximum node ID plus one.  The value
       specified by maxnode is always rounded to a multiple of sizeof(unsigned
       long).

       If flags specifies both MPOL_F_NODE and MPOL_F_ADDR, get_mempolicy() will
       return the node ID of the node on which the address addr is allocated into
       the location pointed to by mode.  If no page has yet been allocated for the
       specified address, get_mempolicy() will allocate a page as if the process
       had performed a read [load] access to that address, and return the ID of
       the node where that page was allocated.

       If flags specifies MPOL_F_NODE, but not MPOL_F_ADDR, and the process's
       current policy is MPOL_INTERLEAVE, then get_mempolicy() will return in the
       location pointed to by a non-NULL mode argument, the node ID of the next
       node that will be used for interleaving of internal kernel pages allocated
       on behalf of the process.  These allocations include pages for memory
       mapped files in process memory ranges mapped using the mmap(2) call with
       the MAP_PRIVATE flag for read accesses, and in memory ranges mapped with
       the MAP_SHARED flag for all accesses.

       Other flag values are reserved.

       For an overview of the possible policies see set_mempolicy(2).

RETURN VALUE top

       On success, get_mempolicy() returns 0; on error, -1 is returned and errno
       is set to indicate the error.

ERRORS top

       EFAULT Part of all of the memory range specified by nodemask and maxnode
              points outside your accessible address space.

       EINVAL The value specified by maxnode is less than the number of node IDs
              supported by the system.  Or flags specified values other than
              MPOL_F_NODE or MPOL_F_ADDR; or flags specified MPOL_F_ADDR and addr
              is NULL, or flags did not specify MPOL_F_ADDR and addr is not NULL.
              Or, flags specified MPOL_F_NODE but not MPOL_F_ADDR and the current
              process policy is not MPOL_INTERLEAVE.  Or, flags specified
              MPOL_F_MEMS_ALLOWED with either MPOL_F_ADDR or MPOL_F_NODE.  (And
              there are other EINVAL cases.)

VERSIONS top

       The get_mempolicy() system call was added to the Linux kernel in version
       2.6.7.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       For information on library support, see numa(7).

SEE ALSO top

       getcpu(2), mbind(2), mmap(2), set_mempolicy(2), numa(3), numa(7),
       numactl(8)

COLOPHON top

       This page is part of release 3.45 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-15                    GET_MEMPOLICY(2)


get_nprocs_conf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | COLOPHON The Linux Programming Interface

GET_NPROCS(3)                Linux Programmer's Manual               GET_NPROCS(3)

NAME top

       get_nprocs, get_nprocs_conf - get number of processors

SYNOPSIS top

       #include <sys/sysinfo.h>

       int get_nprocs(void);
       int get_nprocs_conf(void);

DESCRIPTION top

       The function get_nprocs_conf() returns the number of processors configured
       by the operating system.

       The function get_nprocs() returns the number of processors currently
       available in the system.  This may be less than the number returned by
       get_nprocs_conf() because processors may be offline (e.g., on hotpluggable
       systems).

RETURN VALUE top

       As given in DESCRIPTION.

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       The current implementation of these functions is rather expensive, since
       they open and parse files in the /sys file system each time they are
       called.

       The following sysconf(3) calls make use of the functions documented on this
       page to return the same information.

           np = sysconf(_SC_NPROCESSORS_CONF);     /* processors configured */
           np = sysconf(_SC_NPROCESSORS_ONLN);     /* processors available */

EXAMPLE top

       The following example shows how get_nprocs() and get_nprocs_conf() can be
       used.

       #include <stdio.h>
       #include <sys/sysinfo.h>

       int
       main(int argc, char *argv[])
       {
           printf("This system has %d processors configured and "
                   "%d processors available.\n",
                   get_nprocs_conf(), get_nprocs());
           return 0;
       }

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-20                       GET_NPROCS(3)


get_robust_list(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GET_ROBUST_LIST(2)              Linux System Calls              GET_ROBUST_LIST(2)

NAME top

       get_robust_list, set_robust_list - get/set list of robust futexes

SYNOPSIS top

       #include <linux/futex.h>
       #include <syscall.h>

       long get_robust_list(int pid, struct robust_list_head **head_ptr,
                        size_t *len_ptr);
       long set_robust_list(struct robust_list_head *head, size_t len);

       Note: There are no glibc wrappers for these system calls; see NOTES.

DESCRIPTION top

       The robust futex implementation needs to maintain per-thread lists of
       robust futexes which are unlocked when the thread exits.  These lists are
       managed in user space; the kernel is only notified about the location of
       the head of the list.

       The get_robust_list() system call returns the head of the robust futex list
       of the thread whose thread ID is specified in pid.  If pid is 0, the head
       of the list for the calling thread is returned.  The list head is stored in
       the location pointed to by head_ptr.  The size of the object pointed to by
       **head_ptr is stored in len_ptr.

       The set_robust_list() system call requests the kernel to record the head of
       the list of robust futexes owned by the calling thread.  The head argument
       is the list head to record.  The len argument should be sizeof(*head).

RETURN VALUE top

       The set_robust_list() and get_robust_list() system calls return zero when
       the operation is successful, an error code otherwise.

ERRORS top

       The set_robust_list() system call can fail with the following error:

       EINVAL len does not match the size of structure struct robust_list_head
              expected by kernel.

       The get_robust_list() system call can fail with the following errors:

       EPERM  The calling process does not have permission to see the robust futex
              list of the thread with the thread ID pid, and does not have the
              CAP_SYS_PTRACE capability.

       ESRCH  No thread with the thread ID pid could be found.

       EFAULT The head of the robust futex list can't be stored at the location
              head.

VERSIONS top

       These system calls were added in Linux 2.6.17.  No library support is
       provided; use syscall(2).

NOTES top

       These system calls are not needed by normal applications.  No support for
       them is provided in glibc.  In the unlikely event that you want to call
       them directly, use syscall(2).

       A thread can have only one robust futex list; therefore applications that
       wish to use this functionality should use the robust mutexes provided by
       glibc.

SEE ALSO top

       futex(2)

       Documentation/robust-futexes.txt and Documentation/robust-futex-ABI.txt in
       the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                  GET_ROBUST_LIST(2)


get_thread_area(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GET_THREAD_AREA(2)           Linux Programmer's Manual          GET_THREAD_AREA(2)

NAME top

       get_thread_area - get a thread-local storage (TLS) area

SYNOPSIS top

       #include <linux/unistd.h>
       #include <asm/ldt.h>

       int get_thread_area(struct user_desc *u_info);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       get_thread_area() returns an entry in the current thread's thread-local
       storage (TLS) array.  The index of the entry corresponds to the value of
       u_info->entry_number, passed in by the user.  If the value is in bounds,
       get_thread_area() copies the corresponding TLS entry into the area pointed
       to by u_info.

RETURN VALUE top

       get_thread_area() returns 0 on success.  Otherwise, it returns -1 and sets
       errno appropriately.

ERRORS top

       EFAULT u_info is an invalid pointer.

       EINVAL u_info->entry_number is out of bounds.

VERSIONS top

       A version of get_thread_area() first appeared in Linux 2.5.32.

CONFORMING TO top

       get_thread_area() is Linux-specific and should not be used in programs that
       are intended to be portable.

NOTES top

       Glibc does not provide a wrapper for this system call, since it is
       generally intended only for use by threading libraries.  In the unlikely
       event that you want to call it directly, use syscall(2).

SEE ALSO top

       modify_ldt(2), set_thread_area(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                  GET_THREAD_AREA(2)


libc(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

LIBC(7)                      Linux Programmer's Manual                     LIBC(7)

NAME top

       libc - overview of standard C libraries on Linux

DESCRIPTION top

       The term "libc" is commonly used as a shorthand for the "standard C
       library", a library of standard functions that can be used by all C
       programs (and sometimes by programs in other languages).  Because of some
       history (see below), use of the term "libc" to refer to the standard C
       library is somewhat ambiguous on Linux.

glibc

       By far the most widely used C library on Linux is the GNU C Library
       <http://www.gnu.org/software/libc/>, often referred to as glibc.  This is
       the C library that is nowadays used in all major Linux distributions.  It
       is also the C library whose details are documented in the relevant pages of
       the man-pages project (primarily in Section 3 of the manual).  Documenta-
       tion of glibc is also available in the glibc manual, available via the com-
       mand info libc.  Release 1.0 of glibc was made in September 1992.  (There
       were earlier 0.x releases.)  The next major release of glibc was 2.0, at
       the beginning of 1997.

       The pathname /lib/libc.so.6 (or something similar) is normally a symbolic
       link that points to the location of the glibc library, and executing this
       pathname will cause glibc to display various information about the version
       installed on your system.

Linux libc

       In the early to mid 1990s, there was for a while Linux libc, a fork of
       glibc 1.x created by Linux developers who felt that glibc development at
       the time was not sufficing for the needs of Linux.  Often, this library was
       referred to (ambiguously) as just "libc".  Linux libc released major ver-
       sions 2, 3, 4, and 5 (as well as many minor versions of those releases).
       For a while, Linux libc was the standard C library in many Linux distribu-
       tions.  However, notwithstanding the original motivations of the Linux libc
       effort, by the time glibc 2.0 was released, it was clearly superior to
       Linux libc, and all major Linux distributions that had been using Linux
       libc soon switched back to glibc.  (Since this switch occurred over a
       decade ago, man-pages no longer takes care to document Linux libc details.
       Nevertheless, the history is visible in vestiges of information about Linux
       libc that remain in some manual pages, in particular, references to libc4
       and libc5.)

Other C libraries

       There are various other less widely used C libraries for Linux.  These
       libraries are generally smaller than glibc, both in terms of features and
       memory footprint, and often intended for building small binaries, perhaps
       targeted at development for embedded Linux systems.  Among such libraries
       are uClibc (http://www.uclibc.org/) and dietlibc
       (http://www.fefe.de/dietlibc/).  Details of these libraries are generally
       not covered by the man-pages project.

SEE ALSO top

       syscalls(2), feature_test_macros(7), man-pages(7), standards(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                             LIBC(7)


glob(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GLOB(3)                      Linux Programmer's Manual                     GLOB(3)

NAME top

       glob, globfree - find pathnames matching a pattern, free memory from glob()

SYNOPSIS top

       #include <glob.h>

       int glob(const char *pattern, int flags,
                int (*errfunc) (const char *epath, int eerrno),
                glob_t *pglob);
       void globfree(glob_t *pglob);

DESCRIPTION top

       The glob() function searches for all the pathnames matching pattern
       according to the rules used by the shell (see glob(7)).  No tilde expansion
       or parameter substitution is done; if you want these, use wordexp(3).

       The globfree() function frees the dynamically allocated storage from an
       earlier call to glob().

       The results of a glob() call are stored in the structure pointed to by
       pglob.  This structure is of type glob_t (declared in <glob.h>) and
       includes the following elements defined by POSIX.2 (more may be present as
       an extension):

           typedef struct {
               size_t   gl_pathc;    /* Count of paths matched so far  */
               char   **gl_pathv;    /* List of matched pathnames.  */
               size_t   gl_offs;     /* Slots to reserve in gl_pathv.  */
           } glob_t;

       Results are stored in dynamically allocated storage.

       The argument flags is made up of the bitwise OR of zero or more the
       following symbolic constants, which modify the behavior of glob():

       GLOB_ERR
              Return upon a read error (because a directory does not have read
              permission, for example).  By default, glob() attempts carry on
              despite errors, reading all of the directories that it can.

       GLOB_MARK
              Append a slash to each path which corresponds to a directory.

       GLOB_NOSORT
              Don't sort the returned pathnames.  The only reason to do this is to
              save processing time.  By default, the returned pathnames are
              sorted.

       GLOB_DOOFFS
              Reserve pglob->gl_offs slots at the beginning of the list of strings
              in pglob->pathv.  The reserved slots contain NULL pointers.

       GLOB_NOCHECK
              If no pattern matches, return the original pattern.  By default,
              glob() returns GLOB_NOMATCH if there are no matches.

       GLOB_APPEND
              Append the results of this call to the vector of results returned by
              a previous call to glob().  Do not set this flag on the first
              invocation of glob().

       GLOB_NOESCAPE
              Don't allow backslash ('\') to be used as an escape character.
              Normally, a backslash can be used to quote the following character,
              providing a mechanism to turn off the special meaning
              metacharacters.

       flags may also include any of the following, which are GNU extensions and
       not defined by POSIX.2:

       GLOB_PERIOD
              Allow a leading period to be matched by metacharacters.  By default,
              metacharacters can't match a leading period.

       GLOB_ALTDIRFUNC
              Use alternative functions pglob->gl_closedir, pglob->gl_readdir,
              pglob->gl_opendir, pglob->gl_lstat, and pglob->gl_stat for file
              system access instead of the normal library functions.

       GLOB_BRACE
              Expand csh(1) style brace expressions of the form {a,b}.  Brace
              expressions can be nested.  Thus, for example, specifying the
              pattern "{foo/{,cat,dog},bar}" would return the same results as four
              separate glob() calls using the strings: "foo/", "foo/cat",
              "foo/dog", and "bar".

       GLOB_NOMAGIC
              If the pattern contains no metacharacters then it should be returned
              as the sole matching word, even if there is no file with that name.

       GLOB_TILDE
              Carry out tilde expansion.  If a tilde ('~') is the only character
              in the pattern, or an initial tilde is followed immediately by a
              slash ('/'), then the home directory of the caller is substituted
              for the tilde.  If an initial tilde is followed by a username (e.g.,
              "~andrea/bin"), then the tilde and username are substituted by the
              home directory of that user.  If the username is invalid, or the
              home directory cannot be determined, then no substitution is
              performed.

       GLOB_TILDE_CHECK
              This provides behavior similar to that of GLOB_TILDE.  The
              difference is that if the username is invalid, or the home directory
              cannot be determined, then instead of using the pattern itself as
              the name, glob() returns GLOB_NOMATCH to indicate an error.

       GLOB_ONLYDIR
              This is a hint to glob() that the caller is interested only in
              directories that match the pattern.  If the implementation can
              easily determine file-type information, then nondirectory files are
              not returned to the caller.  However, the caller must still check
              that returned files are directories.  (The purpose of this flag is
              merely to optimize performance when the caller is interested only in
              directories.)

       If errfunc is not NULL, it will be called in case of an error with the
       arguments epath, a pointer to the path which failed, and eerrno, the value
       of errno as returned from one of the calls to opendir(3), readdir(3), or
       stat(2).  If errfunc returns nonzero, or if GLOB_ERR is set, glob() will
       terminate after the call to errfunc.

       Upon successful return, pglob->gl_pathc contains the number of matched
       pathnames and pglob->gl_pathv contains a pointer to the list of pointers to
       matched pathnames.  The list of pointers is terminated by a NULL pointer.

       It is possible to call glob() several times.  In that case, the GLOB_APPEND
       flag has to be set in flags on the second and later invocations.

       As a GNU extension, pglob->gl_flags is set to the flags specified, ored
       with GLOB_MAGCHAR if any metacharacters were found.

RETURN VALUE top

       On successful completion, glob() returns zero.  Other possible returns are:

       GLOB_NOSPACE
              for running out of memory,

       GLOB_ABORTED
              for a read error, and

       GLOB_NOMATCH
              for no found matches.

CONFORMING TO top

       POSIX.2, POSIX.1-2001.

NOTES top

       The structure elements gl_pathc and gl_offs are declared as size_t in glibc
       2.1, as they should be according to POSIX.2, but are declared as int in
       libc4, libc5 and glibc 2.0.

BUGS top

       The glob() function may fail due to failure of underlying function calls,
       such as malloc(3) or opendir(3).  These will store their error code in
       errno.

EXAMPLE top

       One example of use is the following code, which simulates typing

           ls -l *.c ../*.c

       in the shell:

           glob_t globbuf;

           globbuf.gl_offs = 2;
           glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
           glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
           globbuf.gl_pathv[0] = "ls";
           globbuf.gl_pathv[1] = "-l";
           execvp("ls", &globbuf.gl_pathv[0]);

SEE ALSO top

       ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3),
       readdir(3), wordexp(3), glob(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-10-10                             GLOB(3)


glob(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GLOB(7)                      Linux Programmer's Manual                     GLOB(7)

NAME top

       glob - globbing pathnames

DESCRIPTION top

       Long ago, in UNIX V6, there was a program /etc/glob that would expand
       wildcard patterns.  Soon afterward this became a shell built-in.

       These days there is also a library routine glob(3) that will perform this
       function for a user program.

       The rules are as follows (POSIX.2, 3.13).

Wildcard Matching

       A string is a wildcard pattern if it contains one of the characters '?',
       '*' or '['.  Globbing is the operation that expands a wildcard pattern into
       the list of pathnames matching the pattern.  Matching is defined by:

       A '?' (not between brackets) matches any single character.

       A '*' (not between brackets) matches any string, including the empty
       string.

       Character classes

       An expression "[...]" where the first character after the leading '[' is
       not an '!' matches a single character, namely any of the characters
       enclosed by the brackets.  The string enclosed by the brackets cannot be
       empty; therefore ']' can be allowed between the brackets, provided that it
       is the first character.  (Thus, "[][!]" matches the three characters '[',
       ']' and '!'.)

       Ranges

       There is one special convention: two characters separated by '-' denote a
       range.  (Thus, "[A-Fa-f0-9]" is equivalent to "[ABCDEFabcdef0123456789]".)
       One may include '-' in its literal meaning by making it the first or last
       character between the brackets.  (Thus, "[]-]" matches just the two
       characters ']' and '-', and "[--0]" matches the three characters '-', '.',
       '0', since '/' cannot be matched.)

       Complementation

       An expression "[!...]" matches a single character, namely any character
       that is not matched by the expression obtained by removing the first '!'
       from it.  (Thus, "[!]a-]" matches any single character except ']', 'a' and
       '-'.)

       One can remove the special meaning of '?', '*' and '[' by preceding them by
       a backslash, or, in case this is part of a shell command line, enclosing
       them in quotes.  Between brackets these characters stand for themselves.
       Thus, "[[?*\]" matches the four characters '[', '?', '*' and '\'.

Pathnames

       Globbing is applied on each of the components of a pathname separately.  A
       '/' in a pathname cannot be matched by a '?' or '*' wildcard, or by a range
       like "[.-0]".  A range cannot contain an explicit '/' character; this would
       lead to a syntax error.

       If a filename starts with a '.', this character must be matched explicitly.
       (Thus, rm * will not remove .profile, and tar c * will not archive all your
       files; tar c . is better.)

Empty Lists

       The nice and simple rule given above: "expand a wildcard pattern into the
       list of matching pathnames" was the original UNIX definition.  It allowed
       one to have patterns that expand into an empty list, as in

           xv -wait 0 *.gif *.jpg

       where perhaps no *.gif files are present (and this is not an error).
       However, POSIX requires that a wildcard pattern is left unchanged when it
       is syntactically incorrect, or the list of matching pathnames is empty.
       With bash one can force the classical behavior using this command:

           shopt -s nullglob

       (Similar problems occur elsewhere.  E.g., where old scripts have

           rm `find . -name "*~"`

       new scripts require

           rm -f nosuchfile `find . -name "*~"`

       to avoid error messages from rm called with an empty argument list.)

NOTES top

Regular expressions

       Note that wildcard patterns are not regular expressions, although they are
       a bit similar.  First of all, they match filenames, rather than text, and
       secondly, the conventions are not the same: for example, in a regular
       expression '*' means zero or more copies of the preceding thing.

       Now that regular expressions have bracket expressions where the negation is
       indicated by a '^', POSIX has declared the effect of a wildcard pattern
       "[^...]" to be undefined.

Character classes and Internationalization

       Of course ranges were originally meant to be ASCII ranges, so that "[ -%]"
       stands for "[ !"#$%]" and "[a-z]" stands for "any lowercase letter".  Some
       UNIX implementations generalized this so that a range X-Y stands for the
       set of characters with code between the codes for X and for Y.  However,
       this requires the user to know the character coding in use on the local
       system, and moreover, is not convenient if the collating sequence for the
       local alphabet differs from the ordering of the character codes.
       Therefore, POSIX extended the bracket notation greatly, both for wildcard
       patterns and for regular expressions.  In the above we saw three types of
       items that can occur in a bracket expression: namely (i) the negation, (ii)
       explicit single characters, and (iii) ranges.  POSIX specifies ranges in an
       internationally more useful way and adds three more types:

       (iii) Ranges X-Y comprise all characters that fall between X and Y
       (inclusive) in the current collating sequence as defined by the LC_COLLATE
       category in the current locale.

       (iv) Named character classes, like

       [:alnum:]  [:alpha:]  [:blank:]  [:cntrl:]
       [:digit:]  [:graph:]  [:lower:]  [:print:]
       [:punct:]  [:space:]  [:upper:]  [:xdigit:]

       so that one can say "[[:lower:]]" instead of "[a-z]", and have things work
       in Denmark, too, where there are three letters past 'z' in the alphabet.
       These character classes are defined by the LC_CTYPE category in the current
       locale.

       (v) Collating symbols, like "[.ch.]" or "[.a-acute.]", where the string
       between "[." and ".]" is a collating element defined for the current
       locale.  Note that this may be a multicharacter element.

       (vi) Equivalence class expressions, like "[=a=]", where the string between
       "[=" and "=]" is any collating element from its equivalence class, as
       defined for the current locale.  For example, "[[=a=]]" might be equivalent
       to "[a'a`a"a^a]", that is, to "[a[.a-acute.][.a-grave.][.a-umlaut.][.a-
       circumflex.]]".

SEE ALSO          top
       sh(1), fnmatch(3), glob(3), locale(7), regex(7)

COLOPHON          top
       This page is part of release 3.45 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                               2012-07-28                             GLOB(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


makedev(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MAKEDEV(3)                   Linux Programmer's Manual                  MAKEDEV(3)

NAME top

       makedev, major, minor - manage a device number

SYNOPSIS top

       #define _BSD_SOURCE             /* See feature_test_macros(7) */
       #include <sys/types.h>

       dev_t makedev(int maj, int min);

       unsigned int major(dev_t dev);
       unsigned int minor(dev_t dev);

DESCRIPTION top

       A device ID consists of two parts: a major ID, identifying the class of the
       device, and a minor ID, identifying a specific instance of a device in that
       class.  A device ID is represented using the type dev_t.

       Given major and minor device IDs, makedev() combines these to produce a
       device ID, returned as the function result.  This device ID can be given to
       mknod(2), for example.

       The major() and minor() functions perform the converse task: given a device
       ID, they return, respectively, the major and minor components.  These
       macros can be useful to, for example, decompose the device IDs in the
       structure returned by stat(2).

CONFORMING TO top

       The makedev(), major(), and minor() functions are not specified in POSIX.1,
       but are present on many other systems.

NOTES top

       These interfaces are defined as macros.  Since glibc 2.3.3, they have been
       aliases for three GNU-specific functions: gnu_dev_makedev(),
       gnu_dev_major(), and gnu_dev_minor().  The latter names are exported, but
       the traditional names are more portable.

SEE ALSO top

       mknod(2), stat(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-10                          MAKEDEV(3)


gnu_get_libc_version(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

GNU_GET_LIBC_VERSION(3)      Linux Programmer's Manual     GNU_GET_LIBC_VERSION(3)

NAME top

       gnu_get_libc_version, gnu_get_libc_release - get glibc version and release

SYNOPSIS top

       #include <gnu/libc-version.h>

       const char *gnu_get_libc_version(void);
       const char *gnu_get_libc_release(void);

DESCRIPTION top

       The function gnu_get_libc_version() returns a string that identifies the
       glibc version available on the system.

       The function gnu_get_libc_release() returns a string indicates the release
       status of the glibc version available on the system.  This will be a string
       such as stable.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       These functions are glibc-specific.

EXAMPLE top

       When run, the program below will produce output such as the following:

           $ ./a.out
           GNU libc version: 2.8
           GNU libc release: stable

Program source

       #include <gnu/libc-version.h>
       #include <stdlib.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           printf("GNU libc version: %s\n", gnu_get_libc_version());
           printf("GNU libc release: %s\n", gnu_get_libc_release());
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       confstr(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-26             GNU_GET_LIBC_VERSION(3)


grantpt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

GRANTPT(3)                   Linux Programmer's Manual                  GRANTPT(3)

NAME top

       grantpt - grant access to the slave pseudoterminal

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <stdlib.h>

       int grantpt(int fd);

DESCRIPTION top

       The grantpt() function changes the mode and owner of the slave
       pseudoterminal device corresponding to the master pseudoterminal referred
       to by fd.  The user ID of the slave is set to the real UID of the calling
       process.  The group ID is set to an unspecified value (e.g., tty).  The
       mode of the slave is set to 0620 (crw--w----).

       The behavior of grantpt() is unspecified if a signal handler is installed
       to catch SIGCHLD signals.

RETURN VALUE top

       When successful, grantpt() returns 0.  Otherwise, it returns -1 and sets
       errno appropriately.

ERRORS top

       EACCES The corresponding slave pseudoterminal could not be accessed.

       EBADF  The fd argument is not a valid open file descriptor.

       EINVAL The fd argument is valid but not associated with a master
              pseudoterminal.

VERSIONS top

       grantpt() is provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       This is part of the UNIX 98 pseudoterminal support, see pts(4).  Many
       systems implement this function via a set-user-ID helper binary called
       "pt_chown".  With Linux devpts no such helper binary is required.

SEE ALSO top

       open(2), posix_openpt(3), ptsname(3), unlockpt(3), pts(4), pty(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-06-14                          GRANTPT(3)


group(5) - Linux manual page

NAME | DESCRIPTION | FILES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

GROUP(5)                     Linux Programmer's Manual                    GROUP(5)

NAME top

       group - user group file

DESCRIPTION top

       The /etc/group file is a text file that defines the groups on the system.
       There is one entry per line, with the following format:

              group_name:password:GID:user_list

       The fields are as follows:

       group_name  the name of the group.

       password    the (encrypted) group password.  If this field is empty, no
                   password is needed.

       GID         the numeric group ID.

       user_list   a list of the usernames that are members of this group,
                   separated by commas.

FILES top

       /etc/group

BUGS top

       As the 4.2BSD initgroups(3) man page says: No-one seems to keep /etc/group
       up-to-date.

SEE ALSO top

       login(1), newgrp(1), getgrent(3), getgrnam(3), passwd(5)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-21                            GROUP(5)


gsignal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

GSIGNAL(3)                   Linux Programmer's Manual                  GSIGNAL(3)

NAME top

       gsignal, ssignal - software signal facility

SYNOPSIS top

       #include <signal.h>

       typedef void (*sighandler_t)(int);

       int gsignal(int signum);

       sighandler_t ssignal(int signum, sighandler_t action);

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

       gsignal(), ssignal(): _SVID_SOURCE

DESCRIPTION top

       Don't use these functions under Linux.  Due to a historical mistake, under
       Linux these functions are aliases for raise(3) and signal(2), respectively.

       Elsewhere, on System V-like systems, these functions implement software
       signaling, entirely independent of the classical signal(2) and kill(2)
       functions.  The function ssignal() defines the action to take when the
       software signal with number signum is raised using the function gsignal(),
       and returns the previous such action or SIG_DFL.  The function gsignal()
       does the following: if no action (or the action SIG_DFL) was specified for
       signum, then it does nothing and returns 0.  If the action SIG_IGN was
       specified for signum, then it does nothing and returns 1.  Otherwise, it
       resets the action to SIG_DFL and calls the action function with argument
       signum, and returns the value returned by that function.  The range of
       possible values signum varies (often 1-15 or 1-17).

CONFORMING TO top

       These functions are available under AIX, DG/UX, HP-UX, SCO, Solaris, Tru64.
       They are called obsolete under most of these systems, and are broken under
       Linux libc and glibc.  Some systems also have gsignal_r() and ssignal_r().

SEE ALSO top

       kill(2), signal(2), raise(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-07-26                          GSIGNAL(3)


hash(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

HASH(3)                      Linux Programmer's Manual                     HASH(3)

NAME top

       hash - hash database access method

SYNOPSIS top

       #include <sys/types.h>
       #include <db.h>

DESCRIPTION top

       Note well: This page documents interfaces provided in glibc up until
       version 2.1.  Since version 2.2, glibc no longer provides these interfaces.
       Probably, you are looking for the APIs provided by the libdb library
       instead.

       The routine dbopen(3) is the library interface to database files.  One of
       the supported file formats is hash files.  The general description of the
       database access methods is in dbopen(3), this manual page describes only
       the hash specific information.

       The hash data structure is an extensible, dynamic hashing scheme.

       The access method specific data structure provided to dbopen(3) is defined
       in the <db.h> include file as follows:

           typedef struct {
               unsigned int       bsize;
               unsigned int       ffactor;
               unsigned int       nelem;
               unsigned int       cachesize;
               uint32_t         (*hash)(const void *, size_t);
               int         lorder;
           } HASHINFO;

       The elements of this structure are as follows:

       bsize     defines the hash table bucket size, and is, by default, 256
                 bytes.  It may be preferable to increase the page size for disk-
                 resident tables and tables with large data items.

       ffactor   indicates a desired density within the hash table.  It is an
                 approximation of the number of keys allowed to accumulate in any
                 one bucket, determining when the hash table grows or shrinks.
                 The default value is 8.

       nelem     is an estimate of the final size of the hash table.  If not set
                 or set too low, hash tables will expand gracefully as keys are
                 entered, although a slight performance degradation may be
                 noticed.  The default value is 1.

       cachesize is the suggested maximum size, in bytes, of the memory cache.
                 This value is only advisory, and the access method will allocate
                 more memory rather than fail.

       hash      is a user-defined hash function.  Since no hash function performs
                 equally well on all possible data, the user may find that the
                 built-in hash function does poorly on a particular data set.  A
                 user-specified hash functions must take two arguments (a pointer
                 to a byte string and a length) and return a 32-bit quantity to be
                 used as the hash value.

       lorder    is the byte order for integers in the stored database metadata.
                 The number should represent the order as an integer; for example,
                 big endian order would be the number 4,321.  If lorder is 0 (no
                 order is specified) the current host order is used.  If the file
                 already exists, the specified value is ignored and the value
                 specified when the tree was created is used.

       If the file already exists (and the O_TRUNC flag is not specified), the
       values specified for bsize, ffactor, lorder, and nelem are ignored and the
       values specified when the tree was created are used.

       If a hash function is specified, hash_open will attempt to determine if the
       hash function specified is the same as the one with which the database was
       created, and will fail if it is not.

       Backward-compatible interfaces to the routines described in dbm(3), and
       ndbm(3) are provided, however these interfaces are not compatible with
       previous file formats.

ERRORS top

       The hash access method routines may fail and set errno for any of the
       errors specified for the library routine dbopen(3).

BUGS top

       Only big and little endian byte order are supported.

SEE ALSO top

       btree(3), dbopen(3), mpool(3), recno(3)

       Dynamic Hash Tables, Per-Ake Larson, Communications of the ACM, April 1988.

       A New Hash Package for UNIX, Margo Seltzer, USENIX Proceedings, Winter
       1991.

COLOPHON top

       This page is part of release 3.45 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/.

4.4 Berkeley Distribution           2012-04-23                             HASH(3)


hsearch(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

HSEARCH(3)                   Linux Programmer's Manual                  HSEARCH(3)

NAME top

       hcreate,  hdestroy,  hsearch, hcreate_r, hdestroy_r, hsearch_r - hash table
       management

SYNOPSIS top

       #include <search.h>

       int hcreate(size_t nel);

       ENTRY *hsearch(ENTRY item, ACTION action);

       void hdestroy(void);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <search.h>

       int hcreate_r(size_t nel, struct hsearch_data *htab);

       int hsearch_r(ENTRY item, ACTION action, ENTRY **retval,
                     struct hsearch_data *htab);

       void hdestroy_r(struct hsearch_data *htab);

DESCRIPTION top

       The three functions hcreate(), hsearch(), and hdestroy() allow the caller
       to create and manage a hash search table containing entries consisting of a
       key (a string) and associated data.  Using these functions, only one hash
       table can be used at a time.

       The three functions hcreate_r(), hsearch_r(), hdestroy_r() are reentrant
       versions that allow a program to use more than one hash search table at the
       same time.  The last argument, htab, points to a structure that describes
       the table on which the function is to operate.  The programmer should treat
       this structure as opaque (i.e., do not attempt to directly access or modify
       the fields in this structure).

       First a hash table must be created using hcreate().  The argument nel
       specifies the maximum number of entries in the table.  (This maximum cannot
       be changed later, so choose it wisely.)  The implementation may adjust this
       value upward to improve the performance of the resulting hash table.

       The hcreate_r() function performs the same task as hcreate(), but for the
       table described by the structure *htab.  The structure pointed to by htab
       must be zeroed before the first call to hcreate_r().

       The function hdestroy() frees the memory occupied by the hash table that
       was created by hcreate().  After calling hdestroy() a new hash table can be
       created using hcreate().  The hdestroy_r() function performs the analogous
       task for a hash table described by *htab, which was previously created
       using hcreate_r().

       The hsearch() function searches the hash table for an item with the same
       key as item (where "the same" is determined using strcmp(3)), and if
       successful returns a pointer to it.

       The argument item is of type ENTRY, which is defined in <search.h> as
       follows:

           typedef struct entry {
               char *key;
               void *data;
           } ENTRY;

       The field key points to a null-terminated string which is the search key.
       The field data points to data that is associated with that key.

       The argument action determines what hsearch() does after an unsuccessful
       search.  This argument must either have the value ENTER, meaning insert a
       copy of item (and return a pointer to the new hash table entry as the
       function result), or the value FIND, meaning that NULL should be returned.
       (If action is FIND, then data is ignored.)

       The hsearch_r() function is like hsearch() but operates on the hash table
       described by *htab.  The hsearch_r() function differs from hsearch() in
       that a pointer to the found item is returned in *retval, rather than as the
       function result.

RETURN VALUE top

       hcreate() and hcreate_r() return nonzero on success.  They return 0 on
       error.

       On success, hsearch() returns a pointer to an entry in the hash table.
       hsearch() returns NULL on error, that is, if action is ENTER and the hash
       table is full, or action is FIND and item cannot be found in the hash
       table.  hsearch_r() returns nonzero on success, and 0 on error.

ERRORS top

       hcreate_r() and hdestroy_r() can fail for the following reasons:

       EINVAL htab is NULL.

       hsearch() and hsearch_r() can fail for the following reasons:

       ENOMEM action was ENTER, key was not found in the table, and there was no
              room in the table to add a new entry.

       ESRCH  action was FIND, and key was not found in the table.

       POSIX.1-2001 only specifies the ENOMEM error.

CONFORMING TO top

       The functions hcreate(), hsearch(), and hdestroy() are from SVr4, and are
       described in POSIX.1-2001.  The functions hcreate_r(), hsearch_r(), and
       hdestroy_r() are GNU extensions.

NOTES top

       Hash table implementations are usually more efficient when the table
       contains enough free space to minimize collisions.  Typically, this means
       that nel should be at least 25% larger than the maximum number of elements
       that the caller expects to store in the table.

       The hdestroy() and hdestroy_r() functions do not free the buffers pointed
       to by the key and data elements of the hash table entries.  (It can't do
       this because it doesn't know whether these buffers were allocated
       dynamically.)  If these buffers need to be freed (perhaps because the
       program is repeatedly creating and destroying hash tables, rather than
       creating a single table whose lifetime matches that of the program), then
       the program must maintain bookkeeping data structures that allow it to free
       them.

BUGS top

       SVr4 and POSIX.1-2001 specify that action is significant only for
       unsuccessful searches, so that an ENTER should not do anything for a
       successful search.  In libc and glibc (before version 2.3), the
       implementation violates the specification, updating the data for the given
       key in this case.

       Individual hash table entries can be added, but not deleted.

EXAMPLE top

       The following program inserts 24 items into a hash table, then prints some
       of them.

       #include <stdio.h>
       #include <stdlib.h>
       #include <search.h>

       char *data[] = { "alpha", "bravo", "charlie", "delta",
            "echo", "foxtrot", "golf", "hotel", "india", "juliet",
            "kilo", "lima", "mike", "november", "oscar", "papa",
            "quebec", "romeo", "sierra", "tango", "uniform",
            "victor", "whisky", "x-ray", "yankee", "zulu"
       };

       int
       main(void)
       {
           ENTRY e, *ep;
           int i;

           hcreate(30);

           for (i = 0; i < 24; i++) {
               e.key = data[i];
               /* data is just an integer, instead of a
                  pointer to something */
               e.data = (void *) i;
               ep = hsearch(e, ENTER);
               /* there should be no failures */
               if (ep == NULL) {
                   fprintf(stderr, "entry failed\n");
                   exit(EXIT_FAILURE);
               }
           }

           for (i = 22; i < 26; i++) {
               /* print two entries from the table, and
                  show that two are not in the table */
               e.key = data[i];
               ep = hsearch(e, FIND);
               printf("%9.9s -> %9.9s:%d\n", e.key,
                      ep ? ep->key : "NULL", ep ? (int)(ep->data) : 0);
           }
           hdestroy();
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       bsearch(3), lsearch(3), malloc(3), tsearch(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-10                          HSEARCH(3)


hd(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

HD(4)                        Linux Programmer's Manual                       HD(4)

NAME top

       hd - MFM/IDE hard disk devices

DESCRIPTION top

       The hd* devices are block devices to access MFM/IDE hard disk drives in raw
       mode.  The master drive on the primary IDE controller (major device number
       3) is hda; the slave drive is hdb.  The master drive of the second
       controller (major device number 22) is hdc and the slave hdd.

       General IDE block device names have the form hdX, or hdXP, where X is a
       letter denoting the physical drive, and P is a number denoting the
       partition on that physical drive.  The first form, hdX, is used to address
       the whole drive.  Partition numbers are assigned in the order the
       partitions are discovered, and only nonempty, nonextended partitions get a
       number.  However, partition numbers 1-4 are given to the four partitions
       described in the MBR (the "primary" partitions), regardless of whether they
       are unused or extended.  Thus, the first logical partition will be hdX5.
       Both DOS-type partitioning and BSD-disklabel partitioning are supported.
       You can have at most 63 partitions on an IDE disk.

       For example, /dev/hda refers to all of the first IDE drive in the system;
       and /dev/hdb3 refers to the third DOS "primary" partition on the second
       one.

       They are typically created by:

              mknod -m 660 /dev/hda b 3 0
              mknod -m 660 /dev/hda1 b 3 1
              mknod -m 660 /dev/hda2 b 3 2
              ...
              mknod -m 660 /dev/hda8 b 3 8
              mknod -m 660 /dev/hdb b 3 64
              mknod -m 660 /dev/hdb1 b 3 65
              mknod -m 660 /dev/hdb2 b 3 66
              ...
              mknod -m 660 /dev/hdb8 b 3 72
              chown root:disk /dev/hd*

FILES top

       /dev/hd*

SEE ALSO top

       chown(1), mknod(1), sd(4), mount(8)

COLOPHON top

       This page is part of release 3.45 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                               1992-12-17                               HD(4)


hier(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

HIER(7)                      Linux Programmer's Manual                     HIER(7)

NAME top

       hier - description of the file system hierarchy

DESCRIPTION top

       A typical Linux system has, among others, the following directories:

       /      This is the root directory.  This is where the whole tree starts.

       /bin   This directory contains executable programs which are needed in
              single user mode and to bring the system up or repair it.

       /boot  Contains static files for the boot loader.  This directory only
              holds the files which are needed during the boot process.  The map
              installer and configuration files should go to /sbin and /etc.

       /dev   Special or device files, which refer to physical devices.  See
              mknod(1).

       /etc   Contains configuration files which are local to the machine.  Some
              larger software packages, like X11, can have their own
              subdirectories below /etc.  Site-wide configuration files may be
              placed here or in /usr/etc.  Nevertheless, programs should always
              look for these files in /etc and you may have links for these files
              to /usr/etc.

       /etc/opt
              Host-specific configuration files for add-on applications installed
              in /opt.

       /etc/sgml
              This directory contains the configuration files for SGML and XML
              (optional).

       /etc/skel
              When a new user account is created, files from this directory are
              usually copied into the user's home directory.

       /etc/X11
              Configuration files for the X11 window system (optional).

       /home  On machines with home directories for users, these are usually
              beneath this directory, directly or not.  The structure of this
              directory depends on local administration decisions.

       /lib   This directory should hold those shared libraries that are necessary
              to boot the system and to run the commands in the root file system.

       /media This directory contains mount points for removable media such as CD
              and DVD disks or USB sticks.

       /mnt   This directory is a mount point for a temporarily mounted file
              system.  In some distributions, /mnt contains subdirectories
              intended to be used as mount points for several temporary file
              systems.

       /opt   This directory should contain add-on packages that contain static
              files.

       /proc  This is a mount point for the proc file system, which provides
              information about running processes and the kernel.  This pseudo-
              file system is described in more detail in proc(5).

       /root  This directory is usually the home directory for the root user
              (optional).

       /sbin  Like /bin, this directory holds commands needed to boot the system,
              but which are usually not executed by normal users.

       /srv   This directory contains site-specific data that is served by this
              system.

       /tmp   This directory contains temporary files which may be deleted with no
              notice, such as by a regular job or at system boot up.

       /usr   This directory is usually mounted from a separate partition.  It
              should hold only sharable, read-only data, so that it can be mounted
              by various machines running Linux.

       /usr/X11R6
              The X-Window system, version 11 release 6 (optional).

       /usr/X11R6/bin
              Binaries which belong to the X-Window system; often, there is a
              symbolic link from the more traditional /usr/bin/X11 to here.

       /usr/X11R6/lib
              Data files associated with the X-Window system.

       /usr/X11R6/lib/X11
              These contain miscellaneous files needed to run X;  Often, there is
              a symbolic link from /usr/lib/X11 to this directory.

       /usr/X11R6/include/X11
              Contains include files needed for compiling programs using the X11
              window system.  Often, there is a symbolic link from
              /usr/include/X11 to this directory.

       /usr/bin
              This is the primary directory for executable programs.  Most
              programs executed by normal users which are not needed for booting
              or for repairing the system and which are not installed locally
              should be placed in this directory.

       /usr/bin/X11
              is the traditional place to look for X11 executables; on Linux, it
              usually is a symbolic link to /usr/X11R6/bin.

       /usr/dict
              Replaced by /usr/share/dict.

       /usr/doc
              Replaced by /usr/share/doc.

       /usr/etc
              Site-wide configuration files to be shared between several machines
              may be stored in this directory.  However, commands should always
              reference those files using the /etc directory.  Links from files in
              /etc should point to the appropriate files in /usr/etc.

       /usr/games
              Binaries for games and educational programs (optional).

       /usr/include
              Include files for the C compiler.

       /usr/include/X11
              Include files for the C compiler and the X-Window system.  This is
              usually a symbolic link to /usr/X11R6/include/X11.

       /usr/include/asm
              Include files which declare some assembler functions.  This used to
              be a symbolic link to /usr/src/linux/include/asm.

       /usr/include/linux
              This contains information which may change from system release to
              system release and used to be a symbolic link to
              /usr/src/linux/include/linux to get at operating system specific
              information.

              (Note that one should have include files there that work correctly
              with the current libc and in user space.  However, Linux kernel
              source is not designed to be used with user programs and does not
              know anything about the libc you are using.  It is very likely that
              things will break if you let /usr/include/asm and /usr/include/linux
              point at a random kernel tree.  Debian systems don't do this and use
              headers from a known good kernel version, provided in the libc*-dev
              package.)

       /usr/include/g++
              Include files to use with the GNU C++ compiler.

       /usr/lib
              Object libraries, including dynamic libraries, plus some executables
              which usually are not invoked directly.  More complicated programs
              may have whole subdirectories there.

       /usr/lib/X11
              The usual place for data files associated with X programs, and
              configuration files for the X system itself.  On Linux, it usually
              is a symbolic link to /usr/X11R6/lib/X11.

       /usr/lib/gcc-lib
              contains executables and include files for the GNU C compiler,
              gcc(1).

       /usr/lib/groff
              Files for the GNU groff document formatting system.

       /usr/lib/uucp
              Files for uucp(1).

       /usr/local
              This is where programs which are local to the site typically go.

       /usr/local/bin
              Binaries for programs local to the site.

       /usr/local/doc
              Local documentation.

       /usr/local/etc
              Configuration files associated with locally installed programs.

       /usr/local/games
              Binaries for locally installed games.

       /usr/local/lib
              Files associated with locally installed programs.

       /usr/local/include
              Header files for the local C compiler.

       /usr/local/info
              Info pages associated with locally installed programs.

       /usr/local/man
              Man pages associated with locally installed programs.

       /usr/local/sbin
              Locally installed programs for system administration.

       /usr/local/share
              Local application data that can be shared among different
              architectures of the same OS.

       /usr/local/src
              Source code for locally installed software.

       /usr/man
              Replaced by /usr/share/man.

       /usr/sbin
              This directory contains program binaries for system administration
              which are not essential for the boot process, for mounting /usr, or
              for system repair.

       /usr/share
              This directory contains subdirectories with specific application
              data, that can be shared among different architectures of the same
              OS.  Often one finds stuff here that used to live in /usr/doc or
              /usr/lib or /usr/man.

       /usr/share/dict
              Contains the word lists used by spell checkers.

       /usr/share/doc
              Documentation about installed programs.

       /usr/share/games
              Static data files for games in /usr/games.

       /usr/share/info
              Info pages go here.

       /usr/share/locale
              Locale information goes here.

       /usr/share/man
              Manual pages go here in subdirectories according to the man page
              sections.

       /usr/share/man/<locale>/man[1-9]
              These directories contain manual pages for the specific locale in
              source code form.  Systems which use a unique language and code set
              for all manual pages may omit the <locale> substring.

       /usr/share/misc
              Miscellaneous data that can be shared among different architectures
              of the same OS.

       /usr/share/nls
              The message catalogs for native language support go here.

       /usr/share/sgml
              Files for SGML and XML.

       /usr/share/terminfo
              The database for terminfo.

       /usr/share/tmac
              Troff macros that are not distributed with groff.

       /usr/share/zoneinfo
              Files for timezone information.

       /usr/src
              Source files for different parts of the system, included with some
              packages for reference purposes.  Don't work here with your own
              projects, as files below /usr should be read-only except when
              installing software.

       /usr/src/linux
              This was the traditional place for the kernel source.  Some
              distributions put here the source for the default kernel they ship.
              You should probably use another directory when building your own
              kernel.

       /usr/tmp
              Obsolete.  This should be a link to /var/tmp.  This link is present
              only for compatibility reasons and shouldn't be used.

       /var   This directory contains files which may change in size, such as
              spool and log files.

       /var/adm
              This directory is superseded by /var/log and should be a symbolic
              link to /var/log.

       /var/backups
              Reserved for historical reasons.

       /var/cache
              Data cached for programs.

       /var/catman/cat[1-9] or /var/cache/man/cat[1-9]
              These directories contain preformatted manual pages according to
              their man page section.  (The use of preformatted manual pages is
              deprecated.)

       /var/cron
              Reserved for historical reasons.

       /var/lib
              Variable state information for programs.

       /var/local
              Variable data for /usr/local.

       /var/lock
              Lock files are placed in this directory.  The naming convention for
              device lock files is LCK..<device> where <device> is the device's
              name in the file system.  The format used is that of HDU UUCP lock
              files, that is, lock files contain a PID as a 10-byte ASCII decimal
              number, followed by a newline character.

       /var/log
              Miscellaneous log files.

       /var/opt
              Variable data for /opt.

       /var/mail
              Users' mailboxes.  Replaces /var/spool/mail.

       /var/msgs
              Reserved for historical reasons.

       /var/preserve
              Reserved for historical reasons.

       /var/run
              Run-time variable files, like files holding process identifiers
              (PIDs) and logged user information (utmp).  Files in this directory
              are usually cleared when the system boots.

       /var/spool
              Spooled (or queued) files for various programs.

       /var/spool/at
              Spooled jobs for at(1).

       /var/spool/cron
              Spooled jobs for cron(8).

       /var/spool/lpd
              Spooled files for printing.

       /var/spool/mail
              Replaced by /var/mail.

       /var/spool/mqueue
              Queued outgoing mail.

       /var/spool/news
              Spool directory for news.

       /var/spool/rwho
              Spooled files for rwhod(8).

       /var/spool/smail
              Spooled files for the smail(1) mail delivery program.

       /var/spool/uucp
              Spooled files for uucp(1).

       /var/tmp
              Like /tmp, this directory holds temporary files stored for an
              unspecified duration.

       /var/yp
              Database files for NIS.

CONFORMING TO top

       The Filesystem Hierarchy Standard, Version 2.2 <http://www.pathname.com
       /fhs/>.

BUGS top

       This list is not exhaustive; different systems may be configured differ-
       ently.

SEE ALSO top

       find(1), ln(1), proc(5), mount(8)

       The Filesystem Hierarchy Standard

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                             HIER(7)


host.conf(5) - Linux manual page

NAME | DESCRIPTION | ENVIRONMENT | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

HOST.CONF(5)                Linux System Administration               HOST.CONF(5)

NAME top

       host.conf - resolver configuration file

DESCRIPTION top

       The file /etc/host.conf contains configuration information specific to the
       resolver library.  It should contain one configuration keyword per line,
       followed by appropriate configuration information.  The keywords recognized
       are order, trim, multi, nospoof, spoof, and reorder.  These keywords are
       described below.

       order  This keyword specifies how host lookups are to be performed.  It
              should be followed by one or more lookup methods, separated by
              commas.  Valid methods are bind, hosts, and nis.

       trim   This keyword may be listed more than once.  Each time it should be
              followed by a list of domains, separated by colons (':'), semicolons
              (';') or commas (','), with the leading dot.  When set, the resolv+
              library will automatically trim the given domain name from the end
              of any hostname resolved via DNS.  This is intended for use with
              local hosts and domains.  (Related note: trim will not affect
              hostnames gathered via NIS or the hosts file.  Care should be taken
              to ensure that the first hostname for each entry in the hosts file
              is fully qualified or unqualified, as appropriate for the local
              installation.)

       multi  Valid values are on and off.  If set to on, the resolv+ library will
              return all valid addresses for a host that appears in the /etc/hosts
              file, instead of only the first.  This is off by default, as it may
              cause a substantial performance loss at sites with large hosts
              files.

       nospoof
              Valid values are on and off.  If set to on, the resolv+ library will
              attempt to prevent hostname spoofing to enhance the security of
              rlogin and rsh.  It works as follows: after performing a host
              address lookup, resolv+ will perform a hostname lookup for that
              address.  If the two hostnames do not match, the query will fail.
              The default value is off.

       spoofalert
              Valid values are on and off.  If this option is set to on and the
              nospoof option is also set, resolv+ will log a warning of the error
              via the syslog facility.  The default value is off.

       spoof  Valid values are off, nowarn and warn.  If this option is set to
              off, spoofed addresses are permitted and no warnings will be emitted
              via the syslog facility.  If this option is set to warn, resolv+
              will attempt to prevent hostname spoofing to enhance the security
              and log a warning of the error via the syslog facility.  If this
              option is set to nowarn, the resolv+ library will attempt to prevent
              hostname spoofing to enhance the security but not emit warnings via
              the syslog facility.  Setting this option to anything else is equal
              to setting it to nowarn.

       reorder
              Valid values are on and off.  If set to on, resolv+ will attempt to
              reorder host addresses so that local addresses (i.e., on the same
              subnet) are listed first when a gethostbyname(3) is performed.
              Reordering is done for all lookup methods.  The default value is
              off.

ENVIRONMENT top

       There are six environment variables that can be used to allow users to
       override the behavior which is configured in /etc/host.conf.

       RESOLV_HOST_CONF
              If set this variable points to a file that should be read instead of
              /etc/host.conf.

       RESOLV_SERV_ORDER
              Overrides the order command.

       RESOLV_SPOOF_CHECK
              Overrides the nospoof, spoofalert and spoof commands in the same way
              as the spoof command is parsed.  Valid values are off, nowarn and
              warn.

       RESOLV_MULTI
              Overrides the multi command.

       RESOLV_REORDER
              Overrides the reorder command.

       RESOLV_ADD_TRIM_DOMAINS
              A list of domains,  separated by colons (':'), semicolons (';') or
              commas (','), with the leading dot, which will be added to the list
              of domains that should be trimmed.

       RESOLV_OVERRIDE_TRIM_DOMAINS
              A list of domains,  separated by colons (':'), semicolons (';') or
              commas (','), with the leading dot, which will replace the list of
              domains that should be trimmed.  Overrides the trim command.

FILES top

       /etc/host.conf
              Resolver configuration file

       /etc/resolv.conf
              Resolver configuration file

       /etc/hosts
              Local hosts database

NOTES top

       The following differences exist compared to the original implementation.  A
       new command spoof and a new environment variable RESOLV_SPOOF_CHECK can
       take arguments like off, nowarn and warn.  Line comments can appear
       anywhere and not only at the beginning of a line.

SEE ALSO top

       gethostbyname(3), hostname(7), named(8), resolv+(8)

COLOPHON top

       This page is part of release 3.45 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                               2003-08-23                        HOST.CONF(5)


hostname(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

HOSTNAME(7)                  Linux Programmer's Manual                 HOSTNAME(7)

NAME top

       hostname - hostname resolution description

DESCRIPTION top

       Hostnames are domains, where a domain is a hierarchical, dot-separated list
       of subdomains; for example, the machine monet, in the Berkeley subdomain of
       the EDU domain would be represented as "monet.Berkeley.EDU".

       Hostnames are often used with network client and server programs, which
       must generally translate the name to an address for use.  (This task is
       generally performed by either getaddrinfo(3) or the obsolete
       gethostbyname(3).)  Hostnames are resolved by the Internet name resolver in
       the following fashion.

       If the name consists of a single component, that is, contains no dot, and
       if the environment variable HOSTALIASES is set to the name of a file, that
       file is searched for any string matching the input hostname.  The file
       should consist of lines made up of two white-space separated strings, the
       first of which is the hostname alias, and the second of which is the
       complete hostname to be substituted for that alias.  If a case-insensitive
       match is found between the hostname to be resolved and the first field of a
       line in the file, the substituted name is looked up with no further
       processing.

       If the input name ends with a trailing dot, the trailing dot is removed,
       and the remaining name is looked up with no further processing.

       If the input name does not end with a trailing dot, it is looked up by
       searching through a list of domains until a match is found.  The default
       search list includes first the local domain, then its parent domains with
       at least 2 name components (longest first).  For example, in the domain
       CS.Berkeley.EDU, the name lithium.CChem will be checked first as
       lithium.CChem.CS.Berkeley.EDU and then as lithium.CChem.Berkeley.EDU.
       Lithium.CChem.EDU will not be tried, as there is only one component
       remaining from the local domain.  The search path can be changed from the
       default by a system-wide configuration file (see resolver(5)).

SEE ALSO top

       gethostbyname(3), resolver(5), mailaddr(7), named(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-07                         HOSTNAME(7)


hosts(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

HOSTS(5)                     Linux Programmer's Manual                    HOSTS(5)

NAME top

       hosts - static table lookup for hostnames

SYNOPSIS top

       /etc/hosts

DESCRIPTION top

       This manual page describes the format of the /etc/hosts file.  This file is
       a simple text file that associates IP addresses with hostnames, one line
       per IP address.  For each host a single line should be present with the
       following information:

              IP_address canonical_hostname [aliases...]

       Fields of the entry are separated by any number of blanks and/or tab
       characters.  Text from a "#" character until the end of the line is a
       comment, and is ignored.  Host names may contain only alphanumeric
       characters, minus signs ("-"), and periods (".").  They must begin with an
       alphabetic character and end with an alphanumeric character.  Optional
       aliases provide for name changes, alternate spellings, shorter hostnames,
       or generic hostnames (for example, localhost).

       The Berkeley Internet Name Domain (BIND) Server implements the Internet
       name server for UNIX systems.  It augments or replaces the /etc/hosts file
       or hostname lookup, and frees a host from relying on /etc/hosts being up to
       date and complete.

       In modern systems, even though the host table has been superseded by DNS,
       it is still widely used for:

       bootstrapping
              Most systems have a small host table containing the name and address
              information for important hosts on the local network.  This is
              useful when DNS is not running, for example during system bootup.

       NIS    Sites that use NIS use the host table as input to the NIS host
              database.  Even though NIS can be used with DNS, most NIS sites
              still use the host table with an entry for all local hosts as a
              backup.

       isolated nodes
              Very small sites that are isolated from the network use the host
              table instead of DNS.  If the local information rarely changes, and
              the network is not connected to the Internet, DNS offers little
              advantage.

FILES top

       /etc/hosts

NOTES top

       Modifications to this file normally take effect immediately, except in
       cases where the file is cached by applications.

Historical Notes

       RFC 952 gave the original format for the host table, though it has since
       changed.

       Before the advent of DNS, the host table was the only way of resolving
       hostnames on the fledgling Internet.  Indeed, this file could be created
       from the official host data base maintained at the Network Information
       Control Center (NIC), though local changes were often required to bring it
       up to date regarding unofficial aliases and/or unknown hosts.  The NIC no
       longer maintains the hosts.txt files, though looking around at the time of
       writing (circa 2000), there are historical hosts.txt files on the WWW.  I
       just found three, from 92, 94, and 95.

EXAMPLE top

       127.0.0.1       localhost
       192.168.1.10    foo.mydomain.org       foo
       192.168.1.13    bar.mydomain.org       bar
       146.82.138.7    master.debian.org      master
       209.237.226.90  www.opensource.org

SEE ALSO top

       hostname(1), resolver(3), resolver(5), hostname(7), named(8)

       Internet RFC 952

COLOPHON top

       This page is part of release 3.45 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-06-16                            HOSTS(5)


hosts.equiv(5) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

HOSTS.EQUIV(5)               Linux Programmer's Manual              HOSTS.EQUIV(5)

NAME top

       /etc/hosts.equiv  -  list  of  hosts and users that are granted "trusted" r
       command access to your system

DESCRIPTION top

       The hosts.equiv file allows or denies hosts and users to use the r-commands
       (e.g., rlogin, rsh or rcp) without supplying a password.

       The file uses the following format:

       [ + | - ] [hostname] [username]

       The hostname is the name of a host which is logically equivalent to the
       local host.  Users logged into that host are allowed to access like-named
       user accounts on the local host without supplying a password.  The hostname
       may be (optionally) preceded by a plus (+) sign.  If the plus sign is used
       alone it allows any host to access your system.  You can explicitly deny
       access to a host by preceding the hostname by a minus (-) sign.  Users from
       that host must always supply a password.  For security reasons you should
       always use the FQDN of the hostname and not the short hostname.

       The username entry grants a specific user access to all user accounts
       (except root) without supplying a password.  That means the user is NOT
       restricted to like-named accounts.  The username may be (optionally)
       preceded by a plus (+) sign.  You can also explicitly deny access to a
       specific user by preceding the username with a minus (-) sign.  This says
       that the user is not trusted no matter what other entries for that host
       exist.

       Netgroups can be specified by preceding the netgroup by an @ sign.

       Be extremely careful when using the plus (+) sign.  A simple typographical
       error could result in a standalone plus sign.  A standalone plus sign is a
       wildcard character that means "any host"!

FILES top

       /etc/hosts.equiv

NOTES top

       Some systems will only honor the contents of this file when it has owner
       root and no write permission for anybody else.  Some exceptionally paranoid
       systems even require that there be no other hard links to the file.

       Modern systems use the Pluggable Authentication Modules library (PAM).
       With PAM a standalone plus sign is only considered a wildcard character
       which means "any host" when the word promiscuous is added to the auth
       component line in your PAM file for the particular service (e.g., rlogin).

SEE ALSO top

       rhosts(5), rlogind(8), rshd(8)

COLOPHON top

       This page is part of release 3.45 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                               2003-08-24                      HOSTS.EQUIV(5)


hpsa(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

HPSA(4)                      Linux Programmer's Manual                     HPSA(4)

NAME top

       hpsa - HP Smart Array SCSI driver

SYNOPSIS top

       modprobe hpsa [ hpsa_allow_any=1 ]

DESCRIPTION top

       hpsa is a SCSI driver for HP Smart Array RAID controllers.

Options

       hpsa_allow_any=1: This option allows the driver to attempt to operate on
       any HP Smart Array hardware RAID controller, even if it is not explicitly
       known to the driver.  This allows newer hardware to work with older
       drivers.  Typically this is used to allow installation of operating systems
       from media that predates the RAID controller, though it may also be used to
       enable hpsa to drive older controllers that would normally be handled by
       the cciss(4) driver.  These older boards have not been tested and are not
       supported with hpsa, and cciss(4) should still be used for these.

Supported Hardware

       The hpsa driver supports the following Smart Array boards:

           Smart Array P700M
           Smart Array P212
           Smart Array P410
           Smart Array P410i
           Smart Array P411
           Smart Array P812
           Smart Array P712m
           Smart Array P711m
           StorageWorks P1210m

Configuration Details

       To configure HP Smart Array controllers, use the HP Array Configuration
       Utility (either hpacuxe(8) or hpacucli(8)) or the Offline ROM-based
       Configuration Utility (ORCA) run from the Smart Array's option ROM at boot
       time.

FILES top

Device Nodes

       Logical drives are accessed via the SCSI disk driver (sd(4)), tape drives
       via the SCSI tape driver (st(4)), and the RAID controller via the SCSI
       generic driver (sg(4)), with device nodes named /dev/sd*, /dev/st*, and
       /dev/sg*, respectively.

HPSA-Specific Host Attribute Files in /sys

       /sys/class/scsi_host/host*/rescan
              This is a write-only attribute.  Writing to this attribute will
              cause the driver to scan for new, changed, or removed devices (e.g,.
              hot-plugged tape drives, or newly configured or deleted logical
              drives, etc.)  and notify the SCSI midlayer of any changes detected.
              Normally a rescan is triggered automatically by HP's Array
              Configuration Utility (either the GUI or the command-line variety);
              thus, for logical drive changes, the user should not normally have
              to use this attribute.  This attribute may be useful when hot
              plugging devices like tape drives, or entire storage boxes
              containing pre-configured logical drives.

       /sys/class/scsi_host/host*/firmware_revision
              This attribute contains the firmware version of the Smart Array.

              For example:

                  # cd /sys/class/scsi_host/host4
                  # cat firmware_revision
                  7.14

HPSA-Specific Disk Attribute Files in /sys

       /sys/class/scsi_disk/c:b:t:l/device/unique_id
              This attribute contains a 32 hex-digit unique ID for each logical
              drive.

              For example:

                  # cd /sys/class/scsi_disk/4:0:0:0/device
                  # cat unique_id
                  600508B1001044395355323037570F77

       /sys/class/scsi_disk/c:b:t:l/device/raid_level
              This attribute contains the RAID level of each logical drive.

              For example:

                  # cd /sys/class/scsi_disk/4:0:0:0/device
                  # cat raid_level
                  RAID 0

       /sys/class/scsi_disk/c:b:t:l/device/lunid
              This attribute contains the 16 hex-digit (8 byte) LUN ID by which a
              logical drive or physical device can be addressed.  c:b:t:l are the
              controller, bus, target and lun of the device.

              For example:

                  # cd /sys/class/scsi_disk/4:0:0:0/device
                  # cat lunid
                  0x0000004000000000

Supported ioctl() operations

       For compatibility with applications written for the cciss(4) driver, many,
       but not all of the ioctls supported by the cciss(4) driver are also
       supported by the hpsa driver.  The data structures used by these ioctls are
       described in the Linux kernel source file include/linux/cciss_ioctl.h.

       CCISS_DEREGDISK, CCISS_REGNEWDISK, CCISS_REGNEWD
              These three ioctls all do exactly the same thing, which is to cause
              the driver to rescan for new devices.  This does exactly the same
              thing as writing to the hpsa-specific host "rescan" attribute.

       CCISS_GETPCIINFO
              Returns PCI domain, bus, device and function and "board ID" (PCI
              subsystem ID).

       CCISS_GETDRIVVER
              Returns driver version in three bytes encoded as:

                  (major_version << 16) | (minor_version << 8) |
                      (subminor_version)

       CCISS_PASSTHRU, CCISS_BIG_PASSTHRU
              Allows "BMIC" and "CISS" commands to be passed through to the Smart
              Array.  These are used extensively by the HP Array Configuration
              Utility, SNMP storage agents, etc.  See cciss_vol_status at
              <http://cciss.sf.net> for some examples.

SEE ALSO          top
       cciss(4), sd(4), st(4), cciss_vol_status(8), hpacucli(8), hpacuxe(8),

       <http://cciss.sf.net>, and Documentation/scsi/hpsa.txt and Documenta-
       tion/ABI/testing/sysfs-bus-pci-devices-cciss in the Linux kernel source
       tree

COLOPHON          top
       This page is part of release 3.45 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                               2012-08-05                             HPSA(4)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


INFINITY(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | AVAILABILITY | SEE ALSO | COLOPHON The Linux Programming Interface

INFINITY(3)                  Linux Programmer's Manual                 INFINITY(3)

NAME top

       INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL - floating-point constants

SYNOPSIS top

       #define _ISOC99_SOURCE      /* See feature_test_macros(7) */
       #include <math.h>

       INFINITY

       NAN

       HUGE_VAL
       HUGE_VALF
       HUGE_VALL

DESCRIPTION top

       The macro INFINITY expands to a float constant representing positive
       infinity.

       The macro NAN expands to a float constant representing a quiet NaN (when
       supported).  A quiet NaN is a NaN ("not-a-number") that does not raise
       exceptions when it is used in arithmetic.  The opposite is a signaling NaN.
       See IEC 60559:1989.

       The macros HUGE_VAL, HUGE_VALF, HUGE_VALL expand to constants of types
       double, float and long double, respectively, that represent a large
       positive value, possibly plus infinity.

CONFORMING TO top

       C99.

AVAILABILITY top

       On a glibc system, the macro HUGE_VAL is always available.  Availability of
       the NAN macro can be tested using #ifdef NAN, and similarly for INFINITY,
       HUGE_VALF, HUGE_VALL.  They will be defined by <math.h> if _ISOC99_SOURCE
       or _GNU_SOURCE is defined, or __STDC_VERSION__ is defined and has a value
       not less than 199901L.

SEE ALSO top

       fpclassify(3), math_error(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-07-26                         INFINITY(3)


hypot(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

HYPOT(3)                     Linux Programmer's Manual                    HYPOT(3)

NAME top

       hypot, hypotf, hypotl - Euclidean distance function

SYNOPSIS top

       #include <math.h>

       double hypot(double x, double y);
       float hypotf(float x, float y);
       long double hypotl(long double x, long double y);

       Link with -lm.

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

       hypot():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       hypotf(), hypotl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The hypot() function returns sqrt(x*x+y*y).  This is the length of the
       hypotenuse of a right-angled triangle with sides of length x and y, or the
       distance of the point (x,y) from the origin.

       The calculation is performed without undue overflow or underflow during the
       intermediate steps of the calculation.

RETURN VALUE top

       On success, these functions return the length of a right-angled triangle
       with sides of length x and y.

       If x or y is an infinity, positive infinity is returned.

       If x or y is a NaN, and the other argument is not an infinity, a NaN is
       returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively.

       If both arguments are subnormal, and the result is subnormal, a range error
       occurs, and the correct result is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

       Range error: result underflow
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

              These functions do not set errno for this case.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD.

SEE ALSO top

       cabs(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            HYPOT(3)


icmp(7) - Linux manual page

NAME | DESCRIPTION | VERSIONS | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ICMP(7)                      Linux Programmer's Manual                     ICMP(7)

NAME top

       icmp - Linux IPv4 ICMP kernel module.

DESCRIPTION top

       This kernel protocol module implements the Internet Control Message
       Protocol defined in RFC 792.  It is used to signal error conditions and for
       diagnosis.  The user doesn't interact directly with this module; instead it
       communicates with the other protocols in the kernel and these pass the ICMP
       errors to the application layers.  The kernel ICMP module also answers ICMP
       requests.

       A user protocol may receive ICMP packets for all local sockets by opening a
       raw socket with the protocol IPPROTO_ICMP.  See raw(7) for more
       information.  The types of ICMP packets passed to the socket can be
       filtered using the ICMP_FILTER socket option.  ICMP packets are always
       processed by the kernel too, even when passed to a user socket.

       Linux limits the rate of ICMP error packets to each destination.
       ICMP_REDIRECT and ICMP_DEST_UNREACH are also limited by the destination
       route of the incoming packets.

/proc interfaces

       ICMP supports a set of /proc interfaces to configure some global IP
       parameters.  The parameters can be accessed by reading or writing files in
       the directory /proc/sys/net/ipv4/.  Most of these parameters are rate
       limitations for specific ICMP types.  Linux 2.2 uses a token bucket filter
       to limit ICMPs.  The value is the timeout in jiffies until the token bucket
       filter is cleared after a burst.  A jiffy is a system dependent unit,
       usually 10ms on i386 and about 1ms on alpha and ia64.

       icmp_destunreach_rate (Linux 2.2 to 2.4.9)
              Maximum rate to send ICMP Destination Unreachable packets.  This
              limits the rate at which packets are sent to any individual route or
              destination.  The limit does not affect sending of ICMP_FRAG_NEEDED
              packets needed for path MTU discovery.

       icmp_echo_ignore_all (since Linux 2.2)
              If this value is nonzero, Linux will ignore all ICMP_ECHO requests.

       icmp_echo_ignore_broadcasts (since Linux 2.2)
              If this value is nonzero, Linux will ignore all ICMP_ECHO packets
              sent to broadcast addresses.

       icmp_echoreply_rate (Linux 2.2 to 2.4.9)
              Maximum rate for sending ICMP_ECHOREPLY packets in response to
              ICMP_ECHOREQUEST packets.

       icmp_errors_use_inbound_ifaddr (Boolean; default: disabled; since Linux
       2.6.12)
              If disabled, ICMP error messages are sent with the primary address
              of the exiting interface.

              If enabled, the message will be sent with the primary address of the
              interface that received the packet that caused the ICMP error.  This
              is the behavior that many network administrators will expect from a
              router.  And it can make debugging complicated network layouts much
              easier.

              Note that if no primary address exists for the interface selected,
              then the primary address of the first non-loopback interface that
              has one will be used regardless of this setting.

       icmp_ignore_bogus_error_responses (Boolean; default: disabled; since Linux
       2.2)
              Some routers violate RFC1122 by sending bogus responses to broadcast
              frames.  Such violations are normally logged via a kernel warning.
              If this parameter is enabled, the kernel will not give such
              warnings, which will avoid log file clutter.

       icmp_paramprob_rate (Linux 2.2 to 2.4.9)
              Maximum rate for sending ICMP_PARAMETERPROB packets.  These packets
              are sent when a packet arrives with an invalid IP header.

       icmp_ratelimit (integer; default: 1000; since Linux 2.4.10)
              Limit the maximum rates for sending ICMP packets whose type matches
              icmp_ratemask (see below) to specific targets.  0 to disable any
              limiting, otherwise the minimum space between responses in
              milliseconds.

       icmp_ratemask (integer; default: see below; since Linux 2.4.10)
              Mask made of ICMP types for which rates are being limited.

              Significant bits: IHGFEDCBA9876543210
              Default mask:     0000001100000011000 (0x1818)

              Bit definitions (see the Linux kernel source file
              include/linux/icmp.h):

                  0 Echo Reply
                  3 Destination Unreachable *
                  4 Source Quench *
                  5 Redirect
                  8 Echo Request
                  B Time Exceeded *
                  C Parameter Problem *
                  D Timestamp Request
                  E Timestamp Reply
                  F Info Request
                  G Info Reply
                  H Address Mask Request
                  I Address Mask Reply

              The bits marked with an asterisk are rate limited by default (see
              the default mask above).

       icmp_timeexceed_rate (Linux 2.2 to 2.4.9)
              Maximum rate for sending ICMP_TIME_EXCEEDED packets.  These packets
              are sent to prevent loops when a packet has crossed too many hops.

VERSIONS top

       Support for the ICMP_ADDRESS request was removed in 2.2.

       Support for ICMP_SOURCE_QUENCH was removed in Linux 2.2.

NOTES top

       As many other implementations don't support IPPROTO_ICMP raw sockets, this
       feature should not be relied on in portable programs.

       ICMP_REDIRECT packets are not sent when Linux is not acting as a router.
       They are also only accepted from the old gateway defined in the routing
       table and the redirect routes are expired after some time.

       The 64-bit timestamp returned by ICMP_TIMESTAMP is in milliseconds since
       the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

       Linux ICMP internally uses a raw socket to send ICMPs.  This raw socket may
       appear in netstat(8) output with a zero inode.

SEE ALSO top

       ip(7)

       RFC 792 for a description of the ICMP protocol.

COLOPHON top

       This page is part of release 3.45 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                               2012-05-10                             ICMP(7)


iconv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ICONV(3)                     Linux Programmer's Manual                    ICONV(3)

NAME top

       iconv - perform character set conversion

SYNOPSIS top

       #include <iconv.h>

       size_t iconv(iconv_t cd,
                    char **inbuf, size_t *inbytesleft,
                    char **outbuf, size_t *outbytesleft);

DESCRIPTION top

       The iconv() function converts a sequence of characters in one character
       encoding to a sequence of characters in another character encoding.  The cd
       argument is a conversion descriptor, previously created by a call to
       iconv_open(3); the conversion descriptor defines the character encodings
       that iconv() uses for the conversion.  The inbuf argument is the address of
       a variable that points to the first character of the input sequence;
       inbytesleft indicates the number of bytes in that buffer.  The outbuf
       argument is the address of a variable that points to the first byte
       available in the output buffer; outbytesleft indicates the number of bytes
       available in the output buffer.

       The main case is when inbuf is not NULL and *inbuf is not NULL.  In this
       case, the iconv() function converts the multibyte sequence starting at
       *inbuf to a multibyte sequence starting at *outbuf.  At most *inbytesleft
       bytes, starting at *inbuf, will be read.  At most *outbytesleft bytes,
       starting at *outbuf, will be written.

       The iconv() function converts one multibyte character at a time, and for
       each character conversion it increments *inbuf and decrements *inbytesleft
       by the number of converted input bytes, it increments *outbuf and
       decrements *outbytesleft by the number of converted output bytes, and it
       updates the conversion state contained in cd.  If the character encoding of
       the input is stateful, the iconv() function can also convert a sequence of
       input bytes to an update to the conversion state without producing any
       output bytes; such input is called a shift sequence.  The conversion can
       stop for four reasons:

       1. An invalid multibyte sequence is encountered in the input.  In this case
          it sets errno to EILSEQ and returns (size_t) -1.  *inbuf is left
          pointing to the beginning of the invalid multibyte sequence.

       2. The input byte sequence has been entirely converted, that is,
          *inbytesleft has gone down to 0.  In this case iconv() returns the
          number of nonreversible conversions performed during this call.

       3. An incomplete multibyte sequence is encountered in the input, and the
          input byte sequence terminates after it.  In this case it sets errno to
          EINVAL and returns (size_t) -1.  *inbuf is left pointing to the
          beginning of the incomplete multibyte sequence.

       4. The output buffer has no more room for the next converted character.  In
          this case it sets errno to E2BIG and returns (size_t) -1.

       A different case is when inbuf is NULL or *inbuf is NULL, but outbuf is not
       NULL and *outbuf is not NULL.  In this case, the iconv() function attempts
       to set cd's conversion state to the initial state and store a corresponding
       shift sequence at *outbuf.  At most *outbytesleft bytes, starting at
       *outbuf, will be written.  If the output buffer has no more room for this
       reset sequence, it sets errno to E2BIG and returns (size_t) -1.  Otherwise
       it increments *outbuf and decrements *outbytesleft by the number of bytes
       written.

       A third case is when inbuf is NULL or *inbuf is NULL, and outbuf is NULL or
       *outbuf is NULL.  In this case, the iconv() function sets cd's conversion
       state to the initial state.

RETURN VALUE top

       The iconv() function returns the number of characters converted in a
       nonreversible way during this call; reversible conversions are not counted.
       In case of error, it sets errno and returns (size_t) -1.

ERRORS top

       The following errors can occur, among others:

       E2BIG  There is not sufficient room at *outbuf.

       EILSEQ An invalid multibyte sequence has been encountered in the input.

       EINVAL An incomplete multibyte sequence has been encountered in the input.

VERSIONS top

       This function is available in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Although inbuf and outbuf are typed as char **, this does not mean that the
       objects they point can be interpreted as C strings or as arrays of
       characters: the interpretation of character byte sequences is handled
       internally by the conversion functions.  In some encodings, a zero byte may
       be a valid part of a multibyte character.

       The caller of iconv() must ensure that the pointers passed to the function
       are suitable for accessing characters in the appropriate character set.
       This includes ensuring correct alignment on platforms that have tight
       restrictions on alignment.

SEE ALSO top

       iconv_close(3), iconv_open(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                            ICONV(3)


iconv_close(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ICONV_CLOSE(3)               Linux Programmer's Manual              ICONV_CLOSE(3)

NAME top

       iconv_close - deallocate descriptor for character set conversion

SYNOPSIS top

       #include <iconv.h>

       int iconv_close(iconv_t cd);

DESCRIPTION top

       The iconv_close() function deallocates a conversion descriptor cd
       previously allocated using iconv_open(3).

RETURN VALUE top

       When successful, the iconv_close() function returns 0.  In case of error,
       it sets errno and returns -1.

VERSIONS top

       This function is available in glibc since version 2.1.

CONFORMING TO top

       UNIX98, POSIX.1-2001.

SEE ALSO top

       iconv(3), iconv_open(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-11                      ICONV_CLOSE(3)


iconv_open(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ICONV_OPEN(3)                Linux Programmer's Manual               ICONV_OPEN(3)

NAME top

       iconv_open - allocate descriptor for character set conversion

SYNOPSIS top

       #include <iconv.h>

       iconv_t iconv_open(const char *tocode, const char *fromcode);

DESCRIPTION top

       The iconv_open() function allocates a conversion descriptor suitable for
       converting byte sequences from character encoding fromcode to character
       encoding tocode.

       The values permitted for fromcode and tocode and the supported combinations
       are system-dependent.  For the GNU C library, the permitted values are
       listed by the iconv --list command, and all combinations of the listed
       values are supported.  Furthermore the GNU C library and the GNU libiconv
       library support the following two suffixes:

       //TRANSLIT
              When the string "//TRANSLIT" is appended to tocode, transliteration
              is activated.  This means that when a character cannot be
              represented in the target character set, it can be approximated
              through one or several similarly looking characters.

       //IGNORE
              When the string "//IGNORE" is appended to tocode, characters that
              cannot be represented in the target character set will be silently
              discarded.

       The resulting conversion descriptor can be used with iconv(3) any number of
       times.  It remains valid until deallocated using iconv_close(3).

       A conversion descriptor contains a conversion state.  After creation using
       iconv_open(), the state is in the initial state.  Using iconv(3) modifies
       the descriptor's conversion state.  (This implies that a conversion
       descriptor can not be used in multiple threads simultaneously.)  To bring
       the state back to the initial state, use iconv(3) with NULL as inbuf
       argument.

RETURN VALUE top

       The iconv_open() function returns a freshly allocated conversion
       descriptor.  In case of error, it sets errno and returns (iconv_t) -1.

ERRORS top

       The following error can occur, among others:

       EINVAL The conversion from fromcode to tocode is not supported by the
              implementation.

VERSIONS top

       This function is available in glibc since version 2.1.

CONFORMING TO top

       UNIX98, POSIX.1-2001.

SEE ALSO top

       iconv(1), iconv(3), iconv_close(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-11                       ICONV_OPEN(3)


idle(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | COLOPHON The Linux Programming Interface

IDLE(2)                      Linux Programmer's Manual                     IDLE(2)

NAME top

       idle - make process 0 idle

SYNOPSIS top

       #include <unistd.h>

       int idle(void);

DESCRIPTION top

       idle() is an internal system call used during bootstrap.  It marks the
       process's pages as swappable, lowers its priority, and enters the main
       scheduling loop.  idle() never returns.

       Only process 0 may call idle().  Any user process, even a process with
       superuser permission, will receive EPERM.

RETURN VALUE top

       idle() never returns for process 0, and always returns -1 for a user
       process.

ERRORS top

       EPERM  Always, for a user process.

VERSIONS top

       Since 2.3.13 this system call does not exist anymore.

CONFORMING TO top

       This function is Linux-specific, and should not be used in programs
       intended to be portable.

COLOPHON top

       This page is part of release 3.45 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                               1994-08-21                             IDLE(2)


if_nameindex(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | EXAMPLE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

IF_NAMEINDEX(3)              Linux Programmer's Manual             IF_NAMEINDEX(3)

NAME top

       if_nameindex, if_freenameindex - get network interface names and indexes

SYNOPSIS top

       #include <net/if.h>

       struct if_nameindex *if_nameindex(void);
       void if_freenameindex(struct if_nameindex *ptr);

DESCRIPTION top

       The if_nameindex() function returns an array of if_nameindex structures,
       each containing information about one of the network interfaces on the
       local system.  The if_nameindex structure contains at least the following
       entries:

               unsigned int if_index; /* Index of interface (1, 2, ...) */
               char        *if_name;  /* Null-terminated name ("eth0", etc.) */

       The if_index field contains the interface index.  The ifa_name field points
       to the null-terminated interface name.  The end of the array is indicated
       by entry with if_index set to zero and ifa_name set to NULL.

       The data structure returned by if_nameindex() is dynamically allocated and
       should be freed using if_freenameindex() when no longer needed.

RETURN VALUE top

       On success, if_nameindex() returns pointer to the array; on error, a NULL
       pointer is returned, and errno is set appropriately.

ERRORS top

       if_nameindex() may fail and set errno if:

       ENOBUFS
              Insufficient resources unavailable.

       if_nameindex() may also fail for any of the errors specified for socket(2),
       bind(2), ioctl(2), getsockname(2), recvmsg(2), sendto(2), or malloc(3).

VERSIONS top

       The if_nameindex() function first appeared in glibc 2.1, but before glibc
       2.3.4, the implementation only supported interfaces with IPv4 addresses.
       Support of interfaces that don't have IPv4 addresses is only available on
       kernels that support netlink.

EXAMPLE top

       The program below demonstrates the use of the functions described on this
       page.  An example of the output this program might produce is the
       following:
           $ ./a.out
           1: lo
           2: wlan0
           3: em1

Program source

       #include <net/if.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       int
       main(int argc, char *argv[])
       {
           struct if_nameindex *if_ni, *i;

           if_ni = if_nameindex();
           if (if_ni == NULL) {
               perror("if_nameindex");
               exit(EXIT_FAILURE);
           }

           for (i = if_ni; ! (i->if_index == 0 && i->if_name == NULL); i++)
               printf("%u: %s\n", i->if_index, i->if_name);

           if_freenameindex(if_ni);

           exit(EXIT_SUCCESS);
       }

CONFORMING TO top

       RFC 3493, POSIX.1-2001.

       This function first appeared in BSDi.

SEE ALSO top

       getsockopt(2), setsockopt(2), getifaddrs(3), if_indextoname(3),
       if_nameindex(3), if_nametoindex(3), ifconfig(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-11-21                     IF_NAMEINDEX(3)


if_nametoindex(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

IF_NAMETOINDEX(3)            Linux Programmer's Manual           IF_NAMETOINDEX(3)

NAME top

       if_nametoindex,  if_indextoname  - mappings between network interface names
       and indexes

SYNOPSIS top

       #include <net/if.h>

       unsigned int if_nametoindex(const char *ifname);

       char *if_indextoname(unsigned int ifindex, char *ifname);

DESCRIPTION top

       The if_nametoindex() function returns the index of the network interface
       corresponding to the name ifname.

       The if_indextoname() function returns the name of the network interface
       corresponding to the interface index ifindex.  The name is placed in the
       buffer pointed to by ifname.  The buffer must allow for the storage of at
       least IF_NAMESIZE bytes.

RETURN VALUE top

       On success, if_nametoindex() returns the index number of the network
       interface; on error, 0 is returned and errno is set appropriately.

       On success, if_indextoname() returns ifname; on error, NULL is returned and
       errno is set appropriately.

ERRORS top

       if_indextoname() may fail and set errno if:

       ENXIO  No interface found for the index.

       if_nametoindex() and if_indextoname() may also fail for any of the errors
       specified for socket(2) or ioctl(2).

CONFORMING TO top

       RFC 3493, POSIX.1-2001.

       This function first appeared in BSDi.

SEE ALSO top

       getifaddrs(3), if_nameindex(3), ifconfig(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-12-14                   IF_NAMETOINDEX(3)


ilogb(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ILOGB(3)                     Linux Programmer's Manual                    ILOGB(3)

NAME top

       ilogb, ilogbf, ilogbl - get integer exponent of a floating-point value

SYNOPSIS top

       #include <math.h>

       int ilogb(double x);
       int ilogbf(float x);
       int ilogbl(long double x);

       Link with -lm.

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

       ilogb():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       ilogbf(), ilogbl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions return the exponent part of their argument as a signed
       integer.  When no error occurs, these functions are equivalent to the
       corresponding logb(3) functions, cast to int.

RETURN VALUE top

       On success, these functions return the exponent of x, as a signed integer.

       If x is zero, then a domain error occurs, and the functions return
       FP_ILOGB0.

       If x is a NaN, then a domain error occurs, and the functions return
       FP_ILOGBNAN.

       If x is negative infinity or positive infinity, then a domain error occurs,
       and the functions return INT_MAX.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is 0 or a NaN
              An invalid floating-point exception (FE_INVALID) is raised.

              These functions do not set errno for this case.

       Domain error: x is an infinity

              These functions do not set errno or raise an exception for this
              case.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       log(3), logb(3), significand(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            ILOGB(3)


outb(2) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

OUTB(2)                      Linux Programmer's Manual                     OUTB(2)

NAME top

       outb,  outw,  outl,  outsb,  outsw, outsl, inb, inw, inl, insb, insw, insl,
       outb_p, outw_p, outl_p, inb_p, inw_p, inl_p - port I/O

DESCRIPTION top

       This family of functions is used to do low-level port input and output.
       The out* functions do port output, the in* functions do port input; the b-
       suffix functions are byte-width and the w-suffix functions word-width; the
       _p-suffix functions pause until the I/O completes.

       They are primarily designed for internal kernel use, but can be used from
       user space.

       You compile with -O or -O2 or similar.  The functions are defined as inline
       macros, and will not be substituted in without optimization enabled,
       causing unresolved references at link time.

       You use ioperm(2) or alternatively iopl(2) to tell the kernel to allow the
       user space application to access the I/O ports in question.  Failure to do
       this will cause the application to receive a segmentation fault.

CONFORMING TO top

       outb() and friends are hardware-specific.  The value argument is passed
       first and the port argument is passed second, which is the opposite order
       from most DOS implementations.

SEE ALSO top

       ioperm(2), iopl(2)

COLOPHON top

       This page is part of release 3.45 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                               1995-11-29                             OUTB(2)


index(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

INDEX(3)                     Linux Programmer's Manual                    INDEX(3)

NAME top

       index, rindex - locate character in string

SYNOPSIS top

       #include <strings.h>

       char *index(const char *s, int c);

       char *rindex(const char *s, int c);

DESCRIPTION top

       The index() function returns a pointer to the first occurrence of the
       character c in the string s.

       The rindex() function returns a pointer to the last occurrence of the
       character c in the string s.

       The terminating null byte ('\0') is considered to be a part of the strings.

RETURN VALUE top

       The index() and rindex() functions return a pointer to the matched
       character or NULL if the character is not found.

CONFORMING TO top

       4.3BSD; marked as LEGACY in POSIX.1-2001.  POSIX.1-2008 removes the
       specifications of index() and rindex(), recommending strchr(3) and
       strrchr(3) instead.

SEE ALSO top

       memchr(3), strchr(3), string(3), strpbrk(3), strrchr(3), strsep(3),
       strspn(3), strstr(3), strtok(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-21                            INDEX(3)


Linux man-pages online

The links from this page display HTML renderings of the man pages from the Linux man-pages project.

  • List of all man pages, by section
  • List of all man pages, alphabetically
  • Individual sections (page names only): 1, 2, 3, 4, 5, 6, 7, 8
  • Intro pages:
intro(1),
intro(2),
intro(3),
intro(4),
intro(5),
intro(6),
intro(7),
intro(8)

Changelog of the man-pages project


inet(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

INET(3)                      Linux Programmer's Manual                     INET(3)

NAME top

       inet_aton,  inet_addr,  inet_network, inet_ntoa, inet_makeaddr, inet_lnaof,
       inet_netof - Internet address manipulation routines

SYNOPSIS top

       #include <sys/socket.h>
       #include <netinet/in.h>
       #include <arpa/inet.h>

       int inet_aton(const char *cp, struct in_addr *inp);

       in_addr_t inet_addr(const char *cp);

       in_addr_t inet_network(const char *cp);

       char *inet_ntoa(struct in_addr in);

       struct in_addr inet_makeaddr(int net, int host);

       in_addr_t inet_lnaof(struct in_addr in);

       in_addr_t inet_netof(struct in_addr in);

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

       inet_aton(), inet_ntoa(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       inet_aton() converts the Internet host address cp from the IPv4 numbers-
       and-dots notation into binary form (in network byte order) and stores it in
       the structure that inp points to.  inet_aton() returns nonzero if the
       address is valid, zero if not.  The address supplied in cp can have one of
       the following forms:

       a.b.c.d   Each of the four numeric parts specifies a byte of the address;
                 the bytes are assigned in left-to-right order to produce the
                 binary address.

       a.b.c     Parts a and b specify the first two bytes of the binary address.
                 Part c is interpreted as a 16-bit value that defines the
                 rightmost two bytes of the binary address.  This notation is
                 suitable for specifying (outmoded) Class B network addresses.

       a.b       Part a specifies the first byte of the binary address.  Part b is
                 interpreted as a 24-bit value that defines the rightmost three
                 bytes of the binary address.  This notation is suitable for
                 specifying (outmoded) Class C network addresses.

       a         The value a is interpreted as a 32-bit value that is stored
                 directly into the binary address without any byte rearrangement.

       In all of the above forms, components of the dotted address can be
       specified in decimal, octal (with a leading 0), or hexadecimal, with a
       leading 0X).  Addresses in any of these forms are collectively termed IPV4
       numbers-and-dots notation.  The form that uses exactly four decimal numbers
       is referred to as IPv4 dotted-decimal notation (or sometimes: IPv4 dotted-
       quad notation).

       The inet_addr() function converts the Internet host address cp from IPv4
       numbers-and-dots notation into binary data in network byte order.  If the
       input is invalid, INADDR_NONE (usually -1) is returned.  Use of this
       function is problematic because -1 is a valid address (255.255.255.255).
       Avoid its use in favor of inet_aton(), inet_pton(3), or getaddrinfo(3)
       which provide a cleaner way to indicate error return.

       The inet_network() function converts cp, a string in IPv4 numbers-and-dots
       notation, into a number in host byte order suitable for use as an Internet
       network address.  On success, the converted address is returned.  If the
       input is invalid, -1 is returned.

       The inet_ntoa() function converts the Internet host address in, given in
       network byte order, to a string in IPv4 dotted-decimal notation.  The
       string is returned in a statically allocated buffer, which subsequent calls
       will overwrite.

       The inet_lnaof() function returns the local network address part of the
       Internet address in.  The returned value is in host byte order.

       The inet_netof() function returns the network number part of the Internet
       address in.  The returned value is in host byte order.

       The inet_makeaddr() function is the converse of inet_netof() and
       inet_lnaof().  It returns an Internet host address in network byte order,
       created by combining the network number net with the local address host,
       both in host byte order.

       The structure in_addr as used in inet_ntoa(), inet_makeaddr(), inet_lnaof()
       and inet_netof() is defined in <netinet/in.h> as:

           typedef uint32_t in_addr_t;

           struct in_addr {
               in_addr_t s_addr;
           };

CONFORMING TO top

       4.3BSD.  inet_addr() and inet_ntoa() are specified in POSIX.1-2001.
       inet_aton() is not specified in POSIX.1-2001, but is available on most
       systems.

NOTES top

       On the i386 the host byte order is Least Significant Byte first (little
       endian), whereas the network byte order, as used on the Internet, is Most
       Significant Byte first (big endian).

       inet_lnaof(), inet_netof(), and inet_makeaddr() are legacy functions that
       assume they are dealing with classful network addresses.  Classful
       networking divides IPv4 network addresses into host and network components
       at byte boundaries, as follows:

       Class A   This address type is indicated by the value 0 in the most
                 significant bit of the (network byte ordered) address.  The
                 network address is contained in the most significant byte, and
                 the host address occupies the remaining three bytes.

       Class B   This address type is indicated by the binary value 10 in the most
                 significant two bits of the address.  The network address is
                 contained in the two most significant bytes, and the host address
                 occupies the remaining two bytes.

       Class C   This address type is indicated by the binary value 110 in the
                 most significant three bits of the address.  The network address
                 is contained in the three most significant bytes, and the host
                 address occupies the remaining byte.

       Classful network addresses are now obsolete, having been superseded by
       Classless Inter-Domain Routing (CIDR), which divides addresses into network
       and host components at arbitrary bit (rather than byte) boundaries.

EXAMPLE top

       An example of the use of inet_aton() and inet_ntoa() is shown below.  Here
       are some example runs:

           $ ./a.out 226.000.000.037      # Last byte is in octal
           226.0.0.31
           $ ./a.out 0x7f.1               # First byte is in hex
           127.0.0.1

Program source

       #define _BSD_SOURCE
       #include <arpa/inet.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           struct in_addr addr;

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

           if (inet_aton(argv[1], &addr) == 0) {
               perror("inet_aton");
               exit(EXIT_FAILURE);
           }

           printf("%s\n", inet_ntoa(addr));
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       byteorder(3), getaddrinfo(3), gethostbyname(3), getnameinfo(3),
       getnetent(3), inet_ntop(3), inet_pton(3), hosts(5), networks(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-06-19                             INET(3)


inet_ntop(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

INET_NTOP(3)                 Linux Programmer's Manual                INET_NTOP(3)

NAME top

       inet_ntop - convert IPv4 and IPv6 addresses from binary to text form

SYNOPSIS top

       #include <arpa/inet.h>

       const char *inet_ntop(int af, const void *src,
                             char *dst, socklen_t size);

DESCRIPTION top

       This function converts the network address structure src in the af address
       family into a character string.  The resulting string is copied to the
       buffer pointed to by dst, which must be a non-NULL pointer.  The caller
       specifies the number of bytes available in this buffer in the argument
       size.

       inet_ntop() extends the inet_ntoa(3) function to support multiple address
       families, inet_ntoa(3) is now considered to be deprecated in favor of
       inet_ntop().  The following address families are currently supported:

       AF_INET
              src points to a struct in_addr (in network byte order) which is
              converted to an IPv4 network address in the dotted-decimal format,
              "ddd.ddd.ddd.ddd".  The buffer dst must be at least INET_ADDRSTRLEN
              bytes long.

       AF_INET6
              src points to a struct in6_addr (in network byte order) which is
              converted to a representation of this address in the most
              appropriate IPv6 network address format for this address.  The
              buffer dst must be at least INET6_ADDRSTRLEN bytes long.

RETURN VALUE top

       On success, inet_ntop() returns a non-NULL pointer to dst.  NULL is
       returned if there was an error, with errno set to indicate the error.

ERRORS top

       EAFNOSUPPORT
              af was not a valid address family.

       ENOSPC The converted address string would exceed the size given by size.

CONFORMING TO top

       POSIX.1-2001.  Note that RFC 2553 defines a prototype where the last
       argument size is of type size_t.  Many systems follow RFC 2553.  Glibc 2.0
       and 2.1 have size_t, but 2.2 and later have socklen_t.

BUGS top

       AF_INET6 converts IPv4-mapped IPv6 addresses into an IPv6 format.

EXAMPLE top

       See inet_pton(3).

SEE ALSO top

       getnameinfo(3), inet(3), inet_pton(3)

COLOPHON top

       This page is part of release 3.45 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                        INET_NTOP(3)


inet_pton(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

INET_PTON(3)                 Linux Programmer's Manual                INET_PTON(3)

NAME top

       inet_pton - convert IPv4 and IPv6 addresses from text to binary form

SYNOPSIS top

       #include <arpa/inet.h>

       int inet_pton(int af, const char *src, void *dst);

DESCRIPTION top

       This function converts the character string src into a network address
       structure in the af address family, then copies the network address
       structure to dst.  The af argument must be either AF_INET or AF_INET6.

       The following address families are currently supported:

       AF_INET
              src points to a character string containing an IPv4 network address
              in dotted-decimal format, "ddd.ddd.ddd.ddd", where ddd is a decimal
              number of up to three digits in the range 0 to 255.  The address is
              converted to a struct in_addr and copied to dst, which must be
              sizeof(struct in_addr) (4) bytes (32 bits) long.

       AF_INET6
              src points to a character string containing an IPv6 network address.
              The address is converted to a struct in6_addr and copied to dst,
              which must be sizeof(struct in6_addr) (16) bytes (128 bits) long.
              The allowed formats for IPv6 addresses follow these rules:

              1. The preferred format is x:x:x:x:x:x:x:x.  This form consists of
                 eight hexadecimal numbers, each of which expresses a 16-bit value
                 (i.e., each x can be up to 4 hex digits).

              2. A series of contiguous zero values in the preferred format can be
                 abbreviated to ::.  Only one instance of :: can occur in an
                 address.  For example, the loopback address 0:0:0:0:0:0:0:1 can
                 be abbreviated as ::1.  The wildcard address, consisting of all
                 zeros, can be written as ::.

              3. An alternate format is useful for expressing IPv4-mapped IPv6
                 addresses.  This form is written as x:x:x:x:x:x:d.d.d.d, where
                 the six leading xs are hexadecimal values that define the six
                 most-significant 16-bit pieces of the address (i.e., 96 bits),
                 and the ds express a value in dotted-decimal notation that
                 defines the least significant 32 bits of the address.  An example
                 of such an address is ::FFFF:204.152.189.116.

              See RFC 2373 for further details on the representation of IPv6
              addresses.

RETURN VALUE top

       inet_pton() returns 1 on success (network address was successfully
       converted).  0 is returned if src does not contain a character string
       representing a valid network address in the specified address family.  If
       af does not contain a valid address family, -1 is returned and errno is set
       to EAFNOSUPPORT.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Unlike inet_aton(3) and inet_addr(3), inet_pton() supports IPv6 addresses.
       On the other hand, inet_pton() only accepts IPv4 addresses in dotted-
       decimal notation, whereas inet_aton(3) and inet_addr(3) allow the more
       general numbers-and-dots notation (hexadecimal and octal number formats,
       and formats that don't require all four bytes to be explicitly written).
       For an interface that handles both IPv6 addresses, and IPv4 addresses in
       numbers-and-dots notation, see getaddrinfo(3).

BUGS top

       AF_INET6 does not recognize IPv4 addresses.  An explicit IPv4-mapped IPv6
       address must be supplied in src instead.

EXAMPLE top

       The program below demonstrates the use of inet_pton() and inet_ntop(3).
       Here are some example runs:

           $ ./a.out i6 0:0:0:0:0:0:0:0
           ::
           $ ./a.out i6 1:0:0:0:0:0:0:8
           1::8
           $ ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116
           ::ffff:204.152.189.116

Program source

       #include <arpa/inet.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           unsigned char buf[sizeof(struct in6_addr)];
           int domain, s;
           char str[INET6_ADDRSTRLEN];

           if (argc != 3) {
               fprintf(stderr, "Usage: %s {i4|i6|<num>} string\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           domain = (strcmp(argv[1], "i4") == 0) ? AF_INET :
                    (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]);

           s = inet_pton(domain, argv[2], buf);
           if (s <= 0) {
               if (s == 0)
                   fprintf(stderr, "Not in presentation format");
               else
                   perror("inet_pton");
               exit(EXIT_FAILURE);
           }

           if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) {
               perror("inet_ntop");
               exit(EXIT_FAILURE);
           }

           printf("%s\n", str);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getaddrinfo(3), inet(3), inet_ntop(3)

COLOPHON top

       This page is part of release 3.45 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-06-18                        INET_PTON(3)


infnan(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | COLOPHON The Linux Programming Interface

INFNAN(3)                    Linux Programmer's Manual                   INFNAN(3)

NAME top

       infnan - deal with infinite or not-a-number (NaN) result

SYNOPSIS top

       #include <math.h>

       double infnan(int error);

       Link with -lm.

DESCRIPTION top

       The infnan() function returns a suitable value for infinity and "not-a-
       number" (NaN) results.  The value of error can be ERANGE to represent
       infinity or anything else to represent NaN.  errno is also set.

RETURN VALUE top

       If error is ERANGE (Infinity), HUGE_VAL is returned.

       If error is -ERANGE (-Infinity), -HUGE_VAL is returned.

       If error is anything else, NAN is returned.

ERRORS top

       EDOM   The value of error is "not-a-number" (NaN).

       ERANGE The value of error is positive infinity or negative infinity.

CONFORMING TO top

       4.3BSD.

NOTES top

       This obsolete function was provided in libc4 and libc5, but is not
       available in glibc2.

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-06-02                           INFNAN(3)


initgroups(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

INITGROUPS(3)                Linux Programmer's Manual               INITGROUPS(3)

NAME top

       initgroups - initialize the supplementary group access list

SYNOPSIS top

       #include <sys/types.h>
       #include <grp.h>

       int initgroups(const char *user, gid_t group);

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

       initgroups(): _BSD_SOURCE

DESCRIPTION top

       The initgroups() function initializes the group access list by reading the
       group database /etc/group and using all groups of which user is a member.
       The additional group group is also added to the list.

       The user argument must be non-NULL.

RETURN VALUE top

       The initgroups() function returns 0 on success.  On error, -1 is returned,
       and errno is set appropriately.

ERRORS top

       ENOMEM Insufficient memory to allocate group information structure.

       EPERM  The calling process has insufficient privilege.  See the underlying
              system call setgroups(2).

FILES top

       /etc/group          group database file

CONFORMING TO top

       SVr4, 4.3BSD.

SEE ALSO top

       getgroups(2), setgroups(2), credentials(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                       INITGROUPS(3)


initrd(4) - Linux manual page

NAME | CONFIGURATION | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INITRD(4)                    Linux Programmer's Manual                   INITRD(4)

NAME top

       initrd - boot loader initialized RAM disk

CONFIGURATION top

       The  /dev/initrd  is  a  read-only block device assigned major number 1 and
       minor number 250.  Typically /dev/initrd is owned by  root.disk  with  mode
       0400  (read  access  by  root  only).   If  the  Linux system does not have
       /dev/initrd already created, it can be created with the following commands:
               mknod -m 400 /dev/initrd b 1 250
               chown root:disk /dev/initrd

       Also, support for both "RAM  disk"  and  "Initial  RAM  disk"  (e.g.,  CON-
       FIG_BLK_DEV_RAM=y  and  CONFIG_BLK_DEV_INITRD=y)  must be compiled directly
       into the Linux kernel to use /dev/initrd.  When using /dev/initrd, the  RAM
       disk driver cannot be loaded as a module.

DESCRIPTION top

       The special file /dev/initrd is a read-only block device.  This device is a
       RAM disk that is initialized (e.g., loaded) by the boot loader before the
       kernel is started.  The kernel then can use /dev/initrd's contents for a
       two-phase system boot-up.

       In the first boot-up phase, the kernel starts up and mounts an initial root
       file-system from the contents of /dev/initrd (e.g., RAM disk initialized by
       the boot loader).  In the second phase, additional drivers or other modules
       are loaded from the initial root device's contents.  After loading the
       additional modules, a new root file system (i.e., the normal root file
       system) is mounted from a different device.

Boot-up Operation

       When booting up with initrd, the system boots as follows:

       1. The boot loader loads the kernel program and /dev/initrd's contents into
          memory.

       2. On kernel startup, the kernel uncompresses and copies the contents of
          the device /dev/initrd onto device /dev/ram0 and then frees the memory
          used by /dev/initrd.

       3. The kernel then read-write mounts the device /dev/ram0 as the initial
          root file system.

       4. If the indicated normal root file system is also the initial root file-
          system (e.g., /dev/ram0) then the kernel skips to the last step for the
          usual boot sequence.

       5. If the executable file /linuxrc is present in the initial root file-
          system, /linuxrc is executed with UID 0.  (The file /linuxrc must have
          executable permission.  The file /linuxrc can be any valid executable,
          including a shell script.)

       6. If /linuxrc is not executed or when /linuxrc terminates, the normal root
          file system is mounted.  (If /linuxrc exits with any file-systems
          mounted on the initial root file-system, then the behavior of the kernel
          is UNSPECIFIED.  See the NOTES section for the current kernel behavior.)

       7. If the normal root file system has a directory /initrd, the device
          /dev/ram0 is moved from / to /initrd.  Otherwise if the directory
          /initrd does not exist, the device /dev/ram0 is unmounted.  (When moved
          from / to /initrd, /dev/ram0 is not unmounted and therefore processes
          can remain running from /dev/ram0.  If directory /initrd does not exist
          on the normal root file system and any processes remain running from
          /dev/ram0 when /linuxrc exits, the behavior of the kernel is
          UNSPECIFIED.  See the NOTES section for the current kernel behavior.)

       8. The usual boot sequence (e.g., invocation of /sbin/init) is performed on
          the normal root file system.

Options

       The following boot loader options, when used with initrd, affect the
       kernel's boot-up operation:

       initrd=[22mfilename[0m
              Specifies the file to load as the contents of /dev/initrd.  For
              LOADLIN this is a command-line option.  For LILO you have to use
              this command in the LILO configuration file /etc/lilo.config.  The
              filename specified with this option will typically be a gzipped
              file-system image.

       noinitrd
              This boot option disables the two-phase boot-up operation.  The
              kernel performs the usual boot sequence as if /dev/initrd was not
              initialized.  With this option, any contents of /dev/initrd loaded
              into memory by the boot loader contents are preserved.  This option
              permits the contents of /dev/initrd to be any data and need not be
              limited to a file system image.  However, device /dev/initrd is
              read-only and can be read only one time after system startup.

       root=[22mdevice-name[0m
              Specifies the device to be used as the normal root file system.  For
              LOADLIN this is a command-line option.  For LILO this is a boot time
              option or can be used as an option line in the LILO configuration
              file /etc/lilo.config.  The device specified by the this option must
              be a mountable device having a suitable root file-system.

Changing the Normal Root File System

       By default, the kernel's settings (e.g., set in the kernel file with
       rdev(8) or compiled into the kernel file), or the boot loader option
       setting is used for the normal root file systems.  For an NFS-mounted
       normal root file system, one has to use the nfs_root_name and
       nfs_root_addrs boot options to give the NFS settings.  For more information
       on NFS-mounted root see the kernel documentation file
       Documentation/filesystems/nfsroot.txt.  For more information on setting the
       root file system see also the LILO and LOADLIN documentation.

       It is also possible for the /linuxrc executable to change the normal root
       device.  For /linuxrc to change the normal root device, /proc must be
       mounted.  After mounting /proc, /linuxrc changes the normal root device by
       writing into the proc files /proc/sys/kernel/real-root-dev,
       /proc/sys/kernel/nfs-root-name, and /proc/sys/kernel/nfs-root-addrs.  For a
       physical root device, the root device is changed by having /linuxrc write
       the new root file system device number into /proc/sys/kernel/real-root-dev.
       For an NFS root file system, the root device is changed by having /linuxrc
       write the NFS setting into files /proc/sys/kernel/nfs-root-name and
       /proc/sys/kernel/nfs-root-addrs and then writing 0xff (e.g., the pseudo-
       NFS-device number) into file /proc/sys/kernel/real-root-dev.  For example,
       the following shell command line would change the normal root device to
       /dev/hdb1:

           echo 0x365 >/proc/sys/kernel/real-root-dev

       For an NFS example, the following shell command lines would change the
       normal root device to the NFS directory /var/nfsroot on a local networked
       NFS server with IP number 193.8.232.7 for a system with IP number
       193.8.232.2 and named "idefix":

           echo /var/nfsroot >/proc/sys/kernel/nfs-root-name
           echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \
               >/proc/sys/kernel/nfs-root-addrs
           echo 255 >/proc/sys/kernel/real-root-dev

       Note: The use of /proc/sys/kernel/real-root-dev to change the root file
       system is obsolete.  See the Linux kernel source file
       Documentation/initrd.txt as well as pivot_root(2) and pivot_root(8) for
       information on the modern method of changing the root file system.

Usage

       The main motivation for implementing initrd was to allow for modular kernel
       configuration at system installation.

       A possible system installation scenario is as follows:

       1. The loader program boots from floppy or other media with a minimal
          kernel (e.g., support for /dev/ram, /dev/initrd, and the ext2 file-
          system) and loads /dev/initrd with a gzipped version of the initial
          file-system.

       2. The executable /linuxrc determines what is needed to (1) mount the
          normal root file-system (i.e., device type, device drivers, file system)
          and (2) the distribution media (e.g., CD-ROM, network, tape, ...).  This
          can be done by asking the user, by auto-probing, or by using a hybrid
          approach.

       3. The executable /linuxrc loads the necessary modules from the initial
          root file-system.

       4. The executable /linuxrc creates and populates the root file system.  (At
          this stage the normal root file system does not have to be a completed
          system yet.)

       5. The executable /linuxrc sets /proc/sys/kernel/real-root-dev, unmount
          /proc, the normal root file system and any other file systems it has
          mounted, and then terminates.

       6. The kernel then mounts the normal root file system.

       7. Now that the file system is accessible and intact, the boot loader can
          be installed.

       8. The boot loader is configured to load into /dev/initrd a file system
          with the set of modules that was used to bring up the system.  (e.g.,
          Device /dev/ram0 can be modified, then unmounted, and finally, the image
          is written from /dev/ram0 to a file.)

       9. The system is now bootable and additional installation tasks can be
          performed.

       The key role of /dev/initrd in the above is to reuse the configuration data
       during normal system operation without requiring initial kernel selection,
       a large generic kernel or, recompiling the kernel.

       A second scenario is for installations where Linux runs on systems with
       different hardware configurations in a single administrative network.  In
       such cases, it may be desirable to use only a small set of kernels (ideally
       only one) and to keep the system-specific part of configuration information
       as small as possible.  In this case, create a common file with all needed
       modules.  Then, only the /linuxrc file or a file executed by /linuxrc would
       be different.

       A third scenario is more convenient recovery disks.  Because information
       like the location of the root file-system partition is not needed at boot
       time, the system loaded from /dev/initrd can use a dialog and/or auto-
       detection followed by a possible sanity check.

       Last but not least, Linux distributions on CD-ROM may use initrd for easy
       installation from the CD-ROM.  The distribution can use LOADLIN to directly
       load /dev/initrd from CD-ROM without the need of any floppies.  The
       distribution could also use a LILO boot floppy and then bootstrap a bigger
       RAM disk via /dev/initrd from the CD-ROM.

FILES top

       /dev/initrd
       /dev/ram0
       /linuxrc
       /initrd

NOTES top

       1. With the current kernel, any file systems that remain mounted when
          /dev/ram0 is moved from / to /initrd continue to be accessible.
          However, the /proc/mounts entries are not updated.

       2. With the current kernel, if directory /initrd does not exist, then
          /dev/ram0 will not be fully unmounted if /dev/ram0 is used by any
          process or has any file-system mounted on it.  If /dev/ram0 is not fully
          unmounted, then /dev/ram0 will remain in memory.

       3. Users of /dev/initrd should not depend on the behavior give in the above
          notes.  The behavior may change in future versions of the Linux kernel.

SEE ALSO top

       chown(1), mknod(1), ram(4), freeramdisk(8), rdev(8)

       Documentation/initrd.txt in the Linux kernel source tree, the LILO
       documentation, the LOADLIN documentation, the SYSLINUX documentation

COLOPHON top

       This page is part of release 3.45 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                               2010-09-04                           INITRD(4)


random(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RANDOM(3)                    Linux Programmer's Manual                   RANDOM(3)

NAME top

       random, srandom, initstate, setstate - random number generator

SYNOPSIS top

       #include <stdlib.h>

       long int random(void);

       void srandom(unsigned int seed);

       char *initstate(unsigned int seed, char *state, size_t n);
       char *setstate(char *state);

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

       random(), srandom(), initstate(), setstate():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The random() function uses a nonlinear additive feedback random number
       generator employing a default table of size 31 long integers to return
       successive pseudo-random numbers in the range from 0 to RAND_MAX.  The
       period of this random number generator is very large, approximately
       16 * ((2^31) - 1).

       The srandom() function sets its argument as the seed for a new sequence of
       pseudo-random integers to be returned by random().  These sequences are
       repeatable by calling srandom() with the same seed value.  If no seed value
       is provided, the random() function is automatically seeded with a value of
       1.

       The initstate() function allows a state array state to be initialized for
       use by random().  The size of the state array n is used by initstate() to
       decide how sophisticated a random number generator it should use--the
       larger the state array, the better the random numbers will be.  seed is the
       seed for the initialization, which specifies a starting point for the
       random number sequence, and provides for restarting at the same point.

       The setstate() function changes the state array used by the random()
       function.  The state array state is used for random number generation until
       the next call to initstate() or setstate().  state must first have been
       initialized using initstate() or be the result of a previous call of
       setstate().

RETURN VALUE top

       The random() function returns a value between 0 and RAND_MAX.  The
       srandom() function returns no value.  The initstate() function returns a
       pointer to the previous state array.  The setstate() function returns a
       pointer to the previous state array, or NULL on error.

ERRORS top

       EINVAL A state array of less than 8 bytes was specified to initstate().

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

NOTES top

       Current "optimal" values for the size of the state array n are 8, 32, 64,
       128, and 256 bytes; other amounts will be rounded down to the nearest known
       amount.  Using less than 8 bytes will cause an error.

       This function should not be used in cases where multiple threads use
       random() and the behavior should be reproducible.  Use random_r(3) for that
       purpose.

       Random-number generation is a complex topic.  Numerical Recipes in C: The
       Art of Scientific Computing (William H. Press, Brian P. Flannery, Saul A.
       Teukolsky, William T. Vetterling; New York: Cambridge University Press,
       2007, 3rd ed.)  provides an excellent discussion of practical random-number
       generation issues in Chapter 7 (Random Numbers).

       For a more theoretical discussion which also covers many practical issues
       in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's The Art of
       Computer Programming, volume 2 (Seminumerical Algorithms), 2nd ed.;
       Reading, Massachusetts: Addison-Wesley Publishing Company, 1981.

SEE ALSO top

       drand48(3), rand(3), random_r(3), srand(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           RANDOM(3)


random_r(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

RANDOM_R(3)                  Linux Programmer's Manual                 RANDOM_R(3)

NAME top

       random_r, srandom_r, initstate_r, setstate_r - reentrant random number gen-
       erator

SYNOPSIS top

       #include <stdlib.h>

       int random_r(struct random_data *buf, int32_t *result);

       int srandom_r(unsigned int seed, struct random_data *buf);

       int initstate_r(unsigned int seed, char *statebuf,
                       size_t statelen, struct random_data *buf);
       int setstate_r(char *statebuf, struct random_data *buf);

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

       random_r(), srandom_r(), initstate_r(), setstate_r():
           _SVID_SOURCE || _BSD_SOURCE

DESCRIPTION top

       These functions are the reentrant equivalents of the functions described in
       random(3).  They are suitable for use in multithreaded programs where each
       thread needs to obtain an independent, reproducible sequence of random
       numbers.

       The random_r() function is like random(3), except that instead of using
       state information maintained in a global variable, it uses the state
       information in the argument pointed to by buf.  The generated random number
       is returned in the argument result.

       The srandom_r() function is like srandom(3), except that it initializes the
       seed for the random number generator whose state is maintained in the
       object pointed to by buf, instead of the seed associated with the global
       state variable.

       The initstate_r() function is like initstate(3) except that it initializes
       the state in the object pointed to by buf, rather than initializing the
       global state variable.

       The setstate_r() function is like setstate(3) except that it modifies the
       state in the object pointer to by buf, rather than modifying the global
       state variable.

RETURN VALUE top

       All of these functions return 0 on success, or -1 on error.

ERRORS top

       EINVAL A state array of less than 8 bytes was specified to initstate_r().

       EINVAL The statebuf or buf argument to setstate_r() was NULL.

       EINVAL The buf or result argument to random_r() was NULL.

CONFORMING TO top

       These functions are nonstandard glibc extensions.

SEE ALSO top

       drand48(3), rand(3), random(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-03-07                         RANDOM_R(3)


init_module(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INIT_MODULE(2)               Linux Programmer's Manual              INIT_MODULE(2)

NAME top

       init_module - load a kernel module

SYNOPSIS top

       int init_module(void *module_image, unsigned long len,
                       const char *param_values);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       init_module() loads an ELF image into kernel space, performs any necessary
       symbol relocations, initializes module parameters to values provided by the
       caller, and then runs the module's init function.  This system call
       requires privilege.

       The module_image argument points to a buffer containing the binary image to
       be loaded; len specifies the size of that buffer.  The module image should
       be a valid ELF image, built for the running kernel.

       The param_values argument is a string containing space-delimited
       specifications of the values for module parameters (defined inside the
       module using module_param() and module_param_array()).  The kernel parses
       this string and initializes the specified parameters.  Each of the
       parameter specifications has the form:

               name[=value[,value...]]

       The parameter name is one of those defined within the module using
       module_param() (see the Linux kernel source file
       include/linux/moduleparam.h).  The parameter value is optional in the case
       of bool and invbool parameters.  Values for array parameters are specified
       as a comma-separated list.

RETURN VALUE top

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

ERRORS top

       EBUSY  Timeout while trying to resolve a symbol reference by this module.

       EEXIST A module with this name is already loaded.

       EFAULT An address argument referred to a location that is outside the
              process's accessible address space.

       EINVAL param_values is invalid, or some part of the ELF image in
              module_image contains inconsistencies.

       ENOEXEC
              The binary image supplied in module_image is not an ELF image, or is
              an ELF image that is invalid or for a different architecture.

       EPERM  The caller was not privileged (did not have the CAP_SYS_MODULE
              capability), or module loading is disabled (see
              /proc/sys/kernel/modules_disabled in proc(5)).

       In addition to the above errors, if the module's init function is executed
       and returns an error, then init_module() fails and errno is set to the
       value returned by the init function.

CONFORMING TO top

       init_module() is Linux-specific.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

       Information about currently loaded modules can be found in /proc/modules
       and in the file trees under the per-module subdirectories under
       /sys/module.

       See the Linux kernel source file include/linux/module.h for some useful
       background information.

Linux 2.4 and earlier

       In Linux 2.4 and earlier, this system call was rather different:

           #include <linux/module.h>

           int init_module(const char *name, struct module *image);

       (User-space applications can detect which version of init_module() is
       available by calling query_module(); the latter call fails with the error
       ENOSYS on Linux 2.6 and later.)

       The older version of the system call loads the relocated module image
       pointed to by image into kernel space and runs the module's init function.
       The caller is responsible for providing the relocated image (since Linux
       2.6, the init_module() system call does the relocation).

       The module image begins with a module structure and is followed by code and
       data as appropriate.  Since Linux 2.2, the module structure is defined as
       follows:

           struct module {
               unsigned long         size_of_struct;
               struct module        *next;
               const char           *name;
               unsigned long         size;
               long                  usecount;
               unsigned long         flags;
               unsigned int          nsyms;
               unsigned int          ndeps;
               struct module_symbol *syms;
               struct module_ref    *deps;
               struct module_ref    *refs;
               int                 (*init)(void);
               void                (*cleanup)(void);
               const struct exception_table_entry *ex_table_start;
               const struct exception_table_entry *ex_table_end;
           #ifdef __alpha__
               unsigned long gp;
           #endif
           };

       All of the pointer fields, with the exception of next and refs, are
       expected to point within the module body and be initialized as appropriate
       for kernel space, that is, relocated with the rest of the module.

SEE ALSO top

       create_module(2), delete_module(2), query_module(2), lsmod(8), modprobe(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-18                      INIT_MODULE(2)


inotify(7) - Linux manual page

NAME | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

INOTIFY(7)                   Linux Programmer's Manual                  INOTIFY(7)

NAME top

       inotify - monitoring file system events

DESCRIPTION top

       The inotify API provides a mechanism for monitoring file system events.
       Inotify can be used to monitor individual files, or to monitor directories.
       When a directory is monitored, inotify will return events for the directory
       itself, and for files inside the directory.

       The following system calls are used with this API: inotify_init(2) (or
       inotify_init1(2)), inotify_add_watch(2), inotify_rm_watch(2), read(2), and
       close(2).

       inotify_init(2) creates an inotify instance and returns a file descriptor
       referring to the inotify instance.  The more recent inotify_init1(2) is
       like inotify_init(2), but provides some extra functionality.

       inotify_add_watch(2) manipulates the "watch list" associated with an
       inotify instance.  Each item ("watch") in the watch list specifies the
       pathname of a file or directory, along with some set of events that the
       kernel should monitor for the file referred to by that pathname.
       inotify_add_watch(2) either creates a new watch item, or modifies an
       existing watch.  Each watch has a unique "watch descriptor", an integer
       returned by inotify_add_watch(2) when the watch is created.

       inotify_rm_watch(2) removes an item from an inotify watch list.

       When all file descriptors referring to an inotify instance have been
       closed, the underlying object and its resources are freed for reuse by the
       kernel; all associated watches are automatically freed.

       To determine what events have occurred, an application read(2)s from the
       inotify file descriptor.  If no events have so far occurred, then, assuming
       a blocking file descriptor, read(2) will block until at least one event
       occurs (unless interrupted by a signal, in which case the call fails with
       the error EINTR; see signal(7)).

       Each successful read(2) returns a buffer containing one or more of the
       following structures:

           struct inotify_event {
               int      wd;       /* Watch descriptor */
               uint32_t mask;     /* Mask of events */
               uint32_t cookie;   /* Unique cookie associating related
                                     events (for rename(2)) */
               uint32_t len;      /* Size of name field */
               char     name[];   /* Optional null-terminated name */
           };

       wd identifies the watch for which this event occurs.  It is one of the
       watch descriptors returned by a previous call to inotify_add_watch(2).

       mask contains bits that describe the event that occurred (see below).

       cookie is a unique integer that connects related events.  Currently this is
       only used for rename events, and allows the resulting pair of IN_MOVED_FROM
       and IN_MOVED_TO events to be connected by the application.  For all other
       event types, cookie is set to 0.

       The name field is only present when an event is returned for a file inside
       a watched directory; it identifies the file pathname relative to the
       watched directory.  This pathname is null-terminated, and may include
       further null bytes to align subsequent reads to a suitable address
       boundary.

       The len field counts all of the bytes in name, including the null bytes;
       the length of each inotify_event structure is thus sizeof(struct
       inotify_event)+len.

       The behavior when the buffer given to read(2) is too small to return
       information about the next event depends on the kernel version: in kernels
       before 2.6.21, read(2) returns 0; since kernel 2.6.21, read(2) fails with
       the error EINVAL.  Specifying a buffer of size

           sizeof(struct inotify_event) + NAME_MAX + 1

       will be sufficient to read at least one event.

inotify events

       The inotify_add_watch(2) mask argument and the mask field of the
       inotify_event structure returned when read(2)ing an inotify file descriptor
       are both bit masks identifying inotify events.  The following bits can be
       specified in mask when calling inotify_add_watch(2) and may be returned in
       the mask field returned by read(2):

           IN_ACCESS         File was accessed (read) (*).
           IN_ATTRIB         Metadata changed, e.g., permissions, timestamps,
                             extended attributes, link count (since Linux 2.6.25),
                             UID, GID, etc. (*).
           IN_CLOSE_WRITE    File opened for writing was closed (*).
           IN_CLOSE_NOWRITE  File not opened for writing was closed (*).
           IN_CREATE         File/directory created in watched directory (*).
           IN_DELETE         File/directory deleted from watched directory (*).
           IN_DELETE_SELF    Watched file/directory was itself deleted.
           IN_MODIFY         File was modified (*).
           IN_MOVE_SELF      Watched file/directory was itself moved.
           IN_MOVED_FROM     File moved out of watched directory (*).
           IN_MOVED_TO       File moved into watched directory (*).
           IN_OPEN           File was opened (*).

       When monitoring a directory, the events marked with an asterisk (*) above
       can occur for files in the directory, in which case the name field in the
       returned inotify_event structure identifies the name of the file within the
       directory.

       The IN_ALL_EVENTS macro is defined as a bit mask of all of the above
       events.  This macro can be used as the mask argument when calling
       inotify_add_watch(2).

       Two additional convenience macros are IN_MOVE, which equates to
       IN_MOVED_FROM|IN_MOVED_TO, and IN_CLOSE, which equates to
       IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.

       The following further bits can be specified in mask when calling
       inotify_add_watch(2):

           IN_DONT_FOLLOW (since Linux 2.6.15)
                             Don't dereference pathname if it is a symbolic link.
           IN_EXCL_UNLINK (since Linux 2.6.36)
                             By default, when watching events on the children of a
                             directory, events are generated for children even
                             after they have been unlinked from the directory.
                             This can result in large numbers of uninteresting
                             events for some applications (e.g., if watching /tmp,
                             in which many applications create temporary files
                             whose names are immediately unlinked).  Specifying
                             IN_EXCL_UNLINK changes the default behavior, so that
                             events are not generated for children after they have
                             been unlinked from the watched directory.
           IN_MASK_ADD       Add (OR) events to watch mask for this pathname if it
                             already exists (instead of replacing mask).
           IN_ONESHOT        Monitor pathname for one event, then remove from
                             watch list.
           IN_ONLYDIR (since Linux 2.6.15)
                             Only watch pathname if it is a directory.

       The following bits may be set in the mask field returned by read(2):

           IN_IGNORED        Watch was removed explicitly (inotify_rm_watch(2)) or
                             automatically (file was deleted, or file system was
                             unmounted).
           IN_ISDIR          Subject of this event is a directory.
           IN_Q_OVERFLOW     Event queue overflowed (wd is -1 for this event).
           IN_UNMOUNT        File system containing watched object was unmounted.

/proc interfaces

       The following interfaces can be used to limit the amount of kernel memory
       consumed by inotify:

       /proc/sys/fs/inotify/max_queued_events
              The value in this file is used when an application calls
              inotify_init(2) to set an upper limit on the number of events that
              can be queued to the corresponding inotify instance.  Events in
              excess of this limit are dropped, but an IN_Q_OVERFLOW event is
              always generated.

       /proc/sys/fs/inotify/max_user_instances
              This specifies an upper limit on the number of inotify instances
              that can be created per real user ID.

       /proc/sys/fs/inotify/max_user_watches
              This specifies an upper limit on the number of watches that can be
              created per real user ID.

VERSIONS top

       Inotify was merged into the 2.6.13 Linux kernel.  The required library
       interfaces were added to glibc in version 2.4.  (IN_DONT_FOLLOW,
       IN_MASK_ADD, and IN_ONLYDIR were only added in version 2.5.)

CONFORMING TO top

       The inotify API is Linux-specific.

NOTES top

       Inotify file descriptors can be monitored using select(2), poll(2), and
       epoll(7).  When an event is available, the file descriptor indicates as
       readable.

       Since Linux 2.6.25, signal-driven I/O notification is available for inotify
       file descriptors; see the discussion of F_SETFL (for setting the O_ASYNC
       flag), F_SETOWN, and F_SETSIG in fcntl(2).  The siginfo_t structure
       (described in sigaction(2)) that is passed to the signal handler has the
       following fields set: si_fd is set to the inotify file descriptor number;
       si_signo is set to the signal number; si_code is set to POLL_IN; and POLLIN
       is set in si_band.

       If successive output inotify events produced on the inotify file descriptor
       are identical (same wd, mask, cookie, and name) then they are coalesced
       into a single event if the older event has not yet been read (but see
       BUGS).

       The events returned by reading from an inotify file descriptor form an
       ordered queue.  Thus, for example, it is guaranteed that when renaming from
       one directory to another, events will be produced in the correct order on
       the inotify file descriptor.

       The FIONREAD ioctl(2) returns the number of bytes available to read from an
       inotify file descriptor.

Limitations and caveats

       Inotify monitoring of directories is not recursive: to monitor
       subdirectories under a directory, additional watches must be created.  This
       can take a significant amount time for large directory trees.

       The inotify API provides no information about the user or process that
       triggered the inotify event.

       Note that the event queue can overflow.  In this case, events are lost.
       Robust applications should handle the possibility of lost events
       gracefully.

       The inotify API identifies affected files by filename.  However, by the
       time an application processes an inotify event, the filename may already
       have been deleted or renamed.

       If monitoring an entire directory subtree, and a new subdirectory is
       created in that tree, be aware that by the time you create a watch for the
       new subdirectory, new files may already have been created in the
       subdirectory.  Therefore, you may want to scan the contents of the
       subdirectory immediately after adding the watch.

BUGS top

       In kernels before 2.6.16, the IN_ONESHOT mask flag does not work.

       Before kernel 2.6.25, the kernel code that was intended to coalesce
       successive identical events (i.e., the two most recent events could
       potentially be coalesced if the older had not yet been read) instead
       checked if the most recent event could be coalesced with the oldest unread
       event.

SEE ALSO top

       inotify_add_watch(2), inotify_init(2), inotify_init1(2),
       inotify_rm_watch(2), read(2), stat(2)

       Documentation/filesystems/inotify.txt in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2012-04-26                          INOTIFY(7)


inotify_add_watch(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

INOTIFY_ADD_WATCH(2)         Linux Programmer's Manual        INOTIFY_ADD_WATCH(2)

NAME top

       inotify_add_watch - add a watch to an initialized inotify instance

SYNOPSIS top

       #include <sys/inotify.h>

       int inotify_add_watch(int fd, const char *pathname, uint32_t mask);

DESCRIPTION top

       inotify_add_watch() adds a new watch, or modifies an existing watch, for
       the file whose location is specified in pathname; the caller must have read
       permission for this file.  The fd argument is a file descriptor referring
       to the inotify instance whose watch list is to be modified.  The events to
       be monitored for pathname are specified in the mask bit-mask argument.  See
       inotify(7) for a description of the bits that can be set in mask.

       A successful call to inotify_add_watch() returns the unique watch
       descriptor associated with pathname for this inotify instance.  If pathname
       was not previously being watched by this inotify instance, then the watch
       descriptor is newly allocated.  If pathname was already being watched, then
       the descriptor for the existing watch is returned.

       The watch descriptor is returned by later read(2)s from the inotify file
       descriptor.  These reads fetch inotify_event structures (see inotify(7))
       indicating file system events; the watch descriptor inside this structure
       identifies the object for which the event occurred.

RETURN VALUE top

       On success, inotify_add_watch() returns a nonnegative watch descriptor.  On
       error -1 is returned and errno is set appropriately.

ERRORS top

       EACCES Read access to the given file is not permitted.

       EBADF  The given file descriptor is not valid.

       EFAULT pathname points outside of the process's accessible address space.

       EINVAL The given event mask contains no valid events; or fd is not an
              inotify file descriptor.

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

       ENOMEM Insufficient kernel memory was available.

       ENOSPC The user limit on the total number of inotify watches was reached or
              the kernel failed to allocate a needed resource.

VERSIONS top

       Inotify was merged into the 2.6.13 Linux kernel.

CONFORMING TO top

       This system call is Linux-specific.

SEE ALSO top

       inotify_init(2), inotify_rm_watch(2), inotify(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-20                INOTIFY_ADD_WATCH(2)


inotify_init(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

INOTIFY_INIT(2)              Linux Programmer's Manual             INOTIFY_INIT(2)

NAME top

       inotify_init, inotify_init1 - initialize an inotify instance

SYNOPSIS top

       #include <sys/inotify.h>

       int inotify_init(void);
       int inotify_init1(int flags);

DESCRIPTION top

       inotify_init() initializes a new inotify instance and returns a file
       descriptor associated with a new inotify event queue.

       If flags is 0, then inotify_init1() is the same as inotify_init().  The
       following values can be bitwise ORed in flags to obtain different behavior:

       IN_NONBLOCK Set the O_NONBLOCK file status flag on the new open file
                   description.  Using this flag saves extra calls to fcntl(2) to
                   achieve the same result.

       IN_CLOEXEC  Set the close-on-exec (FD_CLOEXEC) flag on the new file
                   descriptor.  See the description of the O_CLOEXEC flag in
                   open(2) for reasons why this may be useful.

RETURN VALUE top

       On success, these system calls return a new file descriptor.  On error, -1
       is returned, and errno is set to indicate the error.

ERRORS top

       EINVAL (inotify_init1()) An invalid value was specified in flags.

       EMFILE The user limit on the total number of inotify instances has been
              reached.

       ENFILE The system limit on the total number of file descriptors has been
              reached.

       ENOMEM Insufficient kernel memory is available.

VERSIONS top

       inotify_init() first appeared in Linux 2.6.13; library support was added to
       glibc in version 2.4.  inotify_init1() was added in Linux 2.6.27; library
       support was added to glibc in version 2.9.

CONFORMING TO top

       These system calls are Linux-specific.

SEE ALSO top

       inotify_add_watch(2), inotify_rm_watch(2), inotify(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                     INOTIFY_INIT(2)


inotify_rm_watch(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

INOTIFY_RM_WATCH(2)          Linux Programmer's Manual         INOTIFY_RM_WATCH(2)

NAME top

       inotify_rm_watch - remove an existing watch from an inotify instance

SYNOPSIS top

       #include <sys/inotify.h>

       int inotify_rm_watch(int fd, int wd);

DESCRIPTION top

       inotify_rm_watch() removes the watch associated with the watch descriptor
       wd from the inotify instance associated with the file descriptor fd.

       Removing a watch causes an IN_IGNORED event to be generated for this watch
       descriptor.  (See inotify(7).)

RETURN VALUE top

       On success, inotify_rm_watch() returns zero, or -1 if an error occurred (in
       which case, errno is set appropriately).

ERRORS top

       EBADF  fd is not a valid file descriptor.

       EINVAL The watch descriptor wd is not valid; or fd is not an inotify file
              descriptor.

VERSIONS top

       Inotify was merged into the 2.6.13 Linux kernel.

CONFORMING TO top

       This system call is Linux-specific.

SEE ALSO top

       inotify_add_watch(2), inotify_init(2), inotify(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-15                 INOTIFY_RM_WATCH(2)


insque(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | EXAMPLE | COLOPHON The Linux Programming Interface

INSQUE(3)                    Linux Programmer's Manual                   INSQUE(3)

NAME top

       insque, remque - insert/remove an item from a queue

SYNOPSIS top

       #include <search.h>

       void insque(void *elem, void *prev);

       void remque(void *elem);

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

       insque(), remque():
           _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The insque() and remque() functions manipulate doubly-linked lists.  Each
       element in the list is a structure of which the first two elements are a
       forward and a backward pointer.  The linked list may be linear (i.e., NULL
       forward pointer at the end of the list and NULL backward pointer at the
       start of the list) or circular.

       The insque() function inserts the element pointed to by elem immediately
       after the element pointed to by prev.

       If the list is linear, then the call insque(elem, NULL) can be used to
       insert the initial list element, and the call sets the forward and backward
       pointers of elem to NULL.

       If the list is circular, the caller should ensure that the forward and
       backward pointers of the first element are initialized to point to that
       element, and the prev argument of the insque() call should also point to
       the element.

       The remque() function removes the element pointed to by elem from the
       doubly-linked list.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Traditionally (e.g., SunOS, Linux libc 4 and libc 5), the arguments of
       these functions were of type struct qelem *, defined as:

           struct qelem {
               struct qelem *q_forw;
               struct qelem *q_back;
               char          q_data[1];
           };

       This is still what you will get if _GNU_SOURCE is defined before including
       <search.h>.

       The location of the prototypes for these functions differs among several
       versions of UNIX.  The above is the POSIX version.  Some systems place them
       in <string.h>.  Linux libc4 and libc 5 placed them in <stdlib.h>.

BUGS top

       In glibc 2.4 and earlier, it was not possible to specify prev as NULL.
       Consequently, to build a linear list, the caller had to build a list using
       an initial call that contained the first two elements of the list, with the
       forward and backward pointers in each element suitably initialized.

EXAMPLE top

       The program below demonstrates the use of insque().  Here is an example run
       of the program:

           $ ./a.out -c a b c
           Traversing completed list:
               a
               b
               c
           That was a circular list

Program source

       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <search.h>

       struct element {
           struct element *forward;
           struct element *backward;
           char *name;
       };

       static struct element *
       new_element(void)
       {
           struct element *e;

           e = malloc(sizeof(struct element));
           if (e == NULL) {
               fprintf(stderr, "malloc() failed\n");
               exit(EXIT_FAILURE);
           }

           return e;
       }

       int
       main(int argc, char *argv[])
       {
           struct element *first, *elem, *prev;
           int circular, opt, errfnd;

           /* The "-c" command-line option can be used to specify that the
              list is circular */

           errfnd = 0;
           circular = 0;
           while ((opt = getopt(argc, argv, "c")) != -1) {
               switch (opt) {
               case 'c':
                   circular = 1;
                   break;
               default:
                   errfnd = 1;
                   break;
               }
           }

           if (errfnd || optind >= argc) {
               fprintf(stderr,  "Usage: %s [-c] string...\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           /* Create first element and place it in the linked list */

           elem = new_element();
           first = elem;

           elem->name = argv[optind];

           if (circular) {
               elem->forward = elem;
               elem->backward = elem;
               insque(elem, elem);
           } else {
               insque(elem, NULL);
           }

           /* Add remaining command-line arguments as list elements */

           while (++optind < argc) {
               prev = elem;

               elem = new_element();
               elem->name = argv[optind];
               insque(elem, prev);
           }

           /* Traverse the list from the start, printing element names */

           printf("Traversing completed list:\n");
           elem = first;
           do {
               printf("    %s\n", elem->name);
               elem = elem->forward;
           } while (elem != NULL && elem != first);

           if (elem == first)
               printf("That was a circular list\n");

           exit(EXIT_SUCCESS);
       }

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-09                           INSQUE(3)


intro(2) - Linux manual page

NAME | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INTRO(2)                     Linux Programmer's Manual                    INTRO(2)

NAME top

       intro - introduction to system calls

DESCRIPTION top

       Section 2 of the manual describes the Linux system calls.  A system call is
       an entry point into the Linux kernel.  Usually, system calls are not
       invoked directly: instead, most system calls have corresponding C library
       wrapper functions which perform the steps required (e.g., trapping to
       kernel mode) in order to invoke the system call.  Thus, making a system
       call looks the same as invoking a normal library function.

       For a list of the Linux system calls, see syscalls(2).

RETURN VALUE top

       On error, most system calls return a negative error number (i.e., the
       negated value of one of the constants described in errno(3)).  The C
       library wrapper hides this detail from the caller: when a system call
       returns a negative value, the wrapper copies the absolute value into the
       errno variable, and returns -1 as the return value of the wrapper.

       The value returned by a successful system call depends on the call.  Many
       system calls return 0 on success, but some can return nonzero values from a
       successful call.  The details are described in the individual manual pages.

       In some cases, the programmer must define a feature test macro in order to
       obtain the declaration of a system call from the header file specified in
       the man page SYNOPSIS section.  (Where required, these feature test macros
       must be defined before including any header files.)  In such cases, the
       required macro is described in the man page.  For further information on
       feature test macros, see feature_test_macros(7).

CONFORMING TO top

       Certain terms and abbreviations are used to indicate UNIX variants and
       standards to which calls in this section conform.  See standards(7).

NOTES top

Calling Directly

       In most cases, it is unnecessary to invoke a system call directly, but
       there are times when the Standard C library does not implement a nice
       wrapper function for you.  In this case, the programmer must manually
       invoke the system call using syscall(2).  Historically, this was also
       possible using one of the _syscall macros described in _syscall(2).

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

SEE ALSO          top
       _syscall(2), syscall(2), syscalls(2), errno(3), intro(3), capabilities(7),
       credentials(7), feature_test_macros(7), mq_overview(7), path_resolution(7),
       pipe(7), pty(7), sem_overview(7), shm_overview(7), signal(7), socket(7),
       standards(7), svipc(7), symlink(7), time(7)

COLOPHON          top
       This page is part of release 3.45 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                               2010-11-11                            INTRO(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


intro(3) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INTRO(3)                     Linux Programmer's Manual                    INTRO(3)

NAME top

       intro - introduction to library functions

DESCRIPTION top

       Section 3 of the manual describes all library functions excluding the
       library functions (system call wrappers) described in section 2, which
       implement system calls.

       Many of the functions described in the section are part of the Standard C
       Library (libc).  Some functions are part of other libraries (e.g., the math
       library, libm, or the real-time library, librt) in which case the manual
       page will indicate the linker option needed to link against the required
       library (e.g., -lm and -lrt, respectively, for the aforementioned
       libraries).

       In some cases, the programmer must define a feature test macro in order to
       obtain the declaration of a function from the header file specified in the
       man page SYNOPSIS section.  (Where required, these feature test macros must
       be defined before including any header files.)  In such cases, the required
       macro is described in the man page.  For further information on feature
       test macros, see feature_test_macros(7).

CONFORMING TO top

       Certain terms and abbreviations are used to indicate UNIX variants and
       standards to which calls in this section conform.  See standards(7).

NOTES top

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

SEE ALSO          top
       intro(2), errno(3), capabilities(7), credentials(7), environ(7),
       feature_test_macros(7), libc(7), math_error(7), path_resolution(7),
       pthreads(7), signal(7), standards(7)

COLOPHON          top
       This page is part of release 3.45 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                               2010-11-11                            INTRO(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


intro(4) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INTRO(4)                     Linux Programmer's Manual                    INTRO(4)

NAME top

       intro - introduction to special files

DESCRIPTION top

       Section 4 of the manual describes special files (devices).

FILES top

       /dev/* -- device files

NOTES top

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

SEE ALSO          top
       standards(7)

COLOPHON          top
       This page is part of release 3.45 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-10-23                            INTRO(4)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


intro(5) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INTRO(5)                     Linux Programmer's Manual                    INTRO(5)

NAME top

       intro - introduction to file formats

DESCRIPTION top

       Section 5 of the manual describes various file formats and protocols, and
       the corresponding C structures, if any.

NOTES top

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

SEE ALSO          top
       standards(7)

COLOPHON          top
       This page is part of release 3.45 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-10-23                            INTRO(5)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


intro(6) - Linux manual page

NAME | DESCRIPTION | NOTES | COLOPHON The Linux Programming Interface

INTRO(6)                     Linux Programmer's Manual                    INTRO(6)

NAME top

       intro - introduction to games

DESCRIPTION top

       Section 6 of the manual describes all the games and funny little programs
       available on the system.

NOTES top

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

COLOPHON          top
       This page is part of release 3.45 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-10-23                            INTRO(6)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


intro(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INTRO(7)                     Linux Programmer's Manual                    INTRO(7)

NAME top

       intro - introduction to overview, conventions, and miscellany section

DESCRIPTION top

       Section 7 of the manual provides overviews on various topics, and describes
       conventions and protocols, character set standards, the standard file
       system layout, and miscellaneous other things.

NOTES top

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

SEE ALSO          top
       standards(7)

COLOPHON          top
       This page is part of release 3.45 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-10-23                            INTRO(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


intro(8) - Linux manual page

NAME | DESCRIPTION | NOTES | COLOPHON The Linux Programming Interface

INTRO(8)                     Linux Programmer's Manual                    INTRO(8)

NAME top

       intro - introduction to administration and privileged commands

DESCRIPTION top

       Section 8 of the manual describes commands which either can be or are only
       used by the superuser, like system-administration commands, daemons, and
       hardware-related commands.

       As with the commands in described section 1, the commands described in this
       section terminate with an exit status that indicates whether the command
       succeeded or failed.  See intro(1) for more information.

NOTES top

Authors and Copyright Conditions

       Look at the header of the manual page source for the author(s) and
       copyright conditions.  Note that these can be different from page to page!

COLOPHON          top
       This page is part of release 3.45 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-10-23                            INTRO(8)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


ioctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IOCTL(2)                     Linux Programmer's Manual                    IOCTL(2)

NAME top

       ioctl - control device

SYNOPSIS top

       #include <sys/ioctl.h>

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

DESCRIPTION top

       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 argument 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 top

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

ERRORS top

       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 top

       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 top

       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 top

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

COLOPHON top

       This page is part of release 3.45 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)


ioctl_list(2) - Linux manual page

NAME | DESCRIPTION | RETURN VALUE | SEE ALSO | COLOPHON The Linux Programming Interface

IOCTL_LIST(2)                Linux Programmer's Manual               IOCTL_LIST(2)

NAME top

       ioctl_list - list of ioctl calls in Linux/i386 kernel

DESCRIPTION top

       This is Ioctl List 1.3.27, a list of ioctl calls in Linux/i386 kernel
       1.3.27.  It contains 421 ioctls from </usr/include/{asm,linux}/*.h>.  For
       each ioctl, its numerical value, its name, and its argument type are given.

       An argument type of const struct foo * means the argument is input to the
       kernel.  struct foo * means the kernel outputs the argument.  If the kernel
       uses the argument for both input and output, this is marked with // I-O.

       Some ioctls take more arguments or return more values than a single
       structure.  These are marked // MORE and documented further in a separate
       section.

       This list is very incomplete.

ioctl structure

       Ioctl command values are 32-bit constants.  In principle these constants
       are completely arbitrary, but people have tried to build some structure
       into them.

       The old Linux situation was that of mostly 16-bit constants, where the last
       byte is a serial number, and the preceding byte(s) give a type indicating
       the driver.  Sometimes the major number was used: 0x03 for the HDIO_*
       ioctls, 0x06 for the LP* ioctls.  And sometimes one or more ASCII letters
       were used.  For example, TCGETS has value 0x00005401, with 0x54 = 'T'
       indicating the terminal driver, and CYGETTIMEOUT has value 0x00435906, with
       0x43 0x59 = 'C' 'Y' indicating the cyclades driver.

       Later (0.98p5) some more information was built into the number.  One has 2
       direction bits (00: none, 01: write, 10: read, 11: read/write) followed by
       14 size bits (giving the size of the argument), followed by an 8-bit type
       (collecting the ioctls in groups for a common purpose or a common driver),
       and an 8-bit serial number.

       The macros describing this structure live in <asm/ioctl.h> and are
       _IO(type,nr) and {_IOR,_IOW,_IOWR}(type,nr,size).  They use sizeof(size) so
       that size is a misnomer here: this third argument is a data type.

       Note that the size bits are very unreliable: in lots of cases they are
       wrong, either because of buggy macros using sizeof(sizeof(struct)), or
       because of legacy values.

       Thus, it seems that the new structure only gave disadvantages: it does not
       help in checking, but it causes varying values for the various
       architectures.

RETURN VALUE top

       Decent ioctls return 0 on success and -1 on error, while any output value
       is stored via the argument.  However, quite a few ioctls in fact return an
       output value.  This is not yet indicated below.

       // Main table.

       // <include/asm-i386/socket.h>

       0x00008901   FIOSETOWN    const int *
       0x00008902   SIOCSPGRP    const int *
       0x00008903   FIOGETOWN    int *

       0x00008904   SIOCGPGRP    int *
       0x00008905   SIOCATMAR    int *
       0x00008906   SIOCGSTAMP   timeval *

       // <include/asm-i386/termios.h>

       0x00005401   TCGETS           struct termios *
       0x00005402   TCSETS           const struct termios *
       0x00005403   TCSETSW          const struct termios *
       0x00005404   TCSETSF          const struct termios *
       0x00005405   TCGETA           struct termio *
       0x00005406   TCSETA           const struct termio *
       0x00005407   TCSETAW          const struct termio *
       0x00005408   TCSETAF          const struct termio *
       0x00005409   TCSBRK           int
       0x0000540A   TCXONC           int
       0x0000540B   TCFLSH           int
       0x0000540C   TIOCEXCL         void
       0x0000540D   TIOCNXCL         void
       0x0000540E   TIOCSCTTY        int
       0x0000540F   TIOCGPGRP        pid_t *
       0x00005410   TIOCSPGRP        const pid_t *
       0x00005411   TIOCOUTQ         int *
       0x00005412   TIOCSTI          const char *
       0x00005413   TIOCGWINSZ       struct winsize *
       0x00005414   TIOCSWINSZ       const struct winsize *
       0x00005415   TIOCMGET         int *
       0x00005416   TIOCMBIS         const int *
       0x00005417   TIOCMBIC         const int *
       0x00005418   TIOCMSET         const int *
       0x00005419   TIOCGSOFTCAR     int *
       0x0000541A   TIOCSSOFTCAR     const int *
       0x0000541B   FIONREAD         int *
       0x0000541B   TIOCINQ          int *
       0x0000541C   TIOCLINUX        const char *                   // MORE
       0x0000541D   TIOCCONS         void
       0x0000541E   TIOCGSERIAL      struct serial_struct *
       0x0000541F   TIOCSSERIAL      const struct serial_struct *
       0x00005420   TIOCPKT          const int *
       0x00005421   FIONBIO          const int *
       0x00005422   TIOCNOTTY        void
       0x00005423   TIOCSETD         const int *
       0x00005424   TIOCGETD         int *
       0x00005425   TCSBRKP          int
       0x00005426   TIOCTTYGSTRUCT   struct tty_struct *
       0x00005450   FIONCLEX         void
       0x00005451   FIOCLEX          void
       0x00005452   FIOASYNC         const int *
       0x00005453   TIOCSERCONFIG    void
       0x00005454   TIOCSERGWILD     int *
       0x00005455   TIOCSERSWILD     const int *
       0x00005456   TIOCGLCKTRMIOS   struct termios *
       0x00005457   TIOCSLCKTRMIOS   const struct termios *
       0x00005458   TIOCSERGSTRUCT   struct async_struct *
       0x00005459   TIOCSERGETLSR    int *

       0x0000545A   TIOCSERGETMULTI   struct serial_multiport_struct *
       0x0000545B   TIOCSERSETMULTI   const struct serial_multiport_struct *

       // <include/linux/ax25.h>

       0x000089E0   SIOCAX25GETUID     const struct sockaddr_ax25 *
       0x000089E1   SIOCAX25ADDUID     const struct sockaddr_ax25 *
       0x000089E2   SIOCAX25DELUID     const struct sockaddr_ax25 *
       0x000089E3   SIOCAX25NOUID      const int *

       0x000089E4   SIOCAX25DIGCTL     const int *
       0x000089E5   SIOCAX25GETPARMS   struct ax25_parms_struct *     // I-O

       0x000089E6   SIOCAX25SETPARMS   const struct ax25_parms_struct *

       // <include/linux/cdk.h>

       0x00007314   STL_BINTR    void
       0x00007315   STL_BSTART   void
       0x00007316   STL_BSTOP    void
       0x00007317   STL_BRESET   void

       // <include/linux/cdrom.h>

       0x00005301   CDROMPAUSE        void
       0x00005302   CDROMRESUME       void
       0x00005303   CDROMPLAYMSF      const struct cdrom_msf *
       0x00005304   CDROMPLAYTRKIND   const struct cdrom_ti *
       0x00005305   CDROMREADTOCHDR   struct cdrom_tochdr *

       0x00005306   CDROMREADTOCENTRY   struct cdrom_tocentry *   // I-O

       0x00005307   CDROMSTOP        void
       0x00005308   CDROMSTART       void
       0x00005309   CDROMEJECT       void
       0x0000530A   CDROMVOLCTRL     const struct cdrom_volctrl *
       0x0000530B   CDROMSUBCHNL     struct cdrom_subchnl *            // I-O
       0x0000530C   CDROMREADMODE2   const struct cdrom_msf *          // MORE
       0x0000530D   CDROMREADMODE1   const struct cdrom_msf *          // MORE
       0x0000530E   CDROMREADAUDIO   const struct cdrom_read_audio *   // MORE
       0x0000530F   CDROMEJECT_SW    int

       0x00005310   CDROMMULTISESSION   struct cdrom_multisession *   // I-O

       0x00005311   CDROM_GET_UPC     struct { char [8]; } *
       0x00005312   CDROMRESET        void
       0x00005313   CDROMVOLREAD      struct cdrom_volctrl *
       0x00005314   CDROMREADRAW      const struct cdrom_msf *   // MORE
       0x00005315   CDROMREADCOOKED   const struct cdrom_msf *   // MORE
       0x00005316   CDROMSEEK         const struct cdrom_msf *

       // <include/linux/cm206.h>

       0x00002000   CM206CTL_GET_STAT        int
       0x00002001   CM206CTL_GET_LAST_STAT   int

       // <include/linux/cyclades.h>

       0x00435901   CYGETMON          struct cyclades_monitor *
       0x00435902   CYGETTHRESH       int *
       0x00435903   CYSETTHRESH       int
       0x00435904   CYGETDEFTHRESH    int *
       0x00435905   CYSETDEFTHRESH    int
       0x00435906   CYGETTIMEOUT      int *
       0x00435907   CYSETTIMEOUT      int
       0x00435908   CYGETDEFTIMEOUT   int *
       0x00435909   CYSETDEFTIMEOUT   int

       // <include/linux/ext2_fs.h>

       0x80046601   EXT2_IOC_GETFLAGS     int *
       0x40046602   EXT2_IOC_SETFLAGS     const int *
       0x80047601   EXT2_IOC_GETVERSION   int *
       0x40047602   EXT2_IOC_SETVERSION   const int *

       // <include/linux/fd.h>

       0x00000000   FDCLRPRM         void
       0x00000001   FDSETPRM         const struct floppy_struct *
       0x00000002   FDDEFPRM         const struct floppy_struct *
       0x00000003   FDGETPRM         struct floppy_struct *
       0x00000004   FDMSGON          void
       0x00000005   FDMSGOFF         void
       0x00000006   FDFMTBEG         void
       0x00000007   FDFMTTRK         const struct format_descr *
       0x00000008   FDFMTEND         void
       0x0000000A   FDSETEMSGTRESH   int
       0x0000000B   FDFLUSH          void
       0x0000000C   FDSETMAXERRS     const struct floppy_max_errors *
       0x0000000E   FDGETMAXERRS     struct floppy_max_errors *
       0x00000010   FDGETDRVTYP      struct { char [16]; } *
       0x00000014   FDSETDRVPRM      const struct floppy_drive_params *
       0x00000015   FDGETDRVPRM      struct floppy_drive_params *
       0x00000016   FDGETDRVSTAT     struct floppy_drive_struct *
       0x00000017   FDPOLLDRVSTAT    struct floppy_drive_struct *
       0x00000018   FDRESET          int
       0x00000019   FDGETFDCSTAT     struct floppy_fdc_state *
       0x0000001B   FDWERRORCLR      void
       0x0000001C   FDWERRORGET      struct floppy_write_errors *

       0x0000001E   FDRAWCMD    struct floppy_raw_cmd *   // MORE // I-O
       0x00000028   FDTWADDLE   void

       // <include/linux/fs.h>

       0x0000125D   BLKROSET     const int *
       0x0000125E   BLKROGET     int *
       0x0000125F   BLKRRPART    void
       0x00001260   BLKGETSIZE   unsigned long *
       0x00001261   BLKFLSBUF    void
       0x00001262   BLKRASET     int
       0x00001263   BLKRAGET     int *
       0x00000001   FIBMAP       int *             // I-O
       0x00000002   FIGETBSZ     int *

       // <include/linux/hdreg.h>

       0x00000301   HDIO_GETGEO             struct hd_geometry *
       0x00000302   HDIO_GET_UNMASKINTR     int *
       0x00000304   HDIO_GET_MULTCOUNT      int *
       0x00000307   HDIO_GET_IDENTITY       struct hd_driveid *
       0x00000308   HDIO_GET_KEEPSETTINGS   int *
       0x00000309   HDIO_GET_CHIPSET        int *
       0x0000030A   HDIO_GET_NOWERR         int *
       0x0000030B   HDIO_GET_DMA            int *
       0x0000031F   HDIO_DRIVE_CMD          int *                  // I-O
       0x00000321   HDIO_SET_MULTCOUNT      int
       0x00000322   HDIO_SET_UNMASKINTR     int
       0x00000323   HDIO_SET_KEEPSETTINGS   int
       0x00000324   HDIO_SET_CHIPSET        int
       0x00000325   HDIO_SET_NOWERR         int
       0x00000326   HDIO_SET_DMA            int

       // <include/linux/if_eql.h>

       0x000089F0   EQL_ENSLAVE       struct ifreq *   // MORE // I-O
       0x000089F1   EQL_EMANCIPATE    struct ifreq *   // MORE // I-O
       0x000089F2   EQL_GETSLAVECFG   struct ifreq *   // MORE // I-O
       0x000089F3   EQL_SETSLAVECFG   struct ifreq *   // MORE // I-O
       0x000089F4   EQL_GETMASTRCFG   struct ifreq *   // MORE // I-O
       0x000089F5   EQL_SETMASTRCFG   struct ifreq *   // MORE // I-O

       // <include/linux/if_plip.h>

       0x000089F0   SIOCDEVPLIP   struct ifreq *   // I-O

       // <include/linux/if_ppp.h>

       0x00005490   PPPIOCGFLAGS       int *
       0x00005491   PPPIOCSFLAGS       const int *
       0x00005492   PPPIOCGASYNCMAP    int *
       0x00005493   PPPIOCSASYNCMAP    const int *
       0x00005494   PPPIOCGUNIT        int *
       0x00005495   PPPIOCSINPSIG      const int *
       0x00005497   PPPIOCSDEBUG       const int *
       0x00005498   PPPIOCGDEBUG       int *
       0x00005499   PPPIOCGSTAT        struct ppp_stats *
       0x0000549A   PPPIOCGTIME        struct ppp_ddinfo *
       0x0000549B   PPPIOCGXASYNCMAP   struct { int [8]; } *
       0x0000549C   PPPIOCSXASYNCMAP   const struct { int [8]; } *
       0x0000549D   PPPIOCSMRU         const int *
       0x0000549E   PPPIOCRASYNCMAP    const int *
       0x0000549F   PPPIOCSMAXCID      const int *

       // <include/linux/ipx.h>

       0x000089E0   SIOCAIPXITFCRT   const char *
       0x000089E1   SIOCAIPXPRISLT   const char *
       0x000089E2   SIOCIPXCFGDATA   struct ipx_config_data *

       // <include/linux/kd.h>

       0x00004B60   GIO_FONT   struct { char [8192]; } *
       0x00004B61   PIO_FONT   const struct { char [8192]; } *

       0x00004B6B  GIO_FONTX  struct console_font_desc *        // MORE // I-O
       0x00004B6C  PIO_FONTX  const struct console_font_desc *  //MORE

       0x00004B70   GIO_CMAP   struct { char [48]; } *
       0x00004B71   PIO_CMAP   const struct { char [48]; }

       0x00004B2F   KIOCSOUND     int
       0x00004B30   KDMKTONE      int
       0x00004B31   KDGETLED      char *
       0x00004B32   KDSETLED      int
       0x00004B33   KDGKBTYPE     char *
       0x00004B34   KDADDIO       int                            // MORE
       0x00004B35   KDDELIO       int                            // MORE
       0x00004B36   KDENABIO      void                           // MORE
       0x00004B37   KDDISABIO     void                           // MORE
       0x00004B3A   KDSETMODE     int
       0x00004B3B   KDGETMODE     int *
       0x00004B3C   KDMAPDISP     void                           // MORE
       0x00004B3D   KDUNMAPDISP   void                           // MORE
       0x00004B40   GIO_SCRNMAP   struct { char [E_TABSZ]; } *

       0x00004B41   PIO_SCRNMAP      const struct { char [E_TABSZ]; } *
       0x00004B69   GIO_UNISCRNMAP   struct { short [E_TABSZ]; } *
       0x00004B6A   PIO_UNISCRNMAP   const struct { short [E_TABSZ]; } *

       0x00004B66   GIO_UNIMAP      struct unimapdesc *         // MORE // I-O
       0x00004B67   PIO_UNIMAP      const struct unimapdesc *   // MORE
       0x00004B68   PIO_UNIMAPCLR   const struct unimapinit *
       0x00004B44   KDGKBMODE       int *
       0x00004B45   KDSKBMODE       int
       0x00004B62   KDGKBMETA       int *
       0x00004B63   KDSKBMETA       int

       0x00004B64   KDGKBLED        int *
       0x00004B65   KDSKBLED        int
       0x00004B46   KDGKBENT        struct kbentry *            // I-O
       0x00004B47   KDSKBENT        const struct kbentry *
       0x00004B48   KDGKBSENT       struct kbsentry *           // I-O
       0x00004B49   KDSKBSENT       const struct kbsentry *
       0x00004B4A   KDGKBDIACR      struct kbdiacrs *
       0x00004B4B   KDSKBDIACR      const struct kbdiacrs *
       0x00004B4C   KDGETKEYCODE    struct kbkeycode *          // I-O
       0x00004B4D   KDSETKEYCODE    const struct kbkeycode *
       0x00004B4E   KDSIGACCEPT     int

       // <include/linux/lp.h>

       0x00000601   LPCHAR        int
       0x00000602   LPTIME        int
       0x00000604   LPABORT       int
       0x00000605   LPSETIRQ      int
       0x00000606   LPGETIRQ      int *
       0x00000608   LPWAIT        int
       0x00000609   LPCAREFUL     int
       0x0000060A   LPABORTOPEN   int
       0x0000060B   LPGETSTATUS   int *
       0x0000060C   LPRESET       void
       0x0000060D   LPGETSTATS    struct lp_stats *

       // <include/linux/mroute.h>

       0x000089E0   SIOCGETVIFCNT   struct sioc_vif_req *   // I-O
       0x000089E1   SIOCGETSGCNT    struct sioc_sg_req *    // I-O

       // <include/linux/mtio.h>

       0x40086D01   MTIOCTOP         const struct mtop *
       0x801C6D02   MTIOCGET         struct mtget *
       0x80046D03   MTIOCPOS         struct mtpos *
       0x80206D04   MTIOCGETCONFIG   struct mtconfiginfo *
       0x40206D05   MTIOCSETCONFIG   const struct mtconfiginfo *

       // <include/linux/netrom.h>

       0x000089E0   SIOCNRGETPARMS   struct nr_parms_struct *         // I-O
       0x000089E1   SIOCNRSETPARMS   const struct nr_parms_struct *
       0x000089E2   SIOCNRDECOBS     void
       0x000089E3   SIOCNRRTCTL      const int *

       // <include/linux/sbpcd.h>

       0x00009000   DDIOCSDBG          const int *
       0x00005382   CDROMAUDIOBUFSIZ   int

       // <include/linux/scc.h>

       0x00005470   TIOCSCCINI    void
       0x00005471   TIOCCHANINI   const struct scc_modem *
       0x00005472   TIOCGKISS     struct ioctl_command *         // I-O
       0x00005473   TIOCSKISS     const struct ioctl_command *
       0x00005474   TIOCSCCSTAT   struct scc_stat *

       // <include/linux/scsi.h>

       0x00005382   SCSI_IOCTL_GET_IDLUN        struct { int [2]; } *
       0x00005383   SCSI_IOCTL_TAGGED_ENABLE    void
       0x00005384   SCSI_IOCTL_TAGGED_DISABLE   void

       0x00005385   SCSI_IOCTL_PROBE_HOST   const int *   // MORE

       // <include/linux/smb_fs.h>

       0x80027501   SMB_IOC_GETMOUNTUID   uid_t *

       // <include/linux/sockios.h>

       0x0000890B   SIOCADDRT        const struct rtentry *   // MORE
       0x0000890C   SIOCDELRT        const struct rtentry *   // MORE
       0x00008910   SIOCGIFNAME      char []
       0x00008911   SIOCSIFLINK      void
       0x00008912   SIOCGIFCONF      struct ifconf *          // MORE // I-O
       0x00008913   SIOCGIFFLAGS     struct ifreq *           // I-O
       0x00008914   SIOCSIFFLAGS     const struct ifreq *
       0x00008915   SIOCGIFADDR      struct ifreq *           // I-O
       0x00008916   SIOCSIFADDR      const struct ifreq *
       0x00008917   SIOCGIFDSTADDR   struct ifreq *           // I-O
       0x00008918   SIOCSIFDSTADDR   const struct ifreq *
       0x00008919   SIOCGIFBRDADDR   struct ifreq *           // I-O
       0x0000891A   SIOCSIFBRDADDR   const struct ifreq *
       0x0000891B   SIOCGIFNETMASK   struct ifreq *           // I-O
       0x0000891C   SIOCSIFNETMASK   const struct ifreq *
       0x0000891D   SIOCGIFMETRIC    struct ifreq *           // I-O
       0x0000891E   SIOCSIFMETRIC    const struct ifreq *
       0x0000891F   SIOCGIFMEM       struct ifreq *           // I-O
       0x00008920   SIOCSIFMEM       const struct ifreq *
       0x00008921   SIOCGIFMTU       struct ifreq *           // I-O
       0x00008922   SIOCSIFMTU       const struct ifreq *

       0x00008923   OLD_SIOCGIFHWADDR   struct ifreq *          // I-O
       0x00008924   SIOCSIFHWADDR       const struct ifreq *    // MORE
       0x00008925   SIOCGIFENCAP        int *
       0x00008926   SIOCSIFENCAP        const int *
       0x00008927   SIOCGIFHWADDR       struct ifreq *          // I-O
       0x00008929   SIOCGIFSLAVE        void
       0x00008930   SIOCSIFSLAVE        void
       0x00008931   SIOCADDMULTI        const struct ifreq *
       0x00008932   SIOCDELMULTI        const struct ifreq *
       0x00008940   SIOCADDRTOLD        void
       0x00008941   SIOCDELRTOLD        void
       0x00008950   SIOCDARP            const struct arpreq *
       0x00008951   SIOCGARP            struct arpreq *         // I-O
       0x00008952   SIOCSARP            const struct arpreq *
       0x00008960   SIOCDRARP           const struct arpreq *
       0x00008961   SIOCGRARP           struct arpreq *         // I-O
       0x00008962   SIOCSRARP           const struct arpreq *
       0x00008970   SIOCGIFMAP          struct ifreq *          // I-O
       0x00008971   SIOCSIFMAP          const struct ifreq *

       // <include/linux/soundcard.h>

       0x00005100   SNDCTL_SEQ_RESET   void
       0x00005101   SNDCTL_SEQ_SYNC    void

       0xC08C5102   SNDCTL_SYNTH_INFO        struct synth_info *   // I-O
       0xC0045103   SNDCTL_SEQ_CTRLRATE      int *                 // I-O
       0x80045104   SNDCTL_SEQ_GETOUTCOUNT   int *
       0x80045105   SNDCTL_SEQ_GETINCOUNT    int *
       0x40045106   SNDCTL_SEQ_PERCMODE      void

       0x40285107   SNDCTL_FM_LOAD_INSTR   const struct sbi_instrument *

       0x40045108   SNDCTL_SEQ_TESTMIDI       const int *
       0x40045109   SNDCTL_SEQ_RESETSAMPLES   const int *

       0x8004510A   SNDCTL_SEQ_NRSYNTHS       int *
       0x8004510B   SNDCTL_SEQ_NRMIDIS        int *
       0xC074510C   SNDCTL_MIDI_INFO          struct midi_info *     // I-O
       0x4004510D   SNDCTL_SEQ_THRESHOLD      const int *
       0xC004510E   SNDCTL_SYNTH_MEMAVL       int *                  // I-O
       0x4004510F   SNDCTL_FM_4OP_ENABLE      const int *
       0xCFB85110   SNDCTL_PMGR_ACCESS        struct patmgr_info *   // I-O
       0x00005111   SNDCTL_SEQ_PANIC          void

       0x40085112   SNDCTL_SEQ_OUTOFBAND   const struct seq_event_rec *

       0xC0045401   SNDCTL_TMR_TIMEBASE    int *                  // I-O
       0x00005402   SNDCTL_TMR_START       void
       0x00005403   SNDCTL_TMR_STOP        void
       0x00005404   SNDCTL_TMR_CONTINUE    void
       0xC0045405   SNDCTL_TMR_TEMPO       int *                  // I-O
       0xC0045406   SNDCTL_TMR_SOURCE      int *                  // I-O
       0x40045407   SNDCTL_TMR_METRONOME   const int *
       0x40045408   SNDCTL_TMR_SELECT      int *                  // I-O
       0xCFB85001   SNDCTL_PMGR_IFACE      struct patmgr_info *   // I-O
       0xC0046D00   SNDCTL_MIDI_PRETIME    int *                  // I-O
       0xC0046D01   SNDCTL_MIDI_MPUMODE    const int *

       0xC0216D02   SNDCTL_MIDI_MPUCMD   struct mpu_command_rec *   // I-O

       0x00005000   SNDCTL_DSP_RESET           void
       0x00005001   SNDCTL_DSP_SYNC            void
       0xC0045002   SNDCTL_DSP_SPEED           int *   // I-O
       0xC0045003   SNDCTL_DSP_STEREO          int *   // I-O
       0xC0045004   SNDCTL_DSP_GETBLKSIZE      int *   // I-O
       0xC0045006   SOUND_PCM_WRITE_CHANNELS   int *   // I-O
       0xC0045007   SOUND_PCM_WRITE_FILTER     int *   // I-O
       0x00005008   SNDCTL_DSP_POST            void
       0xC0045009   SNDCTL_DSP_SUBDIVIDE       int *   // I-O
       0xC004500A   SNDCTL_DSP_SETFRAGMENT     int *   // I-O
       0x8004500B   SNDCTL_DSP_GETFMTS         int *
       0xC0045005   SNDCTL_DSP_SETFMT          int *   // I-O

       0x800C500C   SNDCTL_DSP_GETOSPACE      struct audio_buf_info *
       0x800C500D   SNDCTL_DSP_GETISPACE      struct audio_buf_info *
       0x0000500E   SNDCTL_DSP_NONBLOCK       void
       0x80045002   SOUND_PCM_READ_RATE       int *
       0x80045006   SOUND_PCM_READ_CHANNELS   int *
       0x80045005   SOUND_PCM_READ_BITS       int *
       0x80045007   SOUND_PCM_READ_FILTER     int *
       0x00004300   SNDCTL_COPR_RESET         void
       0xCFB04301   SNDCTL_COPR_LOAD          const struct copr_buffer *

       0xC0144302   SNDCTL_COPR_RDATA   struct copr_debug_buf *   // I-O
       0xC0144303   SNDCTL_COPR_RCODE   struct copr_debug_buf *   // I-O

       0x40144304   SNDCTL_COPR_WDATA   const struct copr_debug_buf *
       0x40144305   SNDCTL_COPR_WCODE   const struct copr_debug_buf *

       0xC0144306   SNDCTL_COPR_RUN    struct copr_debug_buf *   // I-O
       0xC0144307   SNDCTL_COPR_HALT   struct copr_debug_buf *   // I-O

       0x4FA44308   SNDCTL_COPR_SENDMSG           const struct copr_msg *
       0x8FA44309   SNDCTL_COPR_RCVMSG            struct copr_msg *
       0x80044D00   SOUND_MIXER_READ_VOLUME       int *
       0x80044D01   SOUND_MIXER_READ_BASS         int *
       0x80044D02   SOUND_MIXER_READ_TREBLE       int *
       0x80044D03   SOUND_MIXER_READ_SYNTH        int *
       0x80044D04   SOUND_MIXER_READ_PCM          int *
       0x80044D05   SOUND_MIXER_READ_SPEAKER      int *

       0x80044D06   SOUND_MIXER_READ_LINE         int *
       0x80044D07   SOUND_MIXER_READ_MIC          int *
       0x80044D08   SOUND_MIXER_READ_CD           int *
       0x80044D09   SOUND_MIXER_READ_IMIX         int *
       0x80044D0A   SOUND_MIXER_READ_ALTPCM       int *
       0x80044D0B   SOUND_MIXER_READ_RECLEV       int *
       0x80044D0C   SOUND_MIXER_READ_IGAIN        int *
       0x80044D0D   SOUND_MIXER_READ_OGAIN        int *
       0x80044D0E   SOUND_MIXER_READ_LINE1        int *
       0x80044D0F   SOUND_MIXER_READ_LINE2        int *
       0x80044D10   SOUND_MIXER_READ_LINE3        int *
       0x80044D1C   SOUND_MIXER_READ_MUTE         int *
       0x80044D1D   SOUND_MIXER_READ_ENHANCE      int *
       0x80044D1E   SOUND_MIXER_READ_LOUD         int *
       0x80044DFF   SOUND_MIXER_READ_RECSRC       int *
       0x80044DFE   SOUND_MIXER_READ_DEVMASK      int *
       0x80044DFD   SOUND_MIXER_READ_RECMASK      int *
       0x80044DFB   SOUND_MIXER_READ_STEREODEVS   int *
       0x80044DFC   SOUND_MIXER_READ_CAPS         int *

       0xC0044D00   SOUND_MIXER_WRITE_VOLUME    int *   // I-O
       0xC0044D01   SOUND_MIXER_WRITE_BASS      int *   // I-O
       0xC0044D02   SOUND_MIXER_WRITE_TREBLE    int *   // I-O
       0xC0044D03   SOUND_MIXER_WRITE_SYNTH     int *   // I-O
       0xC0044D04   SOUND_MIXER_WRITE_PCM       int *   // I-O
       0xC0044D05   SOUND_MIXER_WRITE_SPEAKER   int *   // I-O
       0xC0044D06   SOUND_MIXER_WRITE_LINE      int *   // I-O
       0xC0044D07   SOUND_MIXER_WRITE_MIC       int *   // I-O
       0xC0044D08   SOUND_MIXER_WRITE_CD        int *   // I-O
       0xC0044D09   SOUND_MIXER_WRITE_IMIX      int *   // I-O
       0xC0044D0A   SOUND_MIXER_WRITE_ALTPCM    int *   // I-O
       0xC0044D0B   SOUND_MIXER_WRITE_RECLEV    int *   // I-O
       0xC0044D0C   SOUND_MIXER_WRITE_IGAIN     int *   // I-O
       0xC0044D0D   SOUND_MIXER_WRITE_OGAIN     int *   // I-O
       0xC0044D0E   SOUND_MIXER_WRITE_LINE1     int *   // I-O
       0xC0044D0F   SOUND_MIXER_WRITE_LINE2     int *   // I-O
       0xC0044D10   SOUND_MIXER_WRITE_LINE3     int *   // I-O
       0xC0044D1C   SOUND_MIXER_WRITE_MUTE      int *   // I-O
       0xC0044D1D   SOUND_MIXER_WRITE_ENHANCE   int *   // I-O
       0xC0044D1E   SOUND_MIXER_WRITE_LOUD      int *   // I-O
       0xC0044DFF   SOUND_MIXER_WRITE_RECSRC    int *   // I-O

       // <include/linux/umsdos_fs.h>

       0x000004D2   UMSDOS_READDIR_DOS   struct umsdos_ioctl *         // I-O
       0x000004D3   UMSDOS_UNLINK_DOS    const struct umsdos_ioctl *
       0x000004D4   UMSDOS_RMDIR_DOS     const struct umsdos_ioctl *
       0x000004D5   UMSDOS_STAT_DOS      struct umsdos_ioctl *         // I-O
       0x000004D6   UMSDOS_CREAT_EMD     const struct umsdos_ioctl *
       0x000004D7   UMSDOS_UNLINK_EMD    const struct umsdos_ioctl *
       0x000004D8   UMSDOS_READDIR_EMD   struct umsdos_ioctl *         // I-O
       0x000004D9   UMSDOS_GETVERSION    struct umsdos_ioctl *
       0x000004DA   UMSDOS_INIT_EMD      void
       0x000004DB   UMSDOS_DOS_SETUP     const struct umsdos_ioctl *
       0x000004DC   UMSDOS_RENAME_DOS    const struct umsdos_ioctl *

       // <include/linux/vt.h>

       0x00005600   VT_OPENQRY       int *
       0x00005601   VT_GETMODE       struct vt_mode *
       0x00005602   VT_SETMODE       const struct vt_mode *
       0x00005603   VT_GETSTATE      struct vt_stat *
       0x00005604   VT_SENDSIG       void
       0x00005605   VT_RELDISP       int
       0x00005606   VT_ACTIVATE      int

       0x00005607   VT_WAITACTIVE    int
       0x00005608   VT_DISALLOCATE   int
       0x00005609   VT_RESIZE        const struct vt_sizes *
       0x0000560A   VT_RESIZEX       const struct vt_consize *

       // More arguments.  Some ioctl's take a pointer to a structure which
       contains additional pointers.  These are documented here in alphabetical
       order.

       CDROMREADAUDIO takes an input pointer const struct cdrom_read_audio *.  The
       buf field points to an output buffer of length nframes * CD_FRAMESIZE_RAW.

       CDROMREADCOOKED, CDROMREADMODE1, CDROMREADMODE2, and CDROMREADRAW take an
       input pointer const struct cdrom_msf *.  They use the same pointer as an
       output pointer to char [].  The length varies by request.  For
       CDROMREADMODE1, most drivers use CD_FRAMESIZE, but the Optics Storage
       driver uses OPT_BLOCKSIZE instead (both have the numerical value 2048).

           CDROMREADCOOKED    char [CD_FRAMESIZE]
           CDROMREADMODE1     char [CD_FRAMESIZE or OPT_BLOCKSIZE]
           CDROMREADMODE2     char [CD_FRAMESIZE_RAW0]
           CDROMREADRAW       char [CD_FRAMESIZE_RAW]

       EQL_ENSLAVE, EQL_EMANCIPATE, EQL_GETSLAVECFG, EQL_SETSLAVECFG,
       EQL_GETMASTERCFG, and EQL_SETMASTERCFG take a struct ifreq *.  The ifr_data
       field is a pointer to another structure as follows:

           EQL_ENSLAVE         const struct slaving_request *
           EQL_EMANCIPATE      const struct slaving_request *
           EQL_GETSLAVECFG     struct slave_config *           // I-O
           EQL_SETSLAVECFG     const struct slave_config *
           EQL_GETMASTERCFG    struct master_config *
           EQL_SETMASTERCFG    const struct master_config *

       FDRAWCMD takes a struct floppy raw_cmd *.  If flags & FD_RAW_WRITE is
       nonzero, then data points to an input buffer of length length.  If flags &
       FD_RAW_READ is nonzero, then data points to an output buffer of length
       length.

       GIO_FONTX and PIO_FONTX take a struct console_font_desc * or a const struct
       console_font_desc *, respectively.  chardata points to a buffer of char
       [charcount].  This is an output buffer for GIO_FONTX and an input buffer
       for PIO_FONTX.

       GIO_UNIMAP and PIO_UNIMAP take a struct unimapdesc * or a const struct
       unimapdesc *, respectively.  entries points to a buffer of struct unipair
       [entry_ct].  This is an output buffer for GIO_UNIMAP and an input buffer
       for PIO_UNIMAP.

       KDADDIO, KDDELIO, KDDISABIO, and KDENABIO enable or disable access to I/O
       ports.  They are essentially alternate interfaces to 'ioperm'.

       KDMAPDISP and KDUNMAPDISP enable or disable memory mappings or I/O port
       access.  They are not implemented in the kernel.

       SCSI_IOCTL_PROBE_HOST takes an input pointer const int *, which is a
       length.  It uses the same pointer as an output pointer to a char [] buffer
       of this length.

       SIOCADDRT and SIOCDELRT take an input pointer whose type depends on the
       protocol:

           Most protocols      const struct rtentry *
           AX.25               const struct ax25_route *
           NET/ROM             const struct nr_route_struct *

       SIOCGIFCONF takes a struct ifconf *.  The ifc_buf field points to a buffer
       of length ifc_len bytes, into which the kernel writes a list of type struct
       ifreq [].

       SIOCSIFHWADDR takes an input pointer whose type depends on the protocol:

           Most protocols      const struct ifreq *
           AX.25               const char [AX25_ADDR_LEN]

       TIOCLINUX takes a const char *.  It uses this to distinguish several
       independent subcases.  In the table below, N + foo means foo after an N-
       byte pad.  struct selection is implicitly defined in
       drivers/char/selection.c

           TIOCLINUX-2         1 + const struct selection *
           TIOCLINUX-3         void
           TIOCLINUX-4         void
           TIOCLINUX-5         4 + const struct { long [8]; } *
           TIOCLINUX-6         char *
           TIOCLINUX-7         char *
           TIOCLINUX-10        1 + const char *

       // Duplicate ioctls

       This list does not include ioctls in the range SIOCDEVPRIVATE and
       SIOCPROTOPRIVATE.

       0x00000001   FDSETPRM              FIBMAP
       0x00000002   FDDEFPRM              FIGETBSZ
       0x00005382   CDROMAUDIOBUFSIZ      SCSI_IOCTL_GET_IDLUN
       0x00005402   SNDCTL_TMR_START      TCSETS
       0x00005403   SNDCTL_TMR_STOP       TCSETSW
       0x00005404   SNDCTL_TMR_CONTINUE   TCSETSF

SEE ALSO top

       ioctl(2)

COLOPHON top

       This page is part of release 3.45 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-12-29                       IOCTL_LIST(2)


ioperm(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IOPERM(2)                    Linux Programmer's Manual                   IOPERM(2)

NAME top

       ioperm - set port input/output permissions

SYNOPSIS top

       #include <unistd.h> /* for libc5 */
       #include <sys/io.h> /* for glibc */

       int ioperm(unsigned long from, unsigned long num, int turn_on);

DESCRIPTION top

       ioperm() sets the port access permission bits for the calling process for
       num bytes starting from port address from to the value turn_on.  If turn_on
       is nonzero, the calling process must be privileged (CAP_SYS_RAWIO).

       Only the first 0x3ff I/O ports can be specified in this manner.  For more
       ports, the iopl(2) system call must be used.

       Permissions are not inherited by the child created by fork(2).  Permissions
       are preserved across execve(2); this is useful for giving port access
       permissions to unprivileged programs.

       This call is mostly for the i386 architecture.  On many other architectures
       it does not exist or will always return an error.

RETURN VALUE top

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

ERRORS top

       EINVAL Invalid values for from or num.

       EIO    (on PowerPC) This call is not supported.

       ENOMEM Out of memory.

       EPERM  The calling process has insufficient privilege.

CONFORMING TO top

       ioperm() is Linux-specific and should not be used in programs intended to
       be portable.

NOTES top

       Libc5 treats it as a system call and has a prototype in <unistd.h>.  Glibc1
       does not have a prototype.  Glibc2 has a prototype both in <sys/io.h> and
       in <sys/perm.h>.  Avoid the latter, it is available on i386 only.

SEE ALSO top

       iopl(2), capabilities(7)

COLOPHON top

       This page is part of release 3.45 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-06-15                           IOPERM(2)


iopl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IOPL(2)                      Linux Programmer's Manual                     IOPL(2)

NAME top

       iopl - change I/O privilege level

SYNOPSIS top

       #include <sys/io.h>

       int iopl(int level);

DESCRIPTION top

       iopl() changes the I/O privilege level of the calling process, as specified
       in level.

       This call is necessary to allow 8514-compatible X servers to run under
       Linux.  Since these X servers require access to all 65536 I/O ports, the
       ioperm(2) call is not sufficient.

       In addition to granting unrestricted I/O port access, running at a higher
       I/O privilege level also allows the process to disable interrupts.  This
       will probably crash the system, and is not recommended.

       Permissions are inherited by fork(2) and execve(2).

       The I/O privilege level for a normal process is 0.

       This call is mostly for the i386 architecture.  On many other architectures
       it does not exist or will always return an error.

RETURN VALUE top

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

ERRORS top

       EINVAL level is greater than 3.

       ENOSYS This call is unimplemented.

       EPERM  The calling process has insufficient privilege to call iopl(); the
              CAP_SYS_RAWIO capability is required.

CONFORMING TO top

       iopl() is Linux-specific and should not be used in processes intended to be
       portable.

NOTES top

       Libc5 treats it as a system call and has a prototype in <unistd.h>.  Glibc1
       does not have a prototype.  Glibc2 has a prototype both in <sys/io.h> and
       in <sys/perm.h>.  Avoid the latter, it is available on i386 only.

SEE ALSO top

       ioperm(2), capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2004-05-27                             IOPL(2)


ioprio_set(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

IOPRIO_SET(2)                Linux Programmer's Manual               IOPRIO_SET(2)

NAME top

       ioprio_get, ioprio_set - get/set I/O scheduling class and priority

SYNOPSIS top

       int ioprio_get(int which, int who);
       int ioprio_set(int which, int who, int ioprio);

       Note: There are no glibc wrappers for these system calls; see NOTES.

DESCRIPTION top

       The ioprio_get() and ioprio_set() system calls respectively get and set the
       I/O scheduling class and priority of one or more threads.

       The which and who arguments identify the thread(s) on which the system
       calls operate.  The which argument determines how who is interpreted, and
       has one of the following values:

       IOPRIO_WHO_PROCESS
              who is a process ID or thread ID identifying a single process or
              thread.  If who is 0, then operate on the calling thread.

       IOPRIO_WHO_PGRP
              who is a process group ID identifying all the members of a process
              group.  If who is 0, then operate on the process group of which the
              caller is a member.

       IOPRIO_WHO_USER
              who is a user ID identifying all of the processes that have a
              matching real UID.

       If which is specified as IOPRIO_WHO_PGRP or IOPRIO_WHO_USER when calling
       ioprio_get(), and more than one process matches who, then the returned
       priority will be the highest one found among all of the matching processes.
       One priority is said to be higher than another one if it belongs to a
       higher priority class (IOPRIO_CLASS_RT is the highest priority class;
       IOPRIO_CLASS_IDLE is the lowest) or if it belongs to the same priority
       class as the other process but has a higher priority level (a lower
       priority number means a higher priority level).

       The ioprio argument given to ioprio_set() is a bit mask that specifies both
       the scheduling class and the priority to be assigned to the target
       process(es).  The following macros are used for assembling and dissecting
       ioprio values:

       IOPRIO_PRIO_VALUE(class, data)
              Given a scheduling class and priority (data), this macro combines
              the two values to produce an ioprio value, which is returned as the
              result of the macro.

       IOPRIO_PRIO_CLASS(mask)
              Given mask (an ioprio value), this macro returns its I/O class
              component, that is, one of the values IOPRIO_CLASS_RT,
              IOPRIO_CLASS_BE, or IOPRIO_CLASS_IDLE.

       IOPRIO_PRIO_DATA(mask)
              Given mask (an ioprio value), this macro returns its priority (data)
              component.

       See the NOTES section for more information on scheduling classes and
       priorities.

       I/O priorities are supported for reads and for synchronous (O_DIRECT,
       O_SYNC) writes.  I/O priorities are not supported for asynchronous writes
       because they are issued outside the context of the program dirtying the
       memory, and thus program-specific priorities do not apply.

RETURN VALUE top

       On success, ioprio_get() returns the ioprio value of the process with
       highest I/O priority of any of the processes that match the criteria
       specified in which and who.  On error, -1 is returned, and errno is set to
       indicate the error.

       On success, ioprio_set() returns 0.  On error, -1 is returned, and errno is
       set to indicate the error.

ERRORS top

       EINVAL Invalid value for which or ioprio.  Refer to the NOTES section for
              available scheduler classes and priority levels for ioprio.

       EPERM  The calling process does not have the privilege needed to assign
              this ioprio to the specified process(es).  See the NOTES section for
              more information on required privileges for ioprio_set().

       ESRCH  No process(es) could be found that matched the specification in
              which and who.

VERSIONS top

       These system calls have been available on Linux since kernel 2.6.13.

CONFORMING TO top

       These system calls are Linux-specific.

NOTES top

       Glibc does not provide a wrapper for these system calls; call them using
       syscall(2).

       Two or more processes or threads can share an I/O context.  This will be
       the case when clone(2) was called with the CLONE_IO flag.  However, by
       default, the distinct threads of a process will not share the same I/O
       context.  This means that if you want to change the I/O priority of all
       threads in a process, you may need to call ioprio_set() on each of the
       threads.  The thread ID that you would need for this operation is the one
       that is returned by gettid(2) or clone(2).

       These system calls only have an effect when used in conjunction with an I/O
       scheduler that supports I/O priorities.  As at kernel 2.6.17 the only such
       scheduler is the Completely Fair Queuing (CFQ) I/O scheduler.

Selecting an I/O Scheduler

       I/O Schedulers are selected on a per-device basis via the special file
       /sys/block/<device>/queue/scheduler.

       One can view the current I/O scheduler via the /sys file system.  For
       example, the following command displays a list of all schedulers currently
       loaded in the kernel:

              $ cat /sys/block/hda/queue/scheduler
              noop anticipatory deadline [cfq]

       The scheduler surrounded by brackets is the one actually in use for the
       device (hda in the example).  Setting another scheduler is done by writing
       the name of the new scheduler to this file.  For example, the following
       command will set the scheduler for the hda device to cfq:

              $ su
              Password:
              # echo cfq > /sys/block/hda/queue/scheduler

The Completely Fair Queuing (CFQ) I/O Scheduler

       Since v3 (aka CFQ Time Sliced) CFQ implements I/O nice levels similar to
       those of CPU scheduling.  These nice levels are grouped in three scheduling
       classes each one containing one or more priority levels:

       IOPRIO_CLASS_RT (1)
              This is the real-time I/O class.  This scheduling class is given
              higher priority than any other class: processes from this class are
              given first access to the disk every time.  Thus this I/O class
              needs to be used with some care: one I/O real-time process can
              starve the entire system.  Within the real-time class, there are 8
              levels of class data (priority) that determine exactly how much time
              this process needs the disk for on each service.  The highest real-
              time priority level is 0; the lowest is 7.  In the future this might
              change to be more directly mappable to performance, by passing in a
              desired data rate instead.

       IOPRIO_CLASS_BE (2)
              This is the best-effort scheduling class, which is the default for
              any process that hasn't set a specific I/O priority.  The class data
              (priority) determines how much I/O bandwidth the process will get.
              Best-effort priority levels are analogous to CPU nice values (see
              getpriority(2)).  The priority level determines a priority relative
              to other processes in the best-effort scheduling class.  Priority
              levels range from 0 (highest) to 7 (lowest).

       IOPRIO_CLASS_IDLE (3)
              This is the idle scheduling class.  Processes running at this level
              only get I/O time when no-one else needs the disk.  The idle class
              has no class data.  Attention is required when assigning this
              priority class to a process, since it may become starved if higher
              priority processes are constantly accessing the disk.

       Refer to Documentation/block/ioprio.txt for more information on the CFQ I/O
       Scheduler and an example program.

Required permissions to set I/O priorities

       Permission to change a process's priority is granted or denied based on two
       assertions:

       Process ownership
              An unprivileged process may only set the I/O priority of a process
              whose real UID matches the real or effective UID of the calling
              process.  A process which has the CAP_SYS_NICE capability can change
              the priority of any process.

       What is the desired priority
              Attempts to set very high priorities (IOPRIO_CLASS_RT) require the
              CAP_SYS_ADMIN capability.  Kernel versions up to 2.6.24 also
              required CAP_SYS_ADMIN to set a very low priority
              (IOPRIO_CLASS_IDLE), but since Linux 2.6.25, this is no longer
              required.

       A call to ioprio_set() must follow both rules, or the call will fail with
       the error EPERM.

BUGS top

       Glibc does not yet provide a suitable header file defining the function
       prototypes and macros described on this page.  Suitable definitions can be
       found in linux/ioprio.h.

SEE ALSO top

       getpriority(2), open(2), capabilities(7)

       Documentation/block/ioprio.txt in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2012-07-29                       IOPRIO_SET(2)


io_cancel(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IO_CANCEL(2)                 Linux Programmer's Manual                IO_CANCEL(2)

NAME top

       io_cancel - cancel an outstanding asynchronous I/O operation

SYNOPSIS top

       #include <linux/aio_abi.h>          /* Defines needed types */

       int io_cancel(aio_context_t ctx_id, struct iocb *iocb,
                     struct io_event *result);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The io_cancel() system call attempts to cancel an asynchronous I/O
       operation previously submitted with io_submit(2).  The ctx_id argument is
       the AIO context ID of the operation to be canceled.  If the AIO context is
       found, the event will be canceled and then copied into the memory pointed
       to by result without being placed into the completion queue.

RETURN VALUE top

       On success, io_cancel() returns 0.  For the failure return, see NOTES.

ERRORS top

       EAGAIN The iocb specified was not canceled.

       EFAULT One of the data structures points to invalid data.

       EINVAL The AIO context specified by ctx_id is invalid.

       ENOSYS io_cancel() is not implemented on this architecture.

VERSIONS top

       The asynchronous I/O system calls first appeared in Linux 2.5.

CONFORMING TO top

       io_cancel() is Linux-specific and should not be used in programs that are
       intended to be portable.

NOTES top

       Glibc does not provide a wrapper function for this system call.  You could
       invoke it using syscall(2).  But instead, you probably want to use the
       io_cancel() wrapper function provided by libaio.

       Note that the libaio wrapper function uses a different type (io_context_t)
       for the ctx_id argument.  Note also that the libaio wrapper does not follow
       the usual C library conventions for indicating errors: on error it returns
       a negated error number (the negative of one of the values listed in
       ERRORS).  If the system call is invoked via syscall(2), then the return
       value follows the usual conventions for indicating an error: -1, with errno
       set to a (positive) value that indicates the error.

SEE ALSO top

       io_destroy(2), io_getevents(2), io_setup(2), io_submit(2), aio(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                        IO_CANCEL(2)


io_destroy(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IO_DESTROY(2)                Linux Programmer's Manual               IO_DESTROY(2)

NAME top

       io_destroy - destroy an asynchronous I/O context

SYNOPSIS top

       #include <linux/aio_abi.h>          /* Defines needed types */

       int io_destroy(aio_context_t ctx_id);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The io_destroy() system call removes the asynchronous I/O context specified
       by ctx_id from the list of I/O contexts and then destroys it.  It can also
       cancel any outstanding asynchronous I/O actions on ctx_id and block on
       completion.

RETURN VALUE top

       On success, io_destroy() returns 0.  For the failure return, see NOTES.

ERRORS top

       EFAULT The context pointed to is invalid.

       EINVAL The AIO context specified by ctx_id is invalid.

       ENOSYS io_destroy() is not implemented on this architecture.

VERSIONS top

       The asynchronous I/O system calls first appeared in Linux 2.5.

CONFORMING TO top

       io_destroy() is Linux-specific and should not be used in programs that are
       intended to be portable.

NOTES top

       Glibc does not provide a wrapper function for this system call.  You could
       invoke it using syscall(2).  But instead, you probably want to use the
       io_destroy() wrapper function provided by libaio.

       Note that the libaio wrapper function uses a different type (io_context_t)
       for the ctx_id argument.  Note also that the libaio wrapper does not follow
       the usual C library conventions for indicating errors: on error it returns
       a negated error number (the negative of one of the values listed in
       ERRORS).  If the system call is invoked via syscall(2), then the return
       value follows the usual conventions for indicating an error: -1, with errno
       set to a (positive) value that indicates the error.

SEE ALSO top

       io_cancel(2), io_getevents(2), io_setup(2), io_submit(2), aio(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                       IO_DESTROY(2)


io_getevents(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

IO_GETEVENTS(2)              Linux Programmer's Manual             IO_GETEVENTS(2)

NAME top

       io_getevents - read asynchronous I/O events from the completion queue

SYNOPSIS top

       #include <linux/aio_abi.h>         /* Defines needed types */
       #include <linux/time.h>            /* Defines 'struct timespec' */

       int io_getevents(aio_context_t ctx_id, long min_nr, long nr,
                        struct io_event *events, struct timespec *timeout);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The io_getevents() system call attempts to read at least min_nr events and
       up to nr events from the completion queue of the AIO context specified by
       ctx_id.  The timeout argument specifies the amount of time to wait for
       events, where a NULL timeout waits until at least min_nr events have been
       seen.  Note that timeout is relative and will be updated if not NULL and
       the operation blocks.

RETURN VALUE top

       On success, io_getevents() returns the number of events read: 0 if no
       events are available, or less than min_nr if the timeout has elapsed.  For
       the failure return, see NOTES.

ERRORS top

       EFAULT Either events or timeout is an invalid pointer.

       EINVAL ctx_id is invalid.  min_nr is out of range or nr is out of range.

       EINTR  Interrupted by a signal handler; see signal(7).

       ENOSYS io_getevents() is not implemented on this architecture.

VERSIONS top

       The asynchronous I/O system calls first appeared in Linux 2.5.

CONFORMING TO top

       io_getevents() is Linux-specific and should not be used in programs that
       are intended to be portable.

NOTES top

       Glibc does not provide a wrapper function for this system call.  You could
       invoke it using syscall(2).  But instead, you probably want to use the
       io_getevents() wrapper function provided by libaio.

       Note that the libaio wrapper function uses a different type (io_context_t)
       for the ctx_id argument.  Note also that the libaio wrapper does not follow
       the usual C library conventions for indicating errors: on error it returns
       a negated error number (the negative of one of the values listed in
       ERRORS).  If the system call is invoked via syscall(2), then the return
       value follows the usual conventions for indicating an error: -1, with errno
       set to a (positive) value that indicates the error.

BUGS top

       An invalid ctx_id may cause a segmentation fault instead of genenerating
       the error EINVAL.

SEE ALSO top

       io_cancel(2), io_destroy(2), io_setup(2), io_submit(2), aio(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-11-11                     IO_GETEVENTS(2)


io_setup(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IO_SETUP(2)                  Linux Programmer's Manual                 IO_SETUP(2)

NAME top

       io_setup - create an asynchronous I/O context

SYNOPSIS top

       #include <linux/aio_abi.h>          /* Defines needed types */

       int io_setup(unsigned nr_events, aio_context_t *ctx_idp);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The io_setup() system call creates an asynchronous I/O context capable of
       receiving at least nr_events.  The ctx_idp argument must not point to an
       AIO context that already exists, and must be initialized to 0 prior to the
       call.  On successful creation of the AIO context, *ctx_idp is filled in
       with the resulting handle.

RETURN VALUE top

       On success, io_setup() returns 0.  For the failure return, see NOTES.

ERRORS top

       EAGAIN The specified nr_events exceeds the user's limit of available
              events.

       EFAULT An invalid pointer is passed for ctx_idp.

       EINVAL ctx_idp is not initialized, or the specified nr_events exceeds
              internal limits.  nr_events should be greater than 0.

       ENOMEM Insufficient kernel resources are available.

       ENOSYS io_setup() is not implemented on this architecture.

VERSIONS top

       The asynchronous I/O system calls first appeared in Linux 2.5.

CONFORMING TO top

       io_setup() is Linux-specific and should not be used in programs that are
       intended to be portable.

NOTES top

       Glibc does not provide a wrapper function for this system call.  You could
       invoke it using syscall(2).  But instead, you probably want to use the
       io_setup() wrapper function provided by libaio.

       Note that the libaio wrapper function uses a different type
       (io_context_t *) for the ctx_idp argument.  Note also that the libaio
       wrapper does not follow the usual C library conventions for indicating
       errors: on error it returns a negated error number (the negative of one of
       the values listed in ERRORS).  If the system call is invoked via
       syscall(2), then the return value follows the usual conventions for
       indicating an error: -1, with errno set to a (positive) value that
       indicates the error.

SEE ALSO top

       io_cancel(2), io_destroy(2), io_getevents(2), io_submit(2), aio(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                         IO_SETUP(2)


io_submit(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IO_SUBMIT(2)                 Linux Programmer's Manual                IO_SUBMIT(2)

NAME top

       io_submit - submit asynchronous I/O blocks for processing

SYNOPSIS top

       #include <linux/aio_abi.h>          /* Defines needed types */

       int io_submit(aio_context_t ctx_id, long nr, struct iocb **iocbpp);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The io_submit() system call queues nr I/O request blocks for processing in
       the AIO context ctx_id.  The iocbpp argument should be an array of nr AIO
       control blocks, which will be submitted to context ctx_id.

RETURN VALUE top

       On success, io_submit() returns the number of iocbs submitted (which may be
       0 if nr is zero).  For the failure return, see NOTES.

ERRORS top

       EAGAIN Insufficient resources are available to queue any iocbs.

       EBADF  The file descriptor specified in the first iocb is invalid.

       EFAULT One of the data structures points to invalid data.

       EINVAL The AIO context specified by ctx_id is invalid.  nr is less than 0.
              The iocb at *iocbpp[0] is not properly initialized, or the operation
              specified is invalid for the file descriptor in the iocb.

       ENOSYS io_submit() is not implemented on this architecture.

VERSIONS top

       The asynchronous I/O system calls first appeared in Linux 2.5.

CONFORMING TO top

       io_submit() is Linux-specific and should not be used in programs that are
       intended to be portable.

NOTES top

       Glibc does not provide a wrapper function for this system call.  You could
       invoke it using syscall(2).  But instead, you probably want to use the
       io_submit() wrapper function provided by libaio.

       Note that the libaio wrapper function uses a different type (io_context_t)
       for the ctx_id argument.  Note also that the libaio wrapper does not follow
       the usual C library conventions for indicating errors: on error it returns
       a negated error number (the negative of one of the values listed in
       ERRORS).  If the system call is invoked via syscall(2), then the return
       value follows the usual conventions for indicating an error: -1, with errno
       set to a (positive) value that indicates the error.

SEE ALSO top

       io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2), aio(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                        IO_SUBMIT(2)


ip(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

IP(7)                        Linux Programmer's Manual                       IP(7)

NAME top

       ip - Linux IPv4 protocol implementation

SYNOPSIS top

       #include <sys/socket.h>
       #include <netinet/in.h>
       #include <netinet/ip.h> /* superset of previous */

       tcp_socket = socket(AF_INET, SOCK_STREAM, 0);
       udp_socket = socket(AF_INET, SOCK_DGRAM, 0);
       raw_socket = socket(AF_INET, SOCK_RAW, protocol);

DESCRIPTION top

       Linux implements the Internet Protocol, version 4, described in RFC 791 and
       RFC 1122.  ip contains a level 2 multicasting implementation conforming to
       RFC 1112.  It also contains an IP router including a packet filter.

       The programming interface is BSD-sockets compatible.  For more information
       on sockets, see socket(7).

       An IP socket is created by calling the socket(2) function as
       socket(AF_INET, socket_type, protocol).  Valid socket types are SOCK_STREAM
       to open a tcp(7) socket, SOCK_DGRAM to open a udp(7) socket, or SOCK_RAW to
       open a raw(7) socket to access the IP protocol directly.  protocol is the
       IP protocol in the IP header to be received or sent.  The only valid values
       for protocol are 0 and IPPROTO_TCP for TCP sockets, and 0 and IPPROTO_UDP
       for UDP sockets.  For SOCK_RAW you may specify a valid IANA IP protocol
       defined in RFC 1700 assigned numbers.

       When a process wants to receive new incoming packets or connections, it
       should bind a socket to a local interface address using bind(2).  Only one
       IP socket may be bound to any given local (address, port) pair.  When
       INADDR_ANY is specified in the bind call, the socket will be bound to all
       local interfaces.  When listen(2) or connect(2) are called on an unbound
       socket, it is automatically bound to a random free port with the local
       address set to INADDR_ANY.

       A TCP local socket address that has been bound is unavailable for some time
       after closing, unless the SO_REUSEADDR flag has been set.  Care should be
       taken when using this flag as it makes TCP less reliable.

Address Format

       An IP socket address is defined as a combination of an IP interface address
       and a 16-bit port number.  The basic IP protocol does not supply port
       numbers, they are implemented by higher level protocols like udp(7) and
       tcp(7).  On raw sockets sin_port is set to the IP protocol.

           struct sockaddr_in {
               sa_family_t    sin_family; /* address family: AF_INET */
               in_port_t      sin_port;   /* port in network byte order */
               struct in_addr sin_addr;   /* internet address */
           };

           /* Internet address. */
           struct in_addr {
               uint32_t       s_addr;     /* address in network byte order */
           };

       sin_family is always set to AF_INET.  This is required; in Linux 2.2 most
       networking functions return EINVAL when this setting is missing.  sin_port
       contains the port in network byte order.  The port numbers below 1024 are
       called privileged ports (or sometimes: reserved ports).  Only privileged
       processes (i.e., those having the CAP_NET_BIND_SERVICE capability) may
       bind(2) to these sockets.  Note that the raw IPv4 protocol as such has no
       concept of a port, they are only implemented by higher protocols like
       tcp(7) and udp(7).

       sin_addr is the IP host address.  The s_addr member of struct in_addr
       contains the host interface address in network byte order.  in_addr should
       be assigned one of the INADDR_* values (e.g., INADDR_ANY) or set using the
       inet_aton(3), inet_addr(3), inet_makeaddr(3) library functions or directly
       with the name resolver (see gethostbyname(3)).

       IPv4 addresses are divided into unicast, broadcast and multicast addresses.
       Unicast addresses specify a single interface of a host, broadcast addresses
       specify all hosts on a network and multicast addresses address all hosts in
       a multicast group.  Datagrams to broadcast addresses can be only sent or
       received when the SO_BROADCAST socket flag is set.  In the current
       implementation, connection-oriented sockets are only allowed to use unicast
       addresses.

       Note that the address and the port are always stored in network byte order.
       In particular, this means that you need to call htons(3) on the number that
       is assigned to a port.  All address/port manipulation functions in the
       standard library work in network byte order.

       There are several special addresses: INADDR_LOOPBACK (127.0.0.1) always
       refers to the local host via the loopback device; INADDR_ANY (0.0.0.0)
       means any address for binding; INADDR_BROADCAST (255.255.255.255) means any
       host and has the same effect on bind as INADDR_ANY for historical reasons.

Socket Options

       IP supports some protocol-specific socket options that can be set with
       setsockopt(2) and read with getsockopt(2).  The socket option level for IP
       is IPPROTO_IP.  A boolean integer flag is zero when it is false, otherwise
       true.

       IP_ADD_MEMBERSHIP (since Linux 1.2)
              Join a multicast group.  Argument is an ip_mreqn structure.

                  struct ip_mreqn {
                      struct in_addr imr_multiaddr; /* IP multicast group
                                                       address */
                      struct in_addr imr_address;   /* IP address of local
                                                       interface */
                      int            imr_ifindex;   /* interface index */
                  };

              imr_multiaddr contains the address of the multicast group the
              application wants to join or leave.  It must be a valid multicast
              address (or setsockopt(2) fails with the error EINVAL).  imr_address
              is the address of the local interface with which the system should
              join the multicast group; if it is equal to INADDR_ANY an
              appropriate interface is chosen by the system.  imr_ifindex is the
              interface index of the interface that should join/leave the
              imr_multiaddr group, or 0 to indicate any interface.

              The ip_mreqn structure is available only since Linux 2.2.  For
              compatibility, the old ip_mreq structure (present since Linux 1.2)
              is still supported; it differs from ip_mreqn only by not including
              the imr_ifindex field.  Only valid as a setsockopt(2).

       IP_DROP_MEMBERSHIP (since Linux 1.2)
              Leave a multicast group.  Argument is an ip_mreqn or ip_mreq
              structure similar to IP_ADD_MEMBERSHIP.

       IP_FREEBIND (since Linux 2.4)
              If enabled, this boolean option allows binding to an IP address that
              is nonlocal or does not (yet) exist.  This permits listening on a
              socket, without requiring the underlying network interface or the
              specified dynamic IP address to be up at the time that the
              application is trying to bind to it.  This option is the per-socket
              equivalent of the ip_nonlocal_bind /proc interface described below.

       IP_HDRINCL (since Linux 2.0)
              If enabled, the user supplies an IP header in front of the user
              data.  Only valid for SOCK_RAW sockets.  See raw(7) for more
              information.  When this flag is enabled the values set by
              IP_OPTIONS, IP_TTL and IP_TOS are ignored.

       IP_MTU (since Linux 2.2)
              Retrieve the current known path MTU of the current socket.  Only
              valid when the socket has been connected.  Returns an integer.  Only
              valid as a getsockopt(2).

       IP_MTU_DISCOVER (since Linux 2.2)
              Set or receive the Path MTU Discovery setting for a socket.  When
              enabled, Linux will perform Path MTU Discovery as defined in
              RFC 1191 on SOCK_STREAM sockets.  For non-SOCK_STREAM sockets,
              IP_PMTUDISC_DO forces the don't-fragment flag to be set on all
              outgoing packets.  It is the user's responsibility to packetize the
              data in MTU-sized chunks and to do the retransmits if necessary.
              The kernel will reject (with EMSGSIZE) datagrams that are bigger
              than the known path MTU.  IP_PMTUDISC_WANT will fragment a datagram
              if needed according to the path MTU, or will set the don't-fragment
              flag otherwise.

              The system-wide default can be toggled between IP_PMTUDISC_WANT and
              IP_PMTUDISC_DONT by writing (respectively, zero and nonzero values)
              to the /proc/sys/net/ipv4/ip_no_pmtu_disc file.

              Path MTU discovery value   Meaning
              IP_PMTUDISC_WANT           Use per-route settings.
              IP_PMTUDISC_DONT           Never do Path MTU Discovery.
              IP_PMTUDISC_DO             Always do Path MTU Discovery.
              IP_PMTUDISC_PROBE          Set DF but ignore Path MTU.

              When PMTU discovery is enabled, the kernel automatically keeps track
              of the path MTU per destination host.  When it is connected to a
              specific peer with connect(2), the currently known path MTU can be
              retrieved conveniently using the IP_MTU socket option (e.g., after
              an EMSGSIZE error occurred).  The path MTU may change over time.
              For connectionless sockets with many destinations, the new MTU for a
              given destination can also be accessed using the error queue (see
              IP_RECVERR).  A new error will be queued for every incoming MTU
              update.

              While MTU discovery is in progress, initial packets from datagram
              sockets may be dropped.  Applications using UDP should be aware of
              this and not take it into account for their packet retransmit
              strategy.

              To bootstrap the path MTU discovery process on unconnected sockets,
              it is possible to start with a big datagram size (up to 64K-headers
              bytes long) and let it shrink by updates of the path MTU.

              To get an initial estimate of the path MTU, connect a datagram
              socket to the destination address using connect(2) and retrieve the
              MTU by calling getsockopt(2) with the IP_MTU option.

              It is possible to implement RFC 4821 MTU probing with SOCK_DGRAM or
              SOCK_RAW sockets by setting a value of IP_PMTUDISC_PROBE (available
              since Linux 2.6.22).  This is also particularly useful for
              diagnostic tools such as tracepath(8) that wish to deliberately send
              probe packets larger than the observed Path MTU.

       IP_MULTICAST_IF (since Linux 1.2)
              Set the local device for a multicast socket.  Argument is an
              ip_mreqn or ip_mreq structure similar to IP_ADD_MEMBERSHIP.

              When an invalid socket option is passed, ENOPROTOOPT is returned.

       IP_MULTICAST_LOOP (since Linux 1.2)
              Set or read a boolean integer argument that determines whether sent
              multicast packets should be looped back to the local sockets.

       IP_MULTICAST_TTL (since Linux 1.2)
              Set or read the time-to-live value of outgoing multicast packets for
              this socket.  It is very important for multicast packets to set the
              smallest TTL possible.  The default is 1 which means that multicast
              packets don't leave the local network unless the user program
              explicitly requests it.  Argument is an integer.

       IP_NODEFRAG (since Linux 2.6.36)
              If enabled (argument is nonzero), the reassembly of outgoing packets
              is disabled in the netfilter layer.  This option is only valid for
              SOCK_RAW sockets.  The argument is an integer.

       IP_OPTIONS (since Linux 2.0)
              Set or get the IP options to be sent with every packet from this
              socket.  The arguments are a pointer to a memory buffer containing
              the options and the option length.  The setsockopt(2) call sets the
              IP options associated with a socket.  The maximum option size for
              IPv4 is 40 bytes.  See RFC 791 for the allowed options.  When the
              initial connection request packet for a SOCK_STREAM socket contains
              IP options, the IP options will be set automatically to the options
              from the initial packet with routing headers reversed.  Incoming
              packets are not allowed to change options after the connection is
              established.  The processing of all incoming source routing options
              is disabled by default and can be enabled by using the
              accept_source_route /proc interface.  Other options like timestamps
              are still handled.  For datagram sockets, IP options can be only set
              by the local user.  Calling getsockopt(2) with IP_OPTIONS puts the
              current IP options used for sending into the supplied buffer.

       IP_PKTINFO (since Linux 2.2)
              Pass an IP_PKTINFO ancillary message that contains a pktinfo
              structure that supplies some information about the incoming packet.
              This only works for datagram oriented sockets.  The argument is a
              flag that tells the socket whether the IP_PKTINFO message should be
              passed or not.  The message itself can only be sent/retrieved as
              control message with a packet using recvmsg(2) or sendmsg(2).

                  struct in_pktinfo {
                      unsigned int   ipi_ifindex;  /* Interface index */
                      struct in_addr ipi_spec_dst; /* Local address */
                      struct in_addr ipi_addr;     /* Header Destination
                                                      address */
                  };

              ipi_ifindex is the unique index of the interface the packet was
              received on.  ipi_spec_dst is the local address of the packet and
              ipi_addr is the destination address in the packet header.  If
              IP_PKTINFO is passed to sendmsg(2) and ipi_spec_dst is not zero,
              then it is used as the local source address for the routing table
              lookup and for setting up IP source route options.  When ipi_ifindex
              is not zero, the primary local address of the interface specified by
              the index overwrites ipi_spec_dst for the routing table lookup.

       IP_RECVERR (since Linux 2.2)
              Enable extended reliable error message passing.  When enabled on a
              datagram socket, all generated errors will be queued in a per-socket
              error queue.  When the user receives an error from a socket
              operation, the errors can be received by calling recvmsg(2) with the
              MSG_ERRQUEUE flag set.  The sock_extended_err structure describing
              the error will be passed in an ancillary message with the type
              IP_RECVERR and the level IPPROTO_IP.  This is useful for reliable
              error handling on unconnected sockets.  The received data portion of
              the error queue contains the error packet.

              The IP_RECVERR control message contains a sock_extended_err
              structure:

                  #define SO_EE_ORIGIN_NONE    0
                  #define SO_EE_ORIGIN_LOCAL   1
                  #define SO_EE_ORIGIN_ICMP    2
                  #define SO_EE_ORIGIN_ICMP6   3

                  struct sock_extended_err {
                      uint32_t ee_errno;   /* error number */
                      uint8_t  ee_origin;  /* where the error originated */
                      uint8_t  ee_type;    /* type */
                      uint8_t  ee_code;    /* code */
                      uint8_t  ee_pad;
                      uint32_t ee_info;    /* additional information */
                      uint32_t ee_data;    /* other data */
                      /* More data may follow */
                  };

                  struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);

              ee_errno contains the errno number of the queued error.  ee_origin
              is the origin code of where the error originated.  The other fields
              are protocol-specific.  The macro SO_EE_OFFENDER returns a pointer
              to the address of the network object where the error originated from
              given a pointer to the ancillary message.  If this address is not
              known, the sa_family member of the sockaddr contains AF_UNSPEC and
              the other fields of the sockaddr are undefined.

              IP uses the sock_extended_err structure as follows: ee_origin is set
              to SO_EE_ORIGIN_ICMP for errors received as an ICMP packet, or
              SO_EE_ORIGIN_LOCAL for locally generated errors.  Unknown values
              should be ignored.  ee_type and ee_code are set from the type and
              code fields of the ICMP header.  ee_info contains the discovered MTU
              for EMSGSIZE errors.  The message also contains the sockaddr_in of
              the node caused the error, which can be accessed with the
              SO_EE_OFFENDER macro.  The sin_family field of the SO_EE_OFFENDER
              address is AF_UNSPEC when the source was unknown.  When the error
              originated from the network, all IP options (IP_OPTIONS, IP_TTL,
              etc.) enabled on the socket and contained in the error packet are
              passed as control messages.  The payload of the packet causing the
              error is returned as normal payload.  Note that TCP has no error
              queue; MSG_ERRQUEUE is not permitted on SOCK_STREAM sockets.
              IP_RECVERR is valid for TCP, but all errors are returned by socket
              function return or SO_ERROR only.

              For raw sockets, IP_RECVERR enables passing of all received ICMP
              errors to the application, otherwise errors are only reported on
              connected sockets

              It sets or retrieves an integer boolean flag.  IP_RECVERR defaults
              to off.

       IP_RECVOPTS (since Linux 2.2)
              Pass all incoming IP options to the user in a IP_OPTIONS control
              message.  The routing header and other options are already filled in
              for the local host.  Not supported for SOCK_STREAM sockets.

       IP_RECVORIGDSTADDR (since Linux 2.6.29)
              This boolean option enables the IP_ORIGDSTADDR ancillary message in
              recvmsg(2), in which the kernel returns the original destination
              address of the datagram being received.  The ancillary message
              contains a struct sockaddr_in.

       IP_RECVTOS (since Linux 2.2)
              If enabled the IP_TOS ancillary message is passed with incoming
              packets.  It contains a byte which specifies the Type of
              Service/Precedence field of the packet header.  Expects a boolean
              integer flag.

       IP_RECVTTL (since Linux 2.2)
              When this flag is set, pass a IP_TTL control message with the time
              to live field of the received packet as a byte.  Not supported for
              SOCK_STREAM sockets.

       IP_RETOPTS (since Linux 2.2)
              Identical to IP_RECVOPTS, but returns raw unprocessed options with
              timestamp and route record options not filled in for this hop.

       IP_ROUTER_ALERT (since Linux 2.2)
              Pass all to-be forwarded packets with the IP Router Alert option set
              to this socket.  Only valid for raw sockets.  This is useful, for
              instance, for user-space RSVP daemons.  The tapped packets are not
              forwarded by the kernel; it is the user's responsibility to send
              them out again.  Socket binding is ignored, such packets are only
              filtered by protocol.  Expects an integer flag.

       IP_TOS (since Linux 1.0)
              Set or receive the Type-Of-Service (TOS) field that is sent with
              every IP packet originating from this socket.  It is used to
              prioritize packets on the network.  TOS is a byte.  There are some
              standard TOS flags defined: IPTOS_LOWDELAY to minimize delays for
              interactive traffic, IPTOS_THROUGHPUT to optimize throughput,
              IPTOS_RELIABILITY to optimize for reliability, IPTOS_MINCOST should
              be used for "filler data" where slow transmission doesn't matter.
              At most one of these TOS values can be specified.  Other bits are
              invalid and shall be cleared.  Linux sends IPTOS_LOWDELAY datagrams
              first by default, but the exact behavior depends on the configured
              queueing discipline.  Some high priority levels may require
              superuser privileges (the CAP_NET_ADMIN capability).  The priority
              can also be set in a protocol independent way by the (SOL_SOCKET,
              SO_PRIORITY) socket option (see socket(7)).

       IP_TRANSPARENT (since Linux 2.6.24)
              Setting this boolean option enables transparent proxying on this
              socket.  This socket option allows the calling application to bind
              to a nonlocal IP address and operate both as a client and a server
              with the foreign address as the local endpoint.  NOTE: this requires
              that routing be set up in a way that packets going to the foreign
              address are routed through the TProxy box.  Enabling this socket
              option requires superuser privileges (the CAP_NET_ADMIN capability).

              TProxy redirection with the iptables TPROXY target also requires
              that this option be set on the redirected socket.

       IP_TTL (since Linux 1.0)
              Set or retrieve the current time-to-live field that is used in every
              packet sent from this socket.

/proc interfaces

       The IP protocol supports a set of /proc interfaces to configure some global
       parameters.  The parameters can be accessed by reading or writing files in
       the directory /proc/sys/net/ipv4/.  Interfaces described as Boolean take an
       integer value, with a nonzero value ("true") meaning that the corresponding
       option is enabled, and a zero value ("false") meaning that the option is
       disabled.

       ip_always_defrag (Boolean; since Linux 2.2.13)
              [New with kernel 2.2.13; in earlier kernel versions this feature was
              controlled at compile time by the CONFIG_IP_ALWAYS_DEFRAG option;
              this option is not present in 2.4.x and later]

              When this boolean flag is enabled (not equal 0), incoming fragments
              (parts of IP packets that arose when some host between origin and
              destination decided that the packets were too large and cut them
              into pieces) will be reassembled (defragmented) before being
              processed, even if they are about to be forwarded.

              Only enable if running either a firewall that is the sole link to
              your network or a transparent proxy; never ever use it for a normal
              router or host.  Otherwise fragmented communication can be disturbed
              if the fragments travel over different links.  Defragmentation also
              has a large memory and CPU time cost.

              This is automagically turned on when masquerading or transparent
              proxying are configured.

       ip_autoconfig (since Linux 2.2 to 2.6.17)
              Not documented.

       ip_default_ttl (integer; default: 64; since Linux 2.2)
              Set the default time-to-live value of outgoing packets.  This can be
              changed per socket with the IP_TTL option.

       ip_dynaddr (Boolean; default: disabled; since Linux 2.0.31)
              Enable dynamic socket address and masquerading entry rewriting on
              interface address change.  This is useful for dialup interface with
              changing IP addresses.  0 means no rewriting, 1 turns it on and 2
              enables verbose mode.

       ip_forward (Boolean; default: disabled; since Linux 1.2)
              Enable IP forwarding with a boolean flag.  IP forwarding can be also
              set on a per-interface basis.

       ip_local_port_range (since Linux 2.2)
              Contains two integers that define the default local port range
              allocated to sockets.  Allocation starts with the first number and
              ends with the second number.  Note that these should not conflict
              with the ports used by masquerading (although the case is handled).
              Also arbitrary choices may cause problems with some firewall packet
              filters that make assumptions about the local ports in use.  First
              number should be at least greater than 1024, or better, greater than
              4096, to avoid clashes with well known ports and to minimize
              firewall problems.

       ip_no_pmtu_disc (Boolean; default: disabled; since Linux 2.2)
              If enabled, don't do Path MTU Discovery for TCP sockets by default.
              Path MTU discovery may fail if misconfigured firewalls (that drop
              all ICMP packets) or misconfigured interfaces (e.g., a point-to-
              point link where the both ends don't agree on the MTU) are on the
              path.  It is better to fix the broken routers on the path than to
              turn off Path MTU Discovery globally, because not doing it incurs a
              high cost to the network.

       ip_nonlocal_bind (Boolean; default: disabled; since Linux 2.4)
              If set, allows processes to bind(2) to nonlocal IP addresses, which
              can be quite useful, but may break some applications.

       ip6frag_time (integer; default: 30)
              Time in seconds to keep an IPv6 fragment in memory.

       ip6frag_secret_interval (integer; default: 600)
              Regeneration interval (in seconds) of the hash secret (or lifetime
              for the hash secret) for IPv6 fragments.

       ipfrag_high_thresh (integer), ipfrag_low_thresh (integer)
              If the amount of queued IP fragments reaches ipfrag_high_thresh, the
              queue is pruned down to ipfrag_low_thresh.  Contains an integer with
              the number of bytes.

       neigh/*
              See arp(7).

Ioctls

       All ioctls described in socket(7) apply to ip.

       Ioctls to configure generic device parameters are described in
       netdevice(7).

ERRORS top

       EACCES The user tried to execute an operation without the necessary
              permissions.  These include: sending a packet to a broadcast address
              without having the SO_BROADCAST flag set; sending a packet via a
              prohibit route; modifying firewall settings without superuser
              privileges (the CAP_NET_ADMIN capability); binding to a privileged
              port without superuser privileges (the CAP_NET_BIND_SERVICE
              capability).

       EADDRINUSE
              Tried to bind to an address already in use.

       EADDRNOTAVAIL
              A nonexistent interface was requested or the requested source
              address was not local.

       EAGAIN Operation on a nonblocking socket would block.

       EALREADY
              An connection operation on a nonblocking socket is already in
              progress.

       ECONNABORTED
              A connection was closed during an accept(2).

       EHOSTUNREACH
              No valid routing table entry matches the destination address.  This
              error can be caused by a ICMP message from a remote router or for
              the local routing table.

       EINVAL Invalid argument passed.  For send operations this can be caused by
              sending to a blackhole route.

       EISCONN
              connect(2) was called on an already connected socket.

       EMSGSIZE
              Datagram is bigger than an MTU on the path and it cannot be
              fragmented.

       ENOBUFS, ENOMEM
              Not enough free memory.  This often means that the memory allocation
              is limited by the socket buffer limits, not by the system memory,
              but this is not 100% consistent.

       ENOENT SIOCGSTAMP was called on a socket where no packet arrived.

       ENOPKG A kernel subsystem was not configured.

       ENOPROTOOPT and EOPNOTSUPP
              Invalid socket option passed.

       ENOTCONN
              The operation is only defined on a connected socket, but the socket
              wasn't connected.

       EPERM  User doesn't have permission to set high priority, change
              configuration, or send signals to the requested process or group.

       EPIPE  The connection was unexpectedly closed or shut down by the other
              end.

       ESOCKTNOSUPPORT
              The socket is not configured or an unknown socket type was
              requested.

       Other errors may be generated by the overlaying protocols; see tcp(7),
       raw(7), udp(7) and socket(7).

NOTES top

       IP_FREEBIND, IP_MTU, IP_MTU_DISCOVER, IP_RECVORIGDSTADDR, IP_PKTINFO,
       IP_RECVERR, IP_ROUTER_ALERT, and IP_TRANSPARENT are Linux-specific.

       Be very careful with the SO_BROADCAST option - it is not privileged in
       Linux.  It is easy to overload the network with careless broadcasts.  For
       new application protocols it is better to use a multicast group instead of
       broadcasting.  Broadcasting is discouraged.

       Some other BSD sockets implementations provide IP_RCVDSTADDR and IP_RECVIF
       socket options to get the destination address and the interface of received
       datagrams.  Linux has the more general IP_PKTINFO for the same task.

       Some BSD sockets implementations also provide an IP_RECVTTL option, but an
       ancillary message with type IP_RECVTTL is passed with the incoming packet.
       This is different from the IP_TTL option used in Linux.

       Using SOL_IP socket options level isn't portable, BSD-based stacks use
       IPPROTO_IP level.

Compatibility

       For compatibility with Linux 2.0, the obsolete socket(AF_INET, SOCK_PACKET,
       protocol) syntax is still supported to open a packet(7) socket.  This is
       deprecated and should be replaced by socket(AF_PACKET, SOCK_RAW, protocol)
       instead.  The main difference is the new sockaddr_ll address structure for
       generic link layer information instead of the old sockaddr_pkt.

BUGS top

       There are too many inconsistent error values.

       The ioctls to configure IP-specific interface options and ARP tables are
       not described.

       Some versions of glibc forget to declare in_pktinfo.  Workaround currently
       is to copy it into your program from this man page.

       Receiving the original destination address with MSG_ERRQUEUE in msg_name by
       recvmsg(2) does not work in some 2.2 kernels.

SEE ALSO top

       recvmsg(2), sendmsg(2), byteorder(3), ipfw(4), capabilities(7), icmp(7),
       ipv6(7), netlink(7), raw(7), socket(7), tcp(7), udp(7)

       RFC 791 for the original IP specification.  RFC 1122 for the IPv4 host
       requirements.  RFC 1812 for the IPv4 router requirements.

COLOPHON top

       This page is part of release 3.45 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                               2011-09-22                               IP(7)


ipc(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

IPC(2)                       Linux Programmer's Manual                      IPC(2)

NAME top

       ipc - System V IPC system calls

SYNOPSIS top

       int ipc(unsigned int call, int first, int second, int third,
               void *ptr, long fifth);

DESCRIPTION top

       ipc() is a common kernel entry point for the System V IPC calls for
       messages, semaphores, and shared memory.  call determines which IPC
       function to invoke; the other arguments are passed through to the
       appropriate call.

       User programs should call the appropriate functions by their usual names.
       Only standard library implementors and kernel hackers need to know about
       ipc().

CONFORMING TO top

       ipc() is Linux-specific, and should not be used in programs intended to be
       portable.

NOTES top

       On some architectures--for example x86-64 and ARM--there is no ipc() system
       call; instead msgctl(2), semctl(2), shmctl(2), and so on really are
       implemented as separate system calls.

SEE ALSO top

       msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2),
       semtimedop(2), shmat(2), shmctl(2), shmdt(2), shmget(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-16                              IPC(2)


svipc(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

SVIPC(7)                     Linux Programmer's Manual                    SVIPC(7)

NAME top

       svipc - System V interprocess communication mechanisms

SYNOPSIS top

       #include <sys/msg.h>
       #include <sys/sem.h>
       #include <sys/shm.h>

DESCRIPTION top

       This manual page refers to the Linux implementation of the System V
       interprocess communication (IPC) mechanisms: message queues, semaphore
       sets, and shared memory segments.  In the following, the word resource
       means an instantiation of one among such mechanisms.

Resource Access Permissions

       For each resource, the system uses a common structure of type struct
       ipc_perm to store information needed in determining permissions to perform
       an IPC operation.  The ipc_perm structure includes the following members:

           struct ipc_perm {
               uid_t          cuid;   /* creator user ID */
               gid_t          cgid;   /* creator group ID */
               uid_t          uid;    /* owner user ID */
               gid_t          gid;    /* owner group ID */
               unsigned short mode;   /* r/w permissions */
           };

       The mode member of the ipc_perm structure defines, with its lower 9 bits,
       the access permissions to the resource for a process executing an IPC
       system call.  The permissions are interpreted as follows:

           0400    Read by user.
           0200    Write by user.
           0040    Read by group.
           0020    Write by group.
           0004    Read by others.
           0002    Write by others.

       Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
       Furthermore, "write" effectively means "alter" for a semaphore set.

       The same system header file also defines the following symbolic constants:

       IPC_CREAT     Create entry if key doesn't exist.

       IPC_EXCL      Fail if key exists.

       IPC_NOWAIT    Error if request must wait.

       IPC_PRIVATE   Private key.

       IPC_RMID      Remove resource.

       IPC_SET       Set resource options.

       IPC_STAT      Get resource options.

       Note that IPC_PRIVATE is a key_t type, while all the other symbolic
       constants are flag fields and can be OR'ed into an int type variable.

Message Queues

       A message queue is uniquely identified by a positive integer (its msqid)
       and has an associated data structure of type struct msqid_ds, defined in
       <sys/msg.h>, containing the following members:

           struct msqid_ds {
               struct ipc_perm msg_perm;
               msgqnum_t       msg_qnum;    /* no of messages on queue */
               msglen_t        msg_qbytes;  /* bytes max on a queue */
               pid_t           msg_lspid;   /* PID of last msgsnd(2) call */
               pid_t           msg_lrpid;   /* PID of last msgrcv(2) call */
               time_t          msg_stime;   /* last msgsnd(2) time */
               time_t          msg_rtime;   /* last msgrcv(2) time */
               time_t          msg_ctime;   /* last change time */
           };

       msg_perm   ipc_perm structure that specifies the access permissions on the
                  message queue.

       msg_qnum   Number of messages currently on the message queue.

       msg_qbytes Maximum number of bytes of message text allowed on the message
                  queue.

       msg_lspid  ID of the process that performed the last msgsnd(2) system call.

       msg_lrpid  ID of the process that performed the last msgrcv(2) system call.

       msg_stime  Time of the last msgsnd(2) system call.

       msg_rtime  Time of the last msgrcv(2) system call.

       msg_ctime  Time of the last system call that changed a member of the
                  msqid_ds structure.

Semaphore Sets

       A semaphore set is uniquely identified by a positive integer (its semid)
       and has an associated data structure of type struct semid_ds, defined in
       <sys/sem.h>, containing the following members:

           struct semid_ds {
               struct ipc_perm sem_perm;
               time_t          sem_otime;   /* last operation time */
               time_t          sem_ctime;   /* last change time */
               unsigned long   sem_nsems;   /* count of sems in set */
           };

       sem_perm   ipc_perm structure that specifies the access permissions on the
                  semaphore set.

       sem_otime  Time of last semop(2) system call.

       sem_ctime  Time of last semctl(2) system call that changed a member of the
                  above structure or of one semaphore belonging to the set.

       sem_nsems  Number of semaphores in the set.  Each semaphore of the set is
                  referenced by a nonnegative integer ranging from 0 to
                  sem_nsems-1.

       A semaphore is a data structure of type struct sem containing the following
       members:

           struct sem {
               int semval;  /* semaphore value */
               int sempid;  /* PID for last operation */
           };

       semval     Semaphore value: a nonnegative integer.

       sempid     ID of the last process that performed a semaphore operation on
                  this semaphore.

Shared Memory Segments

       A shared memory segment is uniquely identified by a positive integer (its
       shmid) and has an associated data structure of type struct shmid_ds,
       defined in <sys/shm.h>, containing the following members:

           struct shmid_ds {
               struct ipc_perm shm_perm;
               size_t          shm_segsz;   /* size of segment */
               pid_t           shm_cpid;    /* PID of creator */
               pid_t           shm_lpid;    /* PID, last operation */
               shmatt_t        shm_nattch;  /* no. of current attaches */
               time_t          shm_atime;   /* time of last attach */
               time_t          shm_dtime;   /* time of last detach */
               time_t          shm_ctime;   /* time of last change */
           };

       shm_perm   ipc_perm structure that specifies the access permissions on the
                  shared memory segment.

       shm_segsz  Size in bytes of the shared memory segment.

       shm_cpid   ID of the process that created the shared memory segment.

       shm_lpid   ID of the last process that executed a shmat(2) or shmdt(2)
                  system call.

       shm_nattch Number of current alive attaches for this shared memory segment.

       shm_atime  Time of the last shmat(2) system call.

       shm_dtime  Time of the last shmdt(2) system call.

       shm_ctime  Time of the last shmctl(2) system call that changed shmid_ds.

SEE ALSO top

       ipc(2), msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2),
       semop(2), shmat(2), shmctl(2), shmdt(2), shmget(2), ftok(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                            SVIPC(7)


ipv6(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

IPV6(7)                      Linux Programmer's Manual                     IPV6(7)

structure.

NAME top

       ipv6 - Linux IPv6 protocol implementation

SYNOPSIS top

       #include <sys/socket.h>
       #include <netinet/in.h>

       tcp6_socket = socket(AF_INET6, SOCK_STREAM, 0);
       raw6_socket = socket(AF_INET6, SOCK_RAW, protocol);
       udp6_socket = socket(AF_INET6, SOCK_DGRAM, protocol);

DESCRIPTION top

       Linux 2.2 optionally implements the Internet Protocol, version 6.  This man
       page contains a description of the IPv6 basic API as implemented by the
       Linux kernel and glibc 2.1.  The interface is based on the BSD sockets
       interface; see socket(7).

       The IPv6 API aims to be mostly compatible with the IPv4 API (see ip(7)).
       Only differences are described in this man page.

       To bind an AF_INET6 socket to any process, the local address should be
       copied from the in6addr_any variable which has in6_addr type.  In static
       initializations, IN6ADDR_ANY_INIT may also be used, which expands to a
       constant expression.  Both of them are in network byte order.

       The IPv6 loopback address (::1) is available in the global in6addr_loopback
       variable.  For initializations, IN6ADDR_LOOPBACK_INIT should be used.

       IPv4 connections can be handled with the v6 API by using the v4-mapped-on-
       v6 address type; thus a program only needs to support this API type to
       support both protocols.  This is handled transparently by the address
       handling functions in the C library.

       IPv4 and IPv6 share the local port space.  When you get an IPv4 connection
       or packet to a IPv6 socket, its source address will be mapped to v6 and it
       will be mapped to v6.

Address Format

           struct sockaddr_in6 {
               sa_family_t     sin6_family;   /* AF_INET6 */
               in_port_t       sin6_port;     /* port number */
               uint32_t        sin6_flowinfo; /* IPv6 flow information */
               struct in6_addr sin6_addr;     /* IPv6 address */
               uint32_t        sin6_scope_id; /* Scope ID (new in 2.4) */
           };

           struct in6_addr {
               unsigned char   s6_addr[16];   /* IPv6 address */
           };

       sin6_family is always set to AF_INET6; sin6_port is the protocol port (see
       sin_port in ip(7)); sin6_flowinfo is the IPv6 flow identifier; sin6_addr is
       the 128-bit IPv6 address.  sin6_scope_id is an ID depending on the scope of
       the address.  It is new in Linux 2.4.  Linux only supports it for link-
       local addresses, in that case sin6_scope_id contains the interface index
       (see netdevice(7))

       IPv6 supports several address types: unicast to address a single host,
       multicast to address a group of hosts, anycast to address the nearest
       member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to
       address a IPv4 host, and other reserved address types.

       The address notation for IPv6 is a group of 8 4-digit hexadecimal numbers,
       separated with a ':'.  "::" stands for a string of 0 bits.  Special
       addresses are ::1 for loopback and ::FFFF:<IPv4 address> for IPv4-mapped-
       on-IPv6.

       The port space of IPv6 is shared with IPv4.

Socket Options

       IPv6 supports some protocol-specific socket options that can be set with
       setsockopt(2) and read with getsockopt(2).  The socket option level for
       IPv6 is IPPROTO_IPV6.  A boolean integer flag is zero when it is false,
       otherwise true.

       IPV6_ADDRFORM
              Turn an AF_INET6 socket into a socket of a different address family.
              Only AF_INET is currently supported for that.  It is only allowed
              for IPv6 sockets that are connected and bound to a v4-mapped-on-v6
              address.  The argument is a pointer to an integer containing
              AF_INET.  This is useful to pass v4-mapped sockets as file
              descriptors to programs that don't know how to deal with the IPv6
              API.

       IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP
              Control membership in multicast groups.  Argument is a pointer to a
              struct ipv6_mreq

       IPV6_MTU
              getsockopt(): Retrieve the current known path MTU of the current
              socket.  Only valid when the socket has been connected.  Returns an
              integer.

              setsockopt(): Set the MTU to be used for the socket.  The MTU is
              limited by the device MTU or the path MTU when path MTU discovery is
              enabled.  Argument is a pointer to integer.

       IPV6_MTU_DISCOVER
              Control path-MTU discovery on the socket.  See IP_MTU_DISCOVER in
              ip(7) for details.

       IPV6_MULTICAST_HOPS
              Set the multicast hop limit for the socket.  Argument is a pointer
              to an integer.  -1 in the value means use the route default,
              otherwise it should be between 0 and 255.

       IPV6_MULTICAST_IF
              Set the device for outgoing multicast packets on the socket.  This
              is only allowed for SOCK_DGRAM and SOCK_RAW socket.  The argument is
              a pointer to an interface index (see netdevice(7)) in an integer.

       IPV6_MULTICAST_LOOP
              Control whether the socket sees multicast packets that it has send
              itself.  Argument is a pointer to boolean.

       IPV6_RECVPKTINFO (since Linux 2.6.14)
              Set delivery of the IPV6_PKTINFO control message on incoming
              datagrams.  Such control messages contain a struct in6_pktinfo, as
              per RFC 3542.  Only allowed for SOCK_DGRAM or SOCK_RAW sockets.
              Argument is a pointer to a boolean value in an integer.

       IPV6_RTHDR, IPV6_AUTHHDR, IPV6_DSTOPTS, IPV6_HOPOPTS, IPV6_FLOWINFO,
       IPV6_HOPLIMIT
              Set delivery of control messages for incoming datagrams containing
              extension headers from the received packet.  IPV6_RTHDR delivers the
              routing header, IPV6_AUTHHDR delivers the authentication header,
              IPV6_DSTOPTS delivers the destination options, IPV6_HOPOPTS delivers
              the hop options, IPV6_FLOWINFO delivers an integer containing the
              flow ID, IPV6_HOPLIMIT delivers an integer containing the hop count
              of the packet.  The control messages have the same type as the sock-
              et option.  All these header options can also be set for outgoing
              packets by putting the appropriate control message into the control
              buffer of sendmsg(2).  Only allowed for SOCK_DGRAM or SOCK_RAW sock-
              ets.  Argument is a pointer to a boolean value.

       IPV6_RECVERR
              Control receiving of asynchronous error options.  See IP_RECVERR in
              ip(7) for details.  Argument is a pointer to boolean.

       IPV6_ROUTER_ALERT
              Pass forwarded packets containing a router alert hop-by-hop option
              to this socket.  Only allowed for SOCK_RAW sockets.  The tapped
              packets are not forwarded by the kernel, it is the user's responsi-
              bility to send them out again.  Argument is a pointer to an integer.
              A positive integer indicates a router alert option value to inter-
              cept.  Packets carrying a router alert option with a value field
              containing this integer will be delivered to the socket.  A negative
              integer disables delivery of packets with router alert options to
              this socket.

       IPV6_UNICAST_HOPS
              Set the unicast hop limit for the socket.  Argument is a pointer to
              an integer.  -1 in the value means use the route default, otherwise
              it should be between 0 and 255.

       IPV6_V6ONLY (since Linux 2.4.21 and 2.6)
              If this flag is set to true (nonzero), then the socket is restricted
              to sending and receiving IPv6 packets only.  In this case, an IPv4
              and an IPv6 application can bind to a single port at the same time.

              If this flag is set to false (zero), then the socket can be used to
              send and receive packets to and from an IPv6 address or an
              IPv4-mapped IPv6 address.

              The argument is a pointer to a boolean value in an integer.

              The default value for this flag is defined by the contents of the
              file /proc/sys/net/ipv6/bindv6only.  The default value for that file
              is 0 (false).

ERRORS top

       ENODEV The user tried to bind(2) to a link-local IPv6 address, but the
              sin6_scope_id in the supplied sockaddr_in6 structure is not a valid
              interface index.

VERSIONS top

       The older libinet6 libc5 based IPv6 API implementation for Linux is not de-
       scribed here and may vary in details.

       Linux 2.4 will break binary compatibility for the sockaddr_in6 for 64-bit
       hosts by changing the alignment of in6_addr and adding an additional
       sin6_scope_id field.  The kernel interfaces stay compatible, but a program
       including sockaddr_in6 or in6_addr into other structures may not be.  This
       is not a problem for 32-bit hosts like i386.

       The sin6_flowinfo field is new in Linux 2.4.  It is transparently
       passed/read by the kernel when the passed address length contains it.  Some
       programs that pass a longer address buffer and then check the outgoing ad-
       dress length may break.

NOTES top

       The sockaddr_in6 structure is bigger than the generic sockaddr.  Programs
       that assume that all address types can be stored safely in a struct sockad-
       dr need to be changed to use struct sockaddr_storage for that instead.

BUGS top

       The IPv6 extended API as in RFC 2292 is currently only partly implemented;
       although the 2.2 kernel has near complete support for receiving options,
       the macros for generating IPv6 options are missing in glibc 2.1.

       IPSec support for EH and AH headers is missing.

       Flow label management is not complete and not documented here.

       This man page is not complete.

SEE ALSO top

       cmsg(3), ip(7)

       RFC 2553: IPv6 BASIC API; Linux tries to be compliant to this.  RFC 2460:
       IPv6 specification.

COLOPHON top

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

Linux                               2012-12-16                             IPV6(7)


rcmd(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RCMD(3)                      Linux Programmer's Manual                     RCMD(3)

NAME top

       rcmd,  rresvport,  iruserok,  ruserok,  rcmd_af, rresvport_af, iruserok_af,
       ruserok_af - routines for returning a stream to a remote command

SYNOPSIS top

       #include <netdb.h>   /* Or <unistd.h> on some systems */

       int rcmd(char **ahost, int inport, const char *locuser,
                const char *remuser, const char *cmd, int *fd2p);

       int rresvport(int *port);

       int iruserok(uint32_t raddr, int superuser,
                    const char *ruser, const char *luser);

       int ruserok(const char *rhost, int superuser,
                   const char *ruser, const char *luser);

       int rcmd_af(char **ahost, int inport, const char *locuser,
                   const char *remuser, const char *cmd, int *fd2p,
                   sa_family_t af);

       int rresvport_af(int *port, sa_family_t af);

       int iruserok_af(uint32_t raddr, int superuser,
                       const char *ruser, const char *luser, sa_family_t af);

       int ruserok_af(const char *rhost, int superuser,
                      const char *ruser, const char *luser, sa_family_t af);

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

       rcmd(), rcmd_af(), rresvport(), rresvport_af(), iruserok(),  iruserok_af(),
       ruserok(), ruserok_af(): _BSD_SOURCE

DESCRIPTION top

       The rcmd() function is used by the superuser to execute a command on a
       remote machine using an authentication scheme based on privileged port
       numbers.  The rresvport() function returns a descriptor to a socket with an
       address in the privileged port space.  The iruserok() and ruserok()
       functions are used by servers to authenticate clients requesting service
       with rcmd().  All four functions are used by the rshd(8) server (among
       others).

rcmd()

       The rcmd() function looks up the host *ahost using gethostbyname(3),
       returning -1 if the host does not exist.  Otherwise *ahost is set to the
       standard name of the host and a connection is established to a server
       residing at the well-known Internet port inport.

       If the connection succeeds, a socket in the Internet domain of type
       SOCK_STREAM is returned to the caller, and given to the remote command as
       stdin and stdout.  If fd2p is nonzero, then an auxiliary channel to a
       control process will be set up, and a descriptor for it will be placed in
       *fd2p.  The control process will return diagnostic output from the command
       (unit 2) on this channel, and will also accept bytes on this channel as
       being UNIX signal numbers, to be forwarded to the process group of the
       command.  If fd2p is 0, then the stderr (unit 2 of the remote command) will
       be made the same as the stdout and no provision is made for sending
       arbitrary signals to the remote process, although you may be able to get
       its attention by using out-of-band data.

       The protocol is described in detail in rshd(8).

rresvport()

       The rresvport() function is used to obtain a socket with a privileged port
       bound to it.  This socket is suitable for use by rcmd() and several other
       functions.  Privileged ports are those in the range 0 to 1023.  Only a
       privileged process (CAP_NET_BIND_SERVICE) is allowed to bind to a
       privileged port.  In the glibc implementation, this function restricts its
       search to the ports from 512 to 1023.  The port argument is value-result:
       the value it supplies to the call is used as the starting point for a
       circular search of the port range; on (successful) return, it contains the
       port number that was bound to.

iruserok() and ruserok()

       The iruserok() and ruserok() functions take a remote host's IP address or
       name, respectively, two usernames and a flag indicating whether the local
       user's name is that of the superuser.  Then, if the user is not the
       superuser, it checks the /etc/hosts.equiv file.  If that lookup is not
       done, or is unsuccessful, the .rhosts in the local user's home directory is
       checked to see if the request for service is allowed.

       If this file does not exist, is not a regular file, is owned by anyone
       other than the user or the superuser, or is writable by anyone other than
       the owner, the check automatically fails.  Zero is returned if the machine
       name is listed in the hosts.equiv file, or the host and remote username are
       found in the .rhosts file; otherwise iruserok() and ruserok() return -1.
       If the local domain (as obtained from gethostname(2)) is the same as the
       remote domain, only the machine name need be specified.

       If the IP address of the remote host is known, iruserok() should be used in
       preference to ruserok(), as it does not require trusting the DNS server for
       the remote host's domain.

*_af() variants

       All of the functions described above work with IPv4 (AF_INET) sockets.  The
       "_af" variants take an extra argument that allows the socket address family
       to be specified.  For these functions, the af argument can be specified as
       AF_INET or AF_INET6.  In addition, rcmd_af() supports the use of AF_UNSPEC.

RETURN VALUE top

       The rcmd() function returns a valid socket descriptor on success.  It
       returns -1 on error and prints a diagnostic message on the standard error.

       The rresvport() function returns a valid, bound socket descriptor on
       success.  It returns -1 on error with the global value errno set according
       to the reason for failure.  The error code EAGAIN is overloaded to mean
       "All network ports in use."

       For information on the return from ruserok() and iruserok(), see above.

VERSIONS top

       The functions iruserok_af(), rcmd_af(), rresvport_af(), and ruserok_af()
       functions are provide in glibc since version 2.2.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs, Solaris, and many other systems.
       These functions appeared in 4.2BSD.  The "_af" variants are more recent
       additions, and are not present on as wide a range of systems.

BUGS top

       iruserok() and iruserok_af() are declared in glibc headers only since
       version 2.12.

SEE ALSO top

       rlogin(1), rsh(1), intro(2), rexec(3), rexecd(8), rlogind(8), rshd(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-23                             RCMD(3)


isalpha(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISALPHA(3)                   Linux Programmer's Manual                  ISALPHA(3)

NAME top

       isalnum,  isalpha,  isascii,  isblank,  iscntrl, isdigit, isgraph, islower,
       isprint, ispunct, isspace, isupper,  isxdigit  -  character  classification
       routines

SYNOPSIS top

       #include <ctype.h>

       int isalnum(int c);
       int isalpha(int c);
       int isascii(int c);
       int isblank(int c);
       int iscntrl(int c);
       int isdigit(int c);
       int isgraph(int c);
       int islower(int c);
       int isprint(int c);
       int ispunct(int c);
       int isspace(int c);
       int isupper(int c);
       int isxdigit(int c);

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

       isascii():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE
       isblank():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions check whether c, which must have the value of an unsigned
       char or EOF, falls into a certain character class according to the current
       locale.

       isalnum()
              checks for an alphanumeric character; it is equivalent to
              (isalpha(c) || isdigit(c)).

       isalpha()
              checks for an alphabetic character; in the standard "C" locale, it
              is equivalent to (isupper(c) || islower(c)).  In some locales, there
              may be additional characters for which isalpha() is true--letters
              which are neither upper case nor lower case.

       isascii()
              checks whether c is a 7-bit unsigned char value that fits into the
              ASCII character set.

       isblank()
              checks for a blank character; that is, a space or a tab.

       iscntrl()
              checks for a control character.

       isdigit()
              checks for a digit (0 through 9).

       isgraph()
              checks for any printable character except space.

       islower()
              checks for a lower-case character.

       isprint()
              checks for any printable character including space.

       ispunct()
              checks for any printable character which is not a space or an
              alphanumeric character.

       isspace()
              checks for white-space characters.  In the "C" and "POSIX" locales,
              these are: space, form-feed ('\f'), newline ('\n'), carriage return
              ('\r'), horizontal tab ('\t'), and vertical tab ('\v').

       isupper()
              checks for an uppercase letter.

       isxdigit()
              checks for a hexadecimal digits, that is, one of
              0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F.

RETURN VALUE top

       The values returned are nonzero if the character c falls into the tested
       class, and a zero value if not.

CONFORMING TO top

       C99, 4.3BSD.  C89 specifies all of these functions except isascii() and
       isblank().  isascii() is a BSD extension and is also an SVr4 extension.
       isblank() conforms to POSIX.1-2001 and C99 7.4.1.3.  POSIX.1-2008 marks
       isascii() as obsolete, noting that it cannot be used portably in a
       localized application.

NOTES top

       The details of what characters belong into which class depend on the
       current locale.  For example, isupper() will not recognize an A-umlaut ("A)
       as an uppercase letter in the default C locale.

SEE ALSO top

       iswalnum(3), iswalpha(3), iswblank(3), iswcntrl(3), iswdigit(3),
       iswgraph(3), iswlower(3), iswprint(3), iswpunct(3), iswspace(3),
       iswupper(3), iswxdigit(3), setlocale(3), toascii(3), tolower(3),
       toupper(3), ascii(7), locale(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                          ISALPHA(3)


isatty(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ISATTY(3)                    Linux Programmer's Manual                   ISATTY(3)

NAME top

       isatty - test whether a file descriptor refers to a terminal

SYNOPSIS top

       #include <unistd.h>

       int isatty(int fd);

DESCRIPTION top

       The isatty() function tests whether fd is an open file descriptor referring
       to a terminal.

RETURN VALUE top

       isatty() returns 1 if fd is an open file descriptor referring to a
       terminal; otherwise 0 is returned, and errno is set to indicate the error.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       EINVAL fd refers to a file other than a terminal.  POSIX.1-2001 specifies
              the error ENOTTY for this case.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

SEE ALSO top

       fstat(2), ttyname(3)

COLOPHON top

       This page is part of release 3.45 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-03                           ISATTY(3)


isgreater(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISGREATER(3)                 Linux Programmer's Manual                ISGREATER(3)

NAME top

       isgreater,  isgreaterequal, isless, islessequal, islessgreater, isunordered
       - floating-point relational tests without exception for NaN

SYNOPSIS top

       #include <math.h>

       int isgreater(x, y);

       int isgreaterequal(x, y);

       int isless(x, y);

       int islessequal(x, y);

       int islessgreater(x, y);

       int isunordered(x, y);

       Link with -lm.

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

       All functions described here:
              _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
              _POSIX_C_SOURCE >= 200112L;
              or cc -std=c99

DESCRIPTION top

       The normal relation operations (like <, "less than") will fail if one of
       the operands is NaN.  This will cause an exception.  To avoid this, C99
       defines the macros listed below.

       These macros are guaranteed to evaluate their arguments only once.  The
       arguments must be of real floating-point type (note: do not pass integer
       values as arguments to these macros, since the arguments will not be
       promoted to real-floating types).

       isgreater()
              determines (x) > (y) without an exception if x or y is NaN.

       isgreaterequal()
              determines (x) >= (y) without an exception if x or y is NaN.

       isless()
              determines (x) < (y) without an exception if x or y is NaN.

       islessequal()
              determines (x) <= (y) without an exception if x or y is NaN.

       islessgreater()
              determines (x) < (y) || (x) > (y) without an exception if x or y is
              NaN.  This macro is not equivalent to x != y because that expression
              is true if x or y is NaN.

       isunordered()
              determines whether its arguments are unordered, that is, whether at
              least one of the arguments is a NaN.

RETURN VALUE top

       The macros other than isunordered() return the result of the relational
       comparison; these macros return 0 if either argument is a NaN.

       isunordered() returns 1 if x or y is NaN and 0 otherwise.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       Not all hardware supports these functions, and where hardware support isn't
       provided, they will be emulated by macros.  This will result in a
       performance penalty.  Don't use these functions if NaN is of no concern for
       you.

SEE ALSO top

       fpclassify(3), isnan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-06                        ISGREATER(3)


iso_8859-1(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-1(7)                Linux Programmer's Manual               ISO_8859-1(7)

NAME top

       iso_8859-1  -  ISO  8859-1  character  set  encoded  in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  Especially important is ISO
       8859-1, the "Latin Alphabet No. 1", which has become widely implemented and
       may already be seen as the de-facto standard ASCII replacement.

       ISO 8859-1 supports the following languages: Afrikaans, Basque, Catalan,
       Danish, Dutch, English, Faeroese, Finnish, French, Galician, German,
       Icelandic, Irish, Italian, Norwegian, Portuguese, Scottish, Spanish, and
       Swedish.

       Note that the ISO 8859-1 characters are also the first 256 characters of
       ISO 10646 (Unicode).

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-1 Characters

       The following table displays the characters in ISO 8859-1 (Latin-1), which
       are printable and unlisted in the ascii(7) manual page.  The fourth column
       will only show the proper glyphs in an environment configured for ISO
       8859-1.

       Oct  Dec  Hex  Char  Description
       ------------------------------------------------------------------------
       240  160  A0         NO-BREAK SPACE
       241  161  A1    ,i    INVERTED EXCLAMATION MARK
       242  162  A2    /c    CENT SIGN
       243  163  A3    -L    POUND SIGN
       244  164  A4    ox    CURRENCY SIGN
       245  165  A5    =Y    YEN SIGN
       246  166  A6    |    BROKEN BAR
       247  167  A7    S    SECTION SIGN
       250  168  A8    "    DIAERESIS
       251  169  A9   (C)   COPYRIGHT SIGN
       252  170  AA    _a    FEMININE ORDINAL INDICATOR
       253  171  AB    <<   LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254  172  AC    ~    NOT SIGN
       255  173  AD         SOFT HYPHEN (shown as a hyphen at line breaks) [1]
       256  174  AE   (R_)   REGISTERED SIGN
       257  175  AF         MACRON

       260  176  B0    o    DEGREE SIGN
       261  177  B1    +-   PLUS-MINUS SIGN
       262  178  B2    2    SUPERSCRIPT TWO
       263  179  B3    3    SUPERSCRIPT THREE
       264  180  B4    '    ACUTE ACCENT
       265  181  B5    ,u    MICRO SIGN
       266  182  B6    9|   PILCROW SIGN
       267  183  B7    .    MIDDLE DOT
       270  184  B8    ,    CEDILLA
       271  185  B9    1    SUPERSCRIPT ONE
       272  186  BA    _o    MASCULINE ORDINAL INDICATOR
       273  187  BB    >>   RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274  188  BC   1/4   VULGAR FRACTION ONE QUARTER
       275  189  BD   1/2   VULGAR FRACTION ONE HALF
       276  190  BE   3/4   VULGAR FRACTION THREE QUARTERS
       277  191  BF    'c    INVERTED QUESTION MARK
       300  192  C0    `A    LATIN CAPITAL LETTER A WITH GRAVE
       301  193  C1    'A    LATIN CAPITAL LETTER A WITH ACUTE
       302  194  C2    ^A    LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303  195  C3    ~A    LATIN CAPITAL LETTER A WITH TILDE
       304  196  C4    "A    LATIN CAPITAL LETTER A WITH DIAERESIS
       305  197  C5    oA    LATIN CAPITAL LETTER A WITH RING ABOVE
       306  198  C6    AE   LATIN CAPITAL LETTER AE
       307  199  C7    ,C    LATIN CAPITAL LETTER C WITH CEDILLA
       310  200  C8    `E    LATIN CAPITAL LETTER E WITH GRAVE
       311  201  C9    'E    LATIN CAPITAL LETTER E WITH ACUTE
       312  202  CA    ^E    LATIN CAPITAL LETTER E WITH CIRCUMFLEX
       313  203  CB    "E    LATIN CAPITAL LETTER E WITH DIAERESIS
       314  204  CC    `I    LATIN CAPITAL LETTER I WITH GRAVE
       315  205  CD    'I    LATIN CAPITAL LETTER I WITH ACUTE
       316  206  CE    ^I    LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317  207  CF    "I    LATIN CAPITAL LETTER I WITH DIAERESIS
       320  208  D0    -D    LATIN CAPITAL LETTER ETH
       321  209  D1    ~N    LATIN CAPITAL LETTER N WITH TILDE
       322  210  D2    `O    LATIN CAPITAL LETTER O WITH GRAVE
       323  211  D3    'O    LATIN CAPITAL LETTER O WITH ACUTE
       324  212  D4    ^O    LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325  213  D5    ~O    LATIN CAPITAL LETTER O WITH TILDE
       326  214  D6    "O    LATIN CAPITAL LETTER O WITH DIAERESIS
       327  215  D7    x    MULTIPLICATION SIGN
       330  216  D8    /O    LATIN CAPITAL LETTER O WITH STROKE
       331  217  D9    `U    LATIN CAPITAL LETTER U WITH GRAVE
       332  218  DA    'U    LATIN CAPITAL LETTER U WITH ACUTE
       333  219  DB    ^U    LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334  220  DC    "U    LATIN CAPITAL LETTER U WITH DIAERESIS
       335  221  DD    'Y    LATIN CAPITAL LETTER Y WITH ACUTE
       336  222  DE    Ib    LATIN CAPITAL LETTER THORN
       337  223  DF    B    LATIN SMALL LETTER SHARP S
       340  224  E0    `a    LATIN SMALL LETTER A WITH GRAVE
       341  225  E1    'a    LATIN SMALL LETTER A WITH ACUTE
       342  226  E2    ^a    LATIN SMALL LETTER A WITH CIRCUMFLEX
       343  227  E3    ~a    LATIN SMALL LETTER A WITH TILDE
       344  228  E4    "a    LATIN SMALL LETTER A WITH DIAERESIS
       345  229  E5    oa    LATIN SMALL LETTER A WITH RING ABOVE
       346  230  E6    ae   LATIN SMALL LETTER AE
       347  231  E7    ,c    LATIN SMALL LETTER C WITH CEDILLA
       350  232  E8    `e    LATIN SMALL LETTER E WITH GRAVE
       351  233  E9    'e    LATIN SMALL LETTER E WITH ACUTE
       352  234  EA    ^e    LATIN SMALL LETTER E WITH CIRCUMFLEX
       353  235  EB    "e    LATIN SMALL LETTER E WITH DIAERESIS
       354  236  EC    `i    LATIN SMALL LETTER I WITH GRAVE
       355  237  ED    'i    LATIN SMALL LETTER I WITH ACUTE
       356  238  EE    ^i    LATIN SMALL LETTER I WITH CIRCUMFLEX
       357  239  EF    "i    LATIN SMALL LETTER I WITH DIAERESIS
       360  240  F0    `'o    LATIN SMALL LETTER ETH

       361  241  F1    ~n    LATIN SMALL LETTER N WITH TILDE
       362  242  F2    `o    LATIN SMALL LETTER O WITH GRAVE
       363  243  F3    'o    LATIN SMALL LETTER O WITH ACUTE
       364  244  F4    ^o    LATIN SMALL LETTER O WITH CIRCUMFLEX
       365  245  F5    ~o    LATIN SMALL LETTER O WITH TILDE
       366  246  F6    "o    LATIN SMALL LETTER O WITH DIAERESIS
       367  247  F7   -:-   DIVISION SIGN
       370  248  F8    /o    LATIN SMALL LETTER O WITH STROKE
       371  249  F9    `u    LATIN SMALL LETTER U WITH GRAVE
       372  250  FA    'u    LATIN SMALL LETTER U WITH ACUTE
       373  251  FB    ^u    LATIN SMALL LETTER U WITH CIRCUMFLEX
       374  252  FC    "u    LATIN SMALL LETTER U WITH DIAERESIS
       375  253  FD    'y    LATIN SMALL LETTER Y WITH ACUTE
       376  254  FE    pb    LATIN SMALL LETTER THORN
       377  255  FF    "y    LATIN SMALL LETTER Y WITH DIAERESIS

       [1] See groff_char(7) (soft hyphen) and the standard ISO 8859-1 ("shy",
           paragraph 6.3.3) or the equivalent version from your national
           standardization body.

SEE ALSO top

       ascii(7), iso_8859-15(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-14                       ISO_8859-1(7)


iso_8859-10(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-10(7)               Linux Programmer's Manual              ISO_8859-10(7)

NAME top

       iso_8859-10  -  ISO  8859-10  character  set encoded in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-10 encodes the
       characters used in Nordic languages.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-10 Characters

       The following table displays the characters in ISO 8859-10, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-10.

       Oct   Dec   Hex   Char   Description
       ----------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LATIN CAPITAL LETTER A WITH OGONEK
       242   162   A2     /c     LATIN CAPITAL LETTER E WITH MACRON
       243   163   A3     -L     LATIN CAPITAL LETTER G WITH CEDILLA
       244   164   A4     ox     LATIN CAPITAL LETTER I WITH MACRON
       245   165   A5     =Y     LATIN CAPITAL LETTER I WITH TILDE
       246   166   A6     |     LATIN CAPITAL LETTER K WITH CEDILLA
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     LATIN CAPITAL LETTER L WITH CEDILLA
       251   169   A9    (C)    LATIN CAPITAL LETTER D WITH STROKE
       252   170   AA     _a     LATIN CAPITAL LETTER S WITH CARON
       253   171   AB     <<    LATIN CAPITAL LETTER T WITH STROKE
       254   172   AC     ~     LATIN CAPITAL LETTER Z WITH CARON
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    LATIN CAPITAL LETTER U WITH MACRON
       257   175   AF           LATIN CAPITAL LETTER ENG (Sami)
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    LATIN SMALL LETTER A WITH OGONEK
       262   178   B2     2     LATIN SMALL LETTER E WITH MACRON
       263   179   B3     3     LATIN SMALL LETTER G WITH CEDILLA
       264   180   B4     '     LATIN SMALL LETTER I WITH MACRON
       265   181   B5     ,u     LATIN SMALL LETTER I WITH TILDE
       266   182   B6     9|    LATIN SMALL LETTER K WITH CEDILLA
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     LATIN SMALL LETTER L WITH CEDILLA
       271   185   B9     1     LATIN SMALL LETTER D WITH STROKE

       272   186   BA     _o     LATIN SMALL LETTER S WITH CARON
       273   187   BB     >>    LATIN SMALL LETTER T WITH STROKE
       274   188   BC    1/4    LATIN SMALL LETTER Z WITH CARON
       275   189   BD    1/2    HORIZONTAL BAR
       276   190   BE    3/4    LATIN SMALL LETTER U WITH MACRON
       277   191   BF     'c     LATIN SMALL LETTER ENG (Sami)
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH MACRON
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH TILDE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER A WITH RING ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER AE
       307   199   C7     ,C     LATIN CAPITAL LETTER I WITH OGONEK
       310   200   C8     `E     LATIN CAPITAL LETTER C WITH CARON
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH OGONEK
       312   202   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER E WITH DOT ABOVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH DIAERESIS
       320   208   D0     -D     LATIN CAPITAL LETTER ETH (Icelandic)
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH CEDILLA
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH MACRON
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH TILDE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     LATIN CAPITAL LETTER U WITH TILDE
       330   216   D8     /O     LATIN CAPITAL LETTER O WITH STROKE
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH OGONEK
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER Y WITH ACUTE
       336   222   DE     Ib     LATIN CAPITAL LETTER THORN (Icelandic)
       337   223   DF     B     LATIN SMALL LETTER SHARP S (German)
       340   224   E0     `a     LATIN SMALL LETTER A WITH MACRON
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH TILDE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER A WITH RING ABOVE
       346   230   E6     ae    LATIN SMALL LETTER AE
       347   231   E7     ,c     LATIN SMALL LETTER I WITH OGONEK
       350   232   E8     `e     LATIN SMALL LETTER C WITH CARON
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH OGONEK
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER E WITH DOT ABOVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH DIAERESIS
       360   240   F0     `'o     LATIN SMALL LETTER ETH (Icelandic)
       361   241   F1     ~n     LATIN SMALL LETTER N WITH CEDILLA
       362   242   F2     `o     LATIN SMALL LETTER O WITH MACRON
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH TILDE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    LATIN SMALL LETTER U WITH TILDE
       370   248   F8     /o     LATIN SMALL LETTER O WITH STROKE
       371   249   F9     `u     LATIN SMALL LETTER U WITH OGONEK
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE

       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER Y WITH ACUTE
       376   254   FE     pb     LATIN SMALL LETTER THORN (Icelandic)
       377   255   FF     "y     LATIN SMALL LETTER KRA (Greenlandic)

NOTES top

       ISO 8859-10 is also known as Latin-6.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                      ISO_8859-10(7)


iso_8859-11(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-11(7)               Linux Programmer's Manual              ISO_8859-11(7)

NAME top

       iso_8859-11  -  ISO  8859-11  character  set encoded in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-11 encodes the
       characters used in the Thai language.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-11 Characters

       The following table displays the characters in ISO 8859-11, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-11.

       Oct   Dec   Hex   Char   Description
       ---------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     THAI CHARACTER KO KAI
       242   162   A2     /c     THAI CHARACTER KHO KHAI
       243   163   A3     -L     THAI CHARACTER KHO KHUAT
       244   164   A4     ox     THAI CHARACTER KHO KHWAI
       245   165   A5     =Y     THAI CHARACTER KHO KHON
       246   166   A6     |     THAI CHARACTER KHO RAKHANG
       247   167   A7     S     THAI CHARACTER NGO NGU
       250   168   A8     "     THAI CHARACTER CHO CHAN
       251   169   A9    (C)    THAI CHARACTER CHO CHING
       252   170   AA     _a     THAI CHARACTER CHO CHANG
       253   171   AB     <<    THAI CHARACTER SO SO
       254   172   AC     ~     THAI CHARACTER CHO CHOE
       255   173   AD           THAI CHARACTER YO YING
       256   174   AE    (R_)    THAI CHARACTER DO CHADA
       257   175   AF           THAI CHARACTER TO PATAK
       260   176   B0     o     THAI CHARACTER THO THAN
       261   177   B1     +-    THAI CHARACTER THO NANGMONTHO
       262   178   B2     2     THAI CHARACTER THO PHUTHAO
       263   179   B3     3     THAI CHARACTER NO NEN
       264   180   B4     '     THAI CHARACTER DO DEK
       265   181   B5     ,u     THAI CHARACTER TO TAO
       266   182   B6     9|    THAI CHARACTER THO THUNG
       267   183   B7     .     THAI CHARACTER THO THAHAN
       270   184   B8     ,     THAI CHARACTER THO THONG
       271   185   B9     1     THAI CHARACTER NO NU

       272   186   BA     _o     THAI CHARACTER BO BAIMAI
       273   187   BB     >>    THAI CHARACTER PO PLA
       274   188   BC    1/4    THAI CHARACTER PHO PHUNG
       275   189   BD    1/2    THAI CHARACTER FO FA
       276   190   BE    3/4    THAI CHARACTER PHO PHAN
       277   191   BF     'c     THAI CHARACTER FO FAN
       300   192   C0     `A     THAI CHARACTER PHO SAMPHAO
       301   193   C1     'A     THAI CHARACTER MO MA
       302   194   C2     ^A     THAI CHARACTER YO YAK
       303   195   C3     ~A     THAI CHARACTER RO RUA
       304   196   C4     "A     THAI CHARACTER RU
       305   197   C5     oA     THAI CHARACTER LO LING
       306   198   C6     AE    THAI CHARACTER LU
       307   199   C7     ,C     THAI CHARACTER WO WAEN
       310   200   C8     `E     THAI CHARACTER SO SALA
       311   201   C9     'E     THAI CHARACTER SO RUSI
       312   202   CA     ^E     THAI CHARACTER SO SUA
       313   203   CB     "E     THAI CHARACTER HO HIP
       314   204   CC     `I     THAI CHARACTER LO CHULA
       315   205   CD     'I     THAI CHARACTER O ANG
       316   206   CE     ^I     THAI CHARACTER HO NOKHUK
       317   207   CF     "I     THAI CHARACTER PAIYANNOI
       320   208   D0     -D     THAI CHARACTER SARA A
       321   209   D1     ~N     THAI CHARACTER MAI HAN-AKAT
       322   210   D2     `O     THAI CHARACTER SARA AA
       323   211   D3     'O     THAI CHARACTER SARA AM
       324   212   D4     ^O     THAI CHARACTER SARA I
       325   213   D5     ~O     THAI CHARACTER SARA II
       326   214   D6     "O     THAI CHARACTER SARA UE
       327   215   D7     x     THAI CHARACTER SARA UEE
       330   216   D8     /O     THAI CHARACTER SARA U
       331   217   D9     `U     THAI CHARACTER SARA UU
       332   218   DA     'U     THAI CHARACTER PHINTHU
       337   223   DF     B     THAI CURRENCY SYMBOL BAHT
       340   224   E0     `a     THAI CHARACTER SARA E
       341   225   E1     'a     THAI CHARACTER SARA AE
       342   226   E2     ^a     THAI CHARACTER SARA O
       343   227   E3     ~a     THAI CHARACTER SARA AI MAIMUAN
       344   228   E4     "a     THAI CHARACTER SARA AI MAIMALAI
       345   229   E5     oa     THAI CHARACTER LAKKHANGYAO
       346   230   E6     ae    THAI CHARACTER MAIYAMOK
       347   231   E7     ,c     THAI CHARACTER MAITAIKHU
       350   232   E8     `e     THAI CHARACTER MAI EK
       351   233   E9     'e     THAI CHARACTER MAI THO
       352   234   EA     ^e     THAI CHARACTER MAI TRI
       353   235   EB     "e     THAI CHARACTER MAI CHATTAWA
       354   236   EC     `i     THAI CHARACTER THANTHAKHAT
       355   237   ED     'i     THAI CHARACTER NIKHAHIT
       356   238   EE     ^i     THAI CHARACTER YAMAKKAN
       357   239   EF     "i     THAI CHARACTER FONGMAN
       360   240   F0     `'o     THAI DIGIT ZERO
       361   241   F1     ~n     THAI DIGIT ONE
       362   242   F2     `o     THAI DIGIT TWO
       363   243   F3     'o     THAI DIGIT THREE
       364   244   F4     ^o     THAI DIGIT FOUR
       365   245   F5     ~o     THAI DIGIT FIVE
       366   246   F6     "o     THAI DIGIT SIX
       367   247   F7    -:-    THAI DIGIT SEVEN
       370   248   F8     /o     THAI DIGIT EIGHT
       371   249   F9     `u     THAI DIGIT NINE
       372   250   FA     'u     THAI CHARACTER ANGKHANKHU
       373   251   FB     ^u     THAI CHARACTER KHOMUT

NOTES top

       ISO 8859-11 is the same as TIS (Thai Industrial Standard) 620-2253,
       commonly known as TIS-620, except for the character in position a0: ISO
       8859-11 defines this as "nonbreaking space", while TIS 620 leaves it
       undefined.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                      ISO_8859-11(7)


iso_8859-13(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-13(7)               Linux Programmer's Manual              ISO_8859-13(7)

NAME top

       iso_8859-13  -  ISO  8859-13  character  set encoded in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-13 encodes the
       characters used in Baltic Rim languages.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-13 Characters

       The following table displays the characters in ISO 8859-13, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-13.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     RIGHT DOUBLE QUOTATION MARK
       242   162   A2     /c     CENT SIGN
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     CURRENCY SIGN
       245   165   A5     =Y     DOUBLE LOW-9 QUOTATION MARK
       246   166   A6     |     BROKEN BAR
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     LATIN CAPITAL LETTER O WITH STROKE
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     LATIN CAPITAL LETTER R WITH CEDILLA
       253   171   AB     <<    LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254   172   AC     ~     NOT SIGN
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    REGISTERED SIGN
       257   175   AF           LATIN CAPITAL LETTER AE
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    PLUS-MINUS SIGN
       262   178   B2     2     SUPERSCRIPT TWO
       263   179   B3     3     SUPERSCRIPT THREE
       264   180   B4     '     LEFT DOUBLE QUOTATION MARK
       265   181   B5     ,u     MICRO SIGN
       266   182   B6     9|    PILCROW SIGN
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     LATIN SMALL LETTER O WITH STROKE
       271   185   B9     1     SUPERSCRIPT ONE

       272   186   BA     _o     LATIN SMALL LETTER R WITH CEDILLA
       273   187   BB     >>    RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274   188   BC    1/4    VULGAR FRACTION ONE QUARTER
       275   189   BD    1/2    VULGAR FRACTION ONE HALF
       276   190   BE    3/4    VULGAR FRACTION THREE QUARTERS
       277   191   BF     'c     LATIN SMALL LETTER AE
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH OGONEK
       301   193   C1     'A     LATIN CAPITAL LETTER I WITH OGONEK
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH MACRON
       303   195   C3     ~A     LATIN CAPITAL LETTER C WITH ACUTE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER A WITH RING ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER E WITH OGONEK
       307   199   C7     ,C     LATIN CAPITAL LETTER E WITH MACRON
       310   200   C8     `E     LATIN CAPITAL LETTER C WITH CARON
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER Z WITH ACUTE
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DOT ABOVE
       314   204   CC     `I     LATIN CAPITAL LETTER G WITH CEDILLA
       315   205   CD     'I     LATIN CAPITAL LETTER K WITH CEDILLA
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH MACRON
       317   207   CF     "I     LATIN CAPITAL LETTER L WITH CEDILLA
       320   208   D0     -D     LATIN CAPITAL LETTER S WITH CARON
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH ACUTE
       322   210   D2     `O     LATIN CAPITAL LETTER N WITH CEDILLA
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH MACRON
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH TILDE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     MULTIPLICATION SIGN
       330   216   D8     /O     LATIN CAPITAL LETTER U WITH OGONEK
       331   217   D9     `U     LATIN CAPITAL LETTER L WITH STROKE
       332   218   DA     'U     LATIN CAPITAL LETTER S WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH MACRON
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER Z WITH DOT ABOVE
       336   222   DE     Ib     LATIN CAPITAL LETTER Z WITH CARON
       337   223   DF     B     LATIN SMALL LETTER SHARP S
       340   224   E0     `a     LATIN SMALL LETTER A WITH OGONEK
       341   225   E1     'a     LATIN SMALL LETTER I WITH OGONEK
       342   226   E2     ^a     LATIN SMALL LETTER A WITH MACRON
       343   227   E3     ~a     LATIN SMALL LETTER C WITH ACUTE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER A WITH RING ABOVE
       346   230   E6     ae    LATIN SMALL LETTER E WITH OGONEK
       347   231   E7     ,c     LATIN SMALL LETTER E WITH MACRON
       350   232   E8     `e     LATIN SMALL LETTER C WITH CARON
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER Z WITH ACUTE
       353   235   EB     "e     LATIN SMALL LETTER E WITH DOT ABOVE
       354   236   EC     `i     LATIN SMALL LETTER G WITH CEDILLA
       355   237   ED     'i     LATIN SMALL LETTER K WITH CEDILLA
       356   238   EE     ^i     LATIN SMALL LETTER I WITH MACRON
       357   239   EF     "i     LATIN SMALL LETTER L WITH CEDILLA
       360   240   F0     `'o     LATIN SMALL LETTER S WITH CARON
       361   241   F1     ~n     LATIN SMALL LETTER N WITH ACUTE
       362   242   F2     `o     LATIN SMALL LETTER N WITH CEDILLA
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH MACRON
       365   245   F5     ~o     LATIN SMALL LETTER O WITH TILDE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    DIVISION SIGN
       370   248   F8     /o     LATIN SMALL LETTER U WITH OGONEK
       371   249   F9     `u     LATIN SMALL LETTER L WITH STROKE
       372   250   FA     'u     LATIN SMALL LETTER S WITH ACUTE

       373   251   FB     ^u     LATIN SMALL LETTER U WITH MACRON
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER Z WITH DOT ABOVE
       376   254   FE     pb     LATIN SMALL LETTER Z WITH CARON
       377   255   FF     "y     RIGHT SINGLE QUOTATION MARK

NOTES top

       ISO 8859-13 is also known as Latin-7.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                      ISO_8859-13(7)


iso_8859-14(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-14(7)               Linux Programmer's Manual              ISO_8859-14(7)

NAME top

       iso_8859-14  -  ISO  8859-14  character  set encoded in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-14 encodes the
       characters used in Celtic languages.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-14 Characters

       The following table displays the characters in ISO 8859-14, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-14.

       Oct   Dec   Hex   Char   Description
       ----------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LATIN CAPITAL LETTER B WITH DOT ABOVE
       242   162   A2     /c     LATIN SMALL LETTER B WITH DOT ABOVE
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     LATIN CAPITAL LETTER C WITH DOT ABOVE
       245   165   A5     =Y     LATIN SMALL LETTER C WITH DOT ABOVE
       246   166   A6     |     LATIN CAPITAL LETTER D WITH DOT ABOVE
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     LATIN CAPITAL LETTER W WITH GRAVE
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     LATIN CAPITAL LETTER W WITH ACUTE
       253   171   AB     <<    LATIN SMALL LETTER D WITH DOT ABOVE
       254   172   AC     ~     LATIN CAPITAL LETTER Y WITH GRAVE
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    REGISTERED SIGN
       257   175   AF           LATIN CAPITAL LETTER Y WITH DIAERESIS
       260   176   B0     o     LATIN CAPITAL LETTER F WITH DOT ABOVE
       261   177   B1     +-    LATIN SMALL LETTER F WITH DOT ABOVE
       262   178   B2     2     LATIN CAPITAL LETTER G WITH DOT ABOVE
       263   179   B3     3     LATIN SMALL LETTER G WITH DOT ABOVE
       264   180   B4     '     LATIN CAPITAL LETTER M WITH DOT ABOVE
       265   181   B5     ,u     LATIN SMALL LETTER M WITH DOT ABOVE
       266   182   B6     9|    PILCROW SIGN
       267   183   B7     .     LATIN CAPITAL LETTER P WITH DOT ABOVE
       270   184   B8     ,     LATIN SMALL LETTER W WITH GRAVE
       271   185   B9     1     LATIN SMALL LETTER P WITH DOT ABOVE

       272   186   BA     _o     LATIN SMALL LETTER W WITH ACUTE
       273   187   BB     >>    LATIN CAPITAL LETTER S WITH DOT ABOVE
       274   188   BC    1/4    LATIN SMALL LETTER Y WITH GRAVE
       275   189   BD    1/2    LATIN CAPITAL LETTER W WITH DIAERESIS
       276   190   BE    3/4    LATIN SMALL LETTER W WITH DIAERESIS
       277   191   BF     'c     LATIN SMALL LETTER S WITH DOT ABOVE
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH GRAVE
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH TILDE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER A WITH RING ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER AE
       307   199   C7     ,C     LATIN CAPITAL LETTER C WITH CEDILLA
       310   200   C8     `E     LATIN CAPITAL LETTER E WITH GRAVE
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH CIRCUMFLEX
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER I WITH GRAVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH DIAERESIS
       320   208   D0     -D     LATIN CAPITAL LETTER W WITH CIRCUMFLEX
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH TILDE
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH GRAVE
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH TILDE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     LATIN CAPITAL LETTER T WITH DOT ABOVE
       330   216   D8     /O     LATIN CAPITAL LETTER O WITH STROKE
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH GRAVE
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER Y WITH ACUTE
       336   222   DE     Ib     LATIN CAPITAL LETTER Y WITH CIRCUMFLEX
       337   223   DF     B     LATIN SMALL LETTER SHARP S
       340   224   E0     `a     LATIN SMALL LETTER A WITH GRAVE
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH TILDE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER A WITH RING ABOVE
       346   230   E6     ae    LATIN SMALL LETTER AE
       347   231   E7     ,c     LATIN SMALL LETTER C WITH CEDILLA
       350   232   E8     `e     LATIN SMALL LETTER E WITH GRAVE
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH CIRCUMFLEX
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER I WITH GRAVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH DIAERESIS
       360   240   F0     `'o     LATIN SMALL LETTER W WITH CIRCUMFLEX
       361   241   F1     ~n     LATIN SMALL LETTER N WITH TILDE
       362   242   F2     `o     LATIN SMALL LETTER O WITH GRAVE
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH TILDE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    LATIN SMALL LETTER T WITH DOT ABOVE
       370   248   F8     /o     LATIN SMALL LETTER O WITH STROKE
       371   249   F9     `u     LATIN SMALL LETTER U WITH GRAVE
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE

       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER Y WITH ACUTE
       376   254   FE     pb     LATIN SMALL LETTER Y WITH CIRCUMFLEX
       377   255   FF     "y     LATIN SMALL LETTER Y WITH DIAERESIS

NOTES top

       ISO 8859-14 is also known as Latin-8.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                      ISO_8859-14(7)


iso_8859-15(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-15(7)               Linux Programmer's Manual              ISO_8859-15(7)

NAME top

       iso_8859-15  -  ISO  8859-15  character  set encoded in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  Especially important is ISO
       8859-1, the "Latin Alphabet No. 1", which has become widely implemented and
       may already be seen as the de-facto standard ASCII replacement.  However,
       it lacks the EURO symbol and does not fully cover Finnish and French.  ISO
       8859-15 is a modification of ISO 8859-1 that covers these needs.

       ISO 8859-15 supports the following languages: Albanian, Basque, Breton,
       Catalan, Danish, Dutch, English, Estonian, Faroese, Finnish, French,
       Frisian, Galician, German, Greenlandic, Icelandic, Irish Gaelic, Italian,
       Latin, Luxemburgish, Norwegian, Portuguese, Rhaeto-Romanic, Scottish
       Gaelic, Spanish, and Swedish.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-15 Characters

       The following table displays the characters in ISO 8859-15 (Latin-9), which
       are printable and unlisted in the ascii(7) manual page.  The fourth column
       will only show the proper glyphs in an environment configured for ISO
       8859-15.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     INVERTED EXCLAMATION MARK
       242   162   A2     /c     CENT SIGN
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     EURO SIGN
       245   165   A5     =Y     YEN SIGN
       246   166   A6     |     LATIN CAPITAL LETTER S WITH CARON
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     LATIN SMALL LETTER S WITH CARON
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     FEMININE ORDINAL INDICATOR
       253   171   AB     <<    LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254   172   AC     ~     NOT SIGN
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    REGISTERED SIGN
       257   175   AF           MACRON

       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    PLUS-MINUS SIGN
       262   178   B2     2     SUPERSCRIPT TWO
       263   179   B3     3     SUPERSCRIPT THREE
       264   180   B4     '     LATIN CAPITAL LETTER Z WITH CARON
       265   181   B5     ,u     MICRO SIGN
       266   182   B6     9|    PILCROW SIGN
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     LATIN SMALL LETTER Z WITH CARON
       271   185   B9     1     SUPERSCRIPT ONE
       272   186   BA     _o     MASCULINE ORDINAL INDICATOR
       273   187   BB     >>    RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274   188   BC    1/4    LATIN CAPITAL LIGATURE OE
       275   189   BD    1/2    LATIN SMALL LIGATURE OE
       276   190   BE    3/4    LATIN CAPITAL LETTER Y WITH DIAERESIS
       277   191   BF     'c     INVERTED QUESTION MARK
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH GRAVE
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH TILDE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER A WITH RING ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER AE
       307   199   C7     ,C     LATIN CAPITAL LETTER C WITH CEDILLA
       310   200   C8     `E     LATIN CAPITAL LETTER E WITH GRAVE
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH CIRCUMFLEX
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER I WITH GRAVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH DIAERESIS
       320   208   D0     -D     LATIN CAPITAL LETTER ETH
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH TILDE
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH GRAVE
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH TILDE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     MULTIPLICATION SIGN
       330   216   D8     /O     LATIN CAPITAL LETTER O WITH STROKE
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH GRAVE
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER Y WITH ACUTE
       336   222   DE     Ib     LATIN CAPITAL LETTER THORN
       337   223   DF     B     LATIN SMALL LETTER SHARP S
       340   224   E0     `a     LATIN SMALL LETTER A WITH GRAVE
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH TILDE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER A WITH RING ABOVE
       346   230   E6     ae    LATIN SMALL LETTER AE
       347   231   E7     ,c     LATIN SMALL LETTER C WITH CEDILLA
       350   232   E8     `e     LATIN SMALL LETTER E WITH GRAVE
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH CIRCUMFLEX
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER I WITH GRAVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH DIAERESIS
       360   240   F0     `'o     LATIN SMALL LETTER ETH

       361   241   F1     ~n     LATIN SMALL LETTER N WITH TILDE
       362   242   F2     `o     LATIN SMALL LETTER O WITH GRAVE
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH TILDE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    DIVISION SIGN
       370   248   F8     /o     LATIN SMALL LETTER O WITH STROKE
       371   249   F9     `u     LATIN SMALL LETTER U WITH GRAVE
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE
       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER Y WITH ACUTE
       376   254   FE     pb     LATIN SMALL LETTER THORN
       377   255   FF     "y     LATIN SMALL LETTER Y WITH DIAERESIS

SEE ALSO top

       ascii(7), iso_8859-1(7)

COLOPHON top

       This page is part of release 3.45 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                               1999-05-31                      ISO_8859-15(7)


iso_8859-16(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-16(7)               Linux Programmer's Manual              ISO_8859-16(7)

NAME top

       iso_8859-16  -  ISO  8859-16  character  set encoded in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-16, the "Latin
       Alphabet No. 10" is used to encode Central and Eastern European Latin
       characters and is not implemented yet by any program vendors.

       ISO 8859-16 supports the following languages: Albanian, Bosnian, Croatian,
       English, Finnish, German, Hungarian, Irish, Polish, Romanian, Slovenian and
       Serbian.

       Also note that the following Cyrillic-based languages have one-to-one
       transliterations to Latin 10: Macedonian and Serbian.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-16 Characters

       The following table displays the characters in ISO 8859-16 (Latin-10),
       which are printable and unlisted in the ascii(7) manual page.  The fourth
       column will only show the proper glyphs in an environment configured for
       ISO 8859-16.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LATIN CAPITAL LETTER A WITH OGONEK
       242   162   A2     /c     LATIN SMALL LETTER A WITH OGONEK
       243   163   A3     -L     LATIN CAPITAL LETTER L WITH STROKE
       244   164   A4     ox     EURO SIGN
       245   165   A5     =Y     DOUBLE LOW-9 QUOTATION MARK
       246   166   A6     |     LATIN CAPITAL LETTER S WITH CARON
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     LATIN SMALL LETTER S WITH CARON
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     LATIN CAPITAL LETTER S WITH COMMA BELOW
       253   171   AB     <<    LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254   172   AC     ~     LATIN CAPITAL LETTER Z WITH ACUTE
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    LATIN SMALL LETTER Z WITH ACUTE
       257   175   AF           LATIN CAPITAL LETTER Z WITH DOT ABOVE
       260   176   B0     o     DEGREE SIGN

       261   177   B1     +-    PLUS-MINUS SIGN
       262   178   B2     2     LATIN CAPITAL LETTER C WITH CARON
       263   179   B3     3     LATIN SMALL LETTER L WITH STROKE
       264   180   B4     '     LATIN CAPITAL LETTER Z WITH CARON
       265   181   B5     ,u     LEFT DOUBLE QUOTATION MARK
       266   182   B6     9|    PILCROW SIGN
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     LATIN SMALL LETTER Z WITH CARON
       271   185   B9     1     LATIN SMALL LETTER C WITH CARON
       272   186   BA     _o     LATIN SMALL LETTER S WITH COMMA BELOW
       273   187   BB     >>    RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274   188   BC    1/4    LATIN CAPITAL LIGATURE OE
       275   189   BD    1/2    LATIN SMALL LIGATURE OE
       276   190   BE    3/4    LATIN CAPITAL LETTER Y WITH DIAERESIS
       277   191   BF     'c     LATIN SMALL LETTER Z WITH DOT ABOVE
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH GRAVE
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH BREVE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER C WITH ACUTE
       306   198   C6     AE    LATIN CAPITAL LETTER AE
       307   199   C7     ,C     LATIN CAPITAL LETTER C WITH CEDILLA
       310   200   C8     `E     LATIN CAPITAL LETTER E WITH GRAVE
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH CIRCUMFLEX
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER I WITH GRAVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH DIAERESIS
       320   208   D0     -D     LATIN CAPITAL LETTER D WITH STROKE
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH ACUTE
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH GRAVE
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH DOUBLE ACUTE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     LATIN CAPITAL LETTER S WITH ACUTE
       330   216   D8     /O     LATIN CAPITAL LETTER U WITH DOUBLE ACUTE
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH GRAVE
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER E WITH OGONEK
       336   222   DE     Ib     LATIN CAPITAL LETTER T WITH COMMA BELOW
       337   223   DF     B     LATIN SMALL LETTER SHARP S
       340   224   E0     `a     LATIN SMALL LETTER A WITH GRAVE
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH BREVE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER C WITH ACUTE
       346   230   E6     ae    LATIN SMALL LETTER AE
       347   231   E7     ,c     LATIN SMALL LETTER C WITH CEDILLA
       350   232   E8     `e     LATIN SMALL LETTER E WITH GRAVE
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH CIRCUMFLEX
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER I WITH GRAVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH DIAERESIS
       360   240   F0     `'o     LATIN SMALL LETTER D WITH STROKE
       361   241   F1     ~n     LATIN SMALL LETTER N WITH ACUTE

       362   242   F2     `o     LATIN SMALL LETTER O WITH GRAVE
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH DOUBLE ACUTE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    LATIN SMALL LETTER S WITH ACUTE
       370   248   F8     /o     LATIN SMALL LETTER U WITH DOUBLE ACUTE
       371   249   F9     `u     LATIN SMALL LETTER U WITH GRAVE
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE
       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER E WITH OGONEK
       376   254   FE     pb     LATIN SMALL LETTER T WITH COMMA BELOW
       377   255   FF     "y     LATIN SMALL LETTER Y WITH DIAERESIS

SEE ALSO top

       ascii(7), iso_8859-1(7), iso_8859-15(7), iso_8859-2(7)

       ISO 8859-16 (Latin 10) Resources <http://bucovina.chem.tue.nl/fonturi
       /index-en.html>.

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                      ISO_8859-16(7)


iso_8859-2(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-2(7)                Linux Programmer's Manual               ISO_8859-2(7)

NAME top

       iso_8859-2  -  ISO  8859-2  character  set  encoded  in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-2, the "Latin Alphabet
       No. 2" is used to encode Central and Eastern European Latin characters and
       is implemented by several program vendors.

       ISO 8859-2 supports the following languages: Albanian, Bosnian, Croatian,
       Czech, English, Finnish, German, Hungarian, Irish, Polish, Slovak,
       Slovenian and Sorbian.

       Also note that the following Cyrillic-based languages have one-to-one
       transliterations to Latin 2: Macedonian and Serbian.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-2 Characters

       The following table displays the characters in ISO 8859-2 (Latin-2), which
       are printable and unlisted in the ascii(7) manual page.  The fourth column
       will only show the proper glyphs in an environment configured for ISO
       8859-2.

       Oct   Dec   Hex   Char   Description
       ------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LATIN CAPITAL LETTER A WITH OGONEK
       242   162   A2     /c     BREVE
       243   163   A3     -L     LATIN CAPITAL LETTER L WITH STROKE
       244   164   A4     ox     CURRENCY SIGN
       245   165   A5     =Y     LATIN CAPITAL LETTER L WITH CARON
       246   166   A6     |     LATIN CAPITAL LETTER S WITH ACUTE
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     DIAERESIS
       251   169   A9    (C)    LATIN CAPITAL LETTER S WITH CARON
       252   170   AA     _a     LATIN CAPITAL LETTER S WITH CEDILLA
       253   171   AB     <<    LATIN CAPITAL LETTER T WITH CARON
       254   172   AC     ~     LATIN CAPITAL LETTER Z WITH ACUTE
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    LATIN CAPITAL LETTER Z WITH CARON
       257   175   AF           LATIN CAPITAL LETTER Z WITH DOT ABOVE
       260   176   B0     o     DEGREE SIGN

       261   177   B1     +-    LATIN SMALL LETTER A WITH OGONEK
       262   178   B2     2     OGONEK
       263   179   B3     3     LATIN SMALL LETTER L WITH STROKE
       264   180   B4     '     ACUTE ACCENT
       265   181   B5     ,u     LATIN SMALL LETTER L WITH CARON
       266   182   B6     9|    LATIN SMALL LETTER S WITH ACUTE
       267   183   B7     .     CARON
       270   184   B8     ,     CEDILLA
       271   185   B9     1     LATIN SMALL LETTER S WITH CARON
       272   186   BA     _o     LATIN SMALL LETTER S WITH CEDILLA
       273   187   BB     >>    LATIN SMALL LETTER T WITH CARON
       274   188   BC    1/4    LATIN SMALL LETTER Z WITH ACUTE
       275   189   BD    1/2    DOUBLE ACUTE ACCENT
       276   190   BE    3/4    LATIN SMALL LETTER Z WITH CARON
       277   191   BF     'c     LATIN SMALL LETTER Z WITH DOT ABOVE
       300   192   C0     `A     LATIN CAPITAL LETTER R WITH ACUTE
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH BREVE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER L WITH ACUTE
       306   198   C6     AE    LATIN CAPITAL LETTER C WITH ACUTE
       307   199   C7     ,C     LATIN CAPITAL LETTER C WITH CEDILLA
       310   200   C8     `E     LATIN CAPITAL LETTER C WITH CARON
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH OGONEK
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER E WITH CARON
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER D WITH CARON
       320   208   D0     -D     LATIN CAPITAL LETTER D WITH STROKE
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH ACUTE
       322   210   D2     `O     LATIN CAPITAL LETTER N WITH CARON
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH DOUBLE ACUTE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     MULTIPLICATION SIGN
       330   216   D8     /O     LATIN CAPITAL LETTER R WITH CARON
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH RING ABOVE
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH DOUBLE ACUTE
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER Y WITH ACUTE
       336   222   DE     Ib     LATIN CAPITAL LETTER T WITH CEDILLA
       337   223   DF     B     LATIN SMALL LETTER SHARP S
       340   224   E0     `a     LATIN SMALL LETTER R WITH ACUTE
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH BREVE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER L WITH ACUTE
       346   230   E6     ae    LATIN SMALL LETTER C WITH ACUTE
       347   231   E7     ,c     LATIN SMALL LETTER C WITH CEDILLA
       350   232   E8     `e     LATIN SMALL LETTER C WITH CARON
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH OGONEK
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER E WITH CARON
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER D WITH CARON
       360   240   F0     `'o     LATIN SMALL LETTER D WITH STROKE
       361   241   F1     ~n     LATIN SMALL LETTER N WITH ACUTE

       362   242   F2     `o     LATIN SMALL LETTER N WITH CARON
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH DOUBLE ACUTE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    DIVISION SIGN
       370   248   F8     /o     LATIN SMALL LETTER R WITH CARON
       371   249   F9     `u     LATIN SMALL LETTER U WITH RING ABOVE
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE
       373   251   FB     ^u     LATIN SMALL LETTER U WITH DOUBLE ACUTE
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER Y WITH ACUTE
       376   254   FE     pb     LATIN SMALL LETTER T WITH CEDILLA
       377   255   FF     "y     DOT ABOVE

SEE ALSO top

       ascii(7), iso_8859-1(7), iso_8859-16(7)

       ISO 8859-2 (Latin 2) Resources <http://sizif.mf.uni-lj.si/linux/cee
       /iso8859-2.html>.

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                       ISO_8859-2(7)


iso_8859-3(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-3(7)                Linux Programmer's Manual               ISO_8859-3(7)

NAME top

       iso_8859-3  -  ISO  8859-3  character  set  encoded  in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-3 encodes the
       characters used in Southeast European languages.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-3 Characters

       The following table displays the characters in ISO 8859-3, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-3.

       Oct   Dec   Hex   Char   Description
       -----------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LATIN CAPITAL LETTER H WITH STROKE
       242   162   A2     /c     BREVE
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     CURRENCY SIGN
       246   166   A6     |     LATIN CAPITAL LETTER H WITH CIRCUMFLEX
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     DIAERESIS
       251   169   A9    (C)    LATIN CAPITAL LETTER I WITH DOT ABOVE
       252   170   AA     _a     LATIN CAPITAL LETTER S WITH CEDILLA
       253   171   AB     <<    LATIN CAPITAL LETTER G WITH BREVE
       254   172   AC     ~     LATIN CAPITAL LETTER J WITH CIRCUMFLEX
       255   173   AD     _     SOFT HYPHEN
       257   175   AF           LATIN CAPITAL LETTER Z WITH DOT ABOVE
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    LATIN SMALL LETTER H WITH STROKE
       262   178   B2     2     SUPERSCRIPT TWO
       263   179   B3     3     SUPERSCRIPT THREE
       264   180   B4     '     ACUTE ACCENT
       265   181   B5     ,u     MICRO SIGN
       266   182   B6     9|    LATIN SMALL LETTER H WITH CIRCUMFLEX
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     CEDILLA
       271   185   B9     1     LATIN SMALL LETTER DOTLESS I
       272   186   BA     _o     LATIN SMALL LETTER S WITH CEDILLA
       273   187   BB     >>    LATIN SMALL LETTER G WITH BREVE

       274   188   BC    1/4    LATIN SMALL LETTER J WITH CIRCUMFLEX
       275   189   BD    1/2    VULGAR FRACTION ONE HALF
       277   191   BF     'c     LATIN SMALL LETTER Z WITH DOT ABOVE
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH GRAVE
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER C WITH DOT ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER C WITH CIRCUMFLEX
       307   199   C7     ,C     LATIN CAPITAL LETTER C WITH CEDILLA
       310   200   C8     `E     LATIN CAPITAL LETTER E WITH GRAVE
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH CIRCUMFLEX
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER I WITH GRAVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH DIAERESIS
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH TILDE
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH GRAVE
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER G WITH DOT ABOVE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     MULTIPLICATION SIGN
       330   216   D8     /O     LATIN CAPITAL LETTER G WITH CIRCUMFLEX
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH GRAVE
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER U WITH BREVE
       336   222   DE     Ib     LATIN CAPITAL LETTER S WITH CIRCUMFLEX
       337   223   DF     B     LATIN SMALL LETTER SHARP S (German)
       340   224   E0     `a     LATIN SMALL LETTER A WITH GRAVE
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER C WITH DOT ABOVE
       346   230   E6     ae    LATIN SMALL LETTER C WITH CIRCUMFLEX
       347   231   E7     ,c     LATIN SMALL LETTER C WITH CEDILLA
       350   232   E8     `e     LATIN SMALL LETTER E WITH GRAVE
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH CIRCUMFLEX
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER I WITH GRAVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH DIAERESIS
       361   241   F1     ~n     LATIN SMALL LETTER N WITH TILDE
       362   242   F2     `o     LATIN SMALL LETTER O WITH GRAVE
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER G WITH DOT ABOVE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    DIVISION SIGN
       370   248   F8     /o     LATIN SMALL LETTER G WITH CIRCUMFLEX
       371   249   F9     `u     LATIN SMALL LETTER U WITH GRAVE
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE
       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER U WITH BREVE
       376   254   FE     pb     LATIN SMALL LETTER S WITH CIRCUMFLEX
       377   255   FF     "y     DOT ABOVE (Mandarin Chinese light tone)

NOTES top

       ISO 8859-3 is also known as Latin-3.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                       ISO_8859-3(7)


iso_8859-4(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-4(7)                Linux Programmer's Manual               ISO_8859-4(7)

NAME top

       iso_8859-4  - ISO 8859-4 character set encoded in octal, decimal, and hexa-
       decimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-4 encodes the
       characters used in Scandinavian and Baltic languages (Latin-4).

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-4 Characters

       The following table displays the characters in ISO 8859-4, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-4.

       Oct   Dec   Hex   Char   Description
       -----------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LATIN CAPITAL LETTER A WITH OGONEK
       242   162   A2     /c     LATIN SMALL LETTER KRA (Greenlandic)
       243   163   A3     -L     LATIN CAPITAL LETTER R WITH CEDILLA
       244   164   A4     ox     CURRENCY SIGN
       245   165   A5     =Y     LATIN CAPITAL LETTER I WITH TILDE
       246   166   A6     |     LATIN CAPITAL LETTER L WITH CEDILLA
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     DIAERESIS
       251   169   A9    (C)    LATIN CAPITAL LETTER S WITH CARON
       252   170   AA     _a     LATIN CAPITAL LETTER E WITH MACRON
       253   171   AB     <<    LATIN CAPITAL LETTER G WITH CEDILLA
       254   172   AC     ~     LATIN CAPITAL LETTER T WITH STROKE
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    LATIN CAPITAL LETTER Z WITH CARON
       257   175   AF           MACRON
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    LATIN SMALL LETTER A WITH OGONEK
       262   178   B2     2     OGONEK
       263   179   B3     3     LATIN SMALL LETTER R WITH CEDILLA
       264   180   B4     '     ACUTE ACCENT
       265   181   B5     ,u     LATIN SMALL LETTER I WITH TILDE
       266   182   B6     9|    LATIN SMALL LETTER L WITH CEDILLA
       267   183   B7     .     CARON (Mandarin Chinese third tone)
       270   184   B8     ,     CEDILLA
       271   185   B9     1     LATIN SMALL LETTER S WITH CARON

       272   186   BA     _o     LATIN SMALL LETTER E WITH MACRON
       273   187   BB     >>    LATIN SMALL LETTER G WITH CEDILLA
       274   188   BC    1/4    LATIN SMALL LETTER T WITH STROKE
       275   189   BD    1/2    LATIN CAPITAL LETTER ENG (Sami)
       276   190   BE    3/4    LATIN SMALL LETTER Z WITH CARON
       277   191   BF     'c     LATIN SMALL LETTER ENG (Sami)
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH MACRON
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH TILDE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER A WITH RING ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER AE
       307   199   C7     ,C     LATIN CAPITAL LETTER I WITH OGONEK
       310   200   C8     `E     LATIN CAPITAL LETTER C WITH CARON
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH OGONEK
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER E WITH DOT ABOVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH MACRON
       320   208   D0     -D     LATIN CAPITAL LETTER D WITH STROKE
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH CEDILLA
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH MACRON
       323   211   D3     'O     LATIN CAPITAL LETTER K WITH CEDILLA
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH TILDE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     MULTIPLICATION SIGN
       330   216   D8     /O     LATIN CAPITAL LETTER O WITH STROKE
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH OGONEK
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER U WITH TILDE
       336   222   DE     Ib     LATIN CAPITAL LETTER U WITH MACRON
       337   223   DF     B     LATIN SMALL LETTER SHARP S (German)
       340   224   E0     `a     LATIN SMALL LETTER A WITH MACRON
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH TILDE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER A WITH RING ABOVE
       346   230   E6     ae    LATIN SMALL LETTER AE
       347   231   E7     ,c     LATIN SMALL LETTER I WITH OGONEK
       350   232   E8     `e     LATIN SMALL LETTER C WITH CARON
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH OGONEK
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER E WITH DOT ABOVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH MACRON
       360   240   F0     `'o     LATIN SMALL LETTER D WITH STROKE
       361   241   F1     ~n     LATIN SMALL LETTER N WITH CEDILLA
       362   242   F2     `o     LATIN SMALL LETTER O WITH MACRON
       363   243   F3     'o     LATIN SMALL LETTER K WITH CEDILLA
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH TILDE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    DIVISION SIGN
       370   248   F8     /o     LATIN SMALL LETTER O WITH STROKE
       371   249   F9     `u     LATIN SMALL LETTER U WITH OGONEK
       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE

       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER U WITH TILDE
       376   254   FE     pb     LATIN SMALL LETTER U WITH MACRON
       377   255   FF     "y     DOT ABOVE (Mandarin Chinese light tone)

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-01-24                       ISO_8859-4(7)


iso_8859-5(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-5(7)                Linux Programmer's Manual               ISO_8859-5(7)

NAME top

       iso_8859-5  - ISO 8859-5 character set encoded in octal, decimal, and hexa-
       decimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-5 encodes the Cyrillic
       alphabet as used in Russian and Macedonian.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-5 Characters

       The following table displays the characters in ISO 8859-5, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-5.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     CYRILLIC CAPITAL LETTER IO
       242   162   A2     /c     CYRILLIC CAPITAL LETTER DJE (Serbocroatian)
       243   163   A3     -L     CYRILLIC CAPITAL LETTER GJE
       244   164   A4     ox     CYRILLIC CAPITAL LETTER UKRAINIAN IE
       245   165   A5     =Y     CYRILLIC CAPITAL LETTER DZE
       246   166   A6     |     CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I
       247   167   A7     S     CYRILLIC CAPITAL LETTER YI (Ukrainian)
       250   168   A8     "     CYRILLIC CAPITAL LETTER JE
       251   169   A9    (C)    CYRILLIC CAPITAL LETTER LJE
       252   170   AA     _a     CYRILLIC CAPITAL LETTER NJE
       253   171   AB     <<    CYRILLIC CAPITAL LETTER TSHE (Serbocroatian)
       254   172   AC     ~     CYRILLIC CAPITAL LETTER KJE
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    CYRILLIC CAPITAL LETTER SHORT U (Byelorussian)
       257   175   AF           CYRILLIC CAPITAL LETTER DZHE
       260   176   B0     o     CYRILLIC CAPITAL LETTER A
       261   177   B1     +-    CYRILLIC CAPITAL LETTER BE
       262   178   B2     2     CYRILLIC CAPITAL LETTER VE
       263   179   B3     3     CYRILLIC CAPITAL LETTER GHE
       264   180   B4     '     CYRILLIC CAPITAL LETTER DE
       265   181   B5     ,u     CYRILLIC CAPITAL LETTER IE
       266   182   B6     9|    CYRILLIC CAPITAL LETTER ZHE
       267   183   B7     .     CYRILLIC CAPITAL LETTER ZE
       270   184   B8     ,     CYRILLIC CAPITAL LETTER I
       271   185   B9     1     CYRILLIC CAPITAL LETTER SHORT I

       272   186   BA     _o     CYRILLIC CAPITAL LETTER KA
       273   187   BB     >>    CYRILLIC CAPITAL LETTER EL
       274   188   BC    1/4    CYRILLIC CAPITAL LETTER EM
       275   189   BD    1/2    CYRILLIC CAPITAL LETTER EN
       276   190   BE    3/4    CYRILLIC CAPITAL LETTER O
       277   191   BF     'c     CYRILLIC CAPITAL LETTER PE
       300   192   C0     `A     CYRILLIC CAPITAL LETTER ER
       301   193   C1     'A     CYRILLIC CAPITAL LETTER ES
       302   194   C2     ^A     CYRILLIC CAPITAL LETTER TE
       303   195   C3     ~A     CYRILLIC CAPITAL LETTER U
       304   196   C4     "A     CYRILLIC CAPITAL LETTER EF
       305   197   C5     oA     CYRILLIC CAPITAL LETTER HA
       306   198   C6     AE    CYRILLIC CAPITAL LETTER TSE
       307   199   C7     ,C     CYRILLIC CAPITAL LETTER CHE
       310   200   C8     `E     CYRILLIC CAPITAL LETTER SHA
       311   201   C9     'E     CYRILLIC CAPITAL LETTER SHCHA
       312   202   CA     ^E     CYRILLIC CAPITAL LETTER HARD SIGN
       313   203   CB     "E     CYRILLIC CAPITAL LETTER YERU
       314   204   CC     `I     CYRILLIC CAPITAL LETTER SOFT SIGN
       315   205   CD     'I     CYRILLIC CAPITAL LETTER E
       316   206   CE     ^I     CYRILLIC CAPITAL LETTER YU
       317   207   CF     "I     CYRILLIC CAPITAL LETTER YA
       320   208   D0     -D     CYRILLIC SMALL LETTER A
       321   209   D1     ~N     CYRILLIC SMALL LETTER BE
       322   210   D2     `O     CYRILLIC SMALL LETTER VE
       323   211   D3     'O     CYRILLIC SMALL LETTER GHE
       324   212   D4     ^O     CYRILLIC SMALL LETTER DE
       325   213   D5     ~O     CYRILLIC SMALL LETTER IE
       326   214   D6     "O     CYRILLIC SMALL LETTER ZHE
       327   215   D7     x     CYRILLIC SMALL LETTER ZE
       330   216   D8     /O     CYRILLIC SMALL LETTER I
       331   217   D9     `U     CYRILLIC SMALL LETTER SHORT I
       332   218   DA     'U     CYRILLIC SMALL LETTER KA
       333   219   DB     ^U     CYRILLIC SMALL LETTER EL
       334   220   DC     "U     CYRILLIC SMALL LETTER EM
       335   221   DD     'Y     CYRILLIC SMALL LETTER EN
       336   222   DE     Ib     CYRILLIC SMALL LETTER O
       337   223   DF     B     CYRILLIC SMALL LETTER PE
       340   224   E0     `a     CYRILLIC SMALL LETTER ER
       341   225   E1     'a     CYRILLIC SMALL LETTER ES
       342   226   E2     ^a     CYRILLIC SMALL LETTER TE
       343   227   E3     ~a     CYRILLIC SMALL LETTER U
       344   228   E4     "a     CYRILLIC SMALL LETTER EF
       345   229   E5     oa     CYRILLIC SMALL LETTER HA
       346   230   E6     ae    CYRILLIC SMALL LETTER TSE
       347   231   E7     ,c     CYRILLIC SMALL LETTER CHE
       350   232   E8     `e     CYRILLIC SMALL LETTER SHA
       351   233   E9     'e     CYRILLIC SMALL LETTER SHCHA
       352   234   EA     ^e     CYRILLIC SMALL LETTER HARD SIGN
       353   235   EB     "e     CYRILLIC SMALL LETTER YERU
       354   236   EC     `i     CYRILLIC SMALL LETTER SOFT SIGN
       355   237   ED     'i     CYRILLIC SMALL LETTER E
       356   238   EE     ^i     CYRILLIC SMALL LETTER YU
       357   239   EF     "i     CYRILLIC SMALL LETTER YA
       360   240   F0     `'o     NUMERO SIGN
       361   241   F1     ~n     CYRILLIC SMALL LETTER IO
       362   242   F2     `o     CYRILLIC SMALL LETTER DJE (Serbocroatian)
       363   243   F3     'o     CYRILLIC SMALL LETTER GJE
       364   244   F4     ^o     CYRILLIC SMALL LETTER UKRAINIAN IE
       365   245   F5     ~o     CYRILLIC SMALL LETTER DZE
       366   246   F6     "o     CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I
       367   247   F7    -:-    CYRILLIC SMALL LETTER YI (Ukrainian)
       370   248   F8     /o     CYRILLIC SMALL LETTER JE
       371   249   F9     `u     CYRILLIC SMALL LETTER LJE
       372   250   FA     'u     CYRILLIC SMALL LETTER NJE

       373   251   FB     /o     CYRILLIC SMALL LETTER TSHE (Serbocroatian)
       374   252   FC     "u     CYRILLIC SMALL LETTER KJE
       375   253   FD     'y     SECTION SIGN
       376   254   FE     pb     CYRILLIC SMALL LETTER SHORT U (Byelorussian)
       377   255   FF     "y     CYRILLIC SMALL LETTER DZHE

SEE ALSO top

       ascii(7), koi8-r(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                       ISO_8859-5(7)


iso_8859-6(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-6(7)                Linux Programmer's Manual               ISO_8859-6(7)

NAME top

       iso_8859-6  - ISO 8859-6 character set encoded in octal, decimal, and hexa-
       decimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-6 encodes the
       characters used in the Arabic language.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-6 Characters

       The following table displays the characters in ISO 8859-6, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-6.

       Oct   Dec   Hex   Char   Description
       -------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       244   164   A4     ox     CURRENCY SIGN
       254   172   AC     ~     ARABIC COMMA
       255   173   AD           SOFT HYPHEN
       273   187   BB     >>    ARABIC SEMICOLON
       277   191   BF     'c     ARABIC QUESTION MARK
       301   193   C1     'A     ARABIC LETTER HAMZA
       302   194   C2     ^A     ARABIC LETTER ALEF WITH MADDA ABOVE
       303   195   C3     ~A     ARABIC LETTER ALEF WITH HAMZA ABOVE
       304   196   C4     "A     ARABIC LETTER WAW WITH HAMZA ABOVE
       305   197   C5     oA     ARABIC LETTER ALEF WITH HAMZA BELOW
       306   198   C6     AE    ARABIC LETTER YEH WITH HAMZA ABOVE
       307   199   C7     ,C     ARABIC LETTER ALEF
       310   200   C8     `E     ARABIC LETTER BEH
       311   201   C9     'E     ARABIC LETTER TEH MARBUTA
       312   202   CA     ^E     ARABIC LETTER TEH
       313   203   CB     "E     ARABIC LETTER THEH
       314   204   CC     `I     ARABIC LETTER JEEM
       315   205   CD     'I     ARABIC LETTER HAH
       316   206   CE     ^I     ARABIC LETTER KHAH
       317   207   CF     "I     ARABIC LETTER DAL
       320   208   D0     -D     ARABIC LETTER THAL
       321   209   D1     ~N     ARABIC LETTER REH
       322   210   D2     `O     ARABIC LETTER ZAIN
       323   211   D3     'O     ARABIC LETTER SEEN
       324   212   D4     ^O     ARABIC LETTER SHEEN

       325   213   D5     ~O     ARABIC LETTER SAD
       326   214   D6     "O     ARABIC LETTER DAD
       327   215   D7     x     ARABIC LETTER TAH
       330   216   D8     /O     ARABIC LETTER ZAH
       331   217   D9     `U     ARABIC LETTER AIN
       332   218   DA     'U     ARABIC LETTER GHAIN
       340   224   E0     `a     ARABIC TATWEEL
       341   225   E1     'a     ARABIC LETTER FEH
       342   226   E2     ^a     ARABIC LETTER QAF
       343   227   E3     ~a     ARABIC LETTER KAF
       344   228   E4     "a     ARABIC LETTER LAM
       345   229   E5     oa     ARABIC LETTER MEEM
       346   230   E6     ae    ARABIC LETTER NOON
       347   231   E7     ,c     ARABIC LETTER HEH
       350   232   E8     `e     ARABIC LETTER WAW
       351   233   E9     'e     ARABIC LETTER ALEF MAKSURA
       352   234   EA     ^e     ARABIC LETTER YEH
       353   235   EB     "e     ARABIC FATHATAN
       354   236   EC     `i     ARABIC DAMMATAN
       355   237   ED     'i     ARABIC KASRATAN
       356   238   EE     ^i     ARABIC FATHA
       357   239   EF     "i     ARABIC DAMMA
       360   240   F0     `'o     ARABIC KASRA
       361   241   F1     ~n     ARABIC SHADDA
       362   242   F2     `o     ARABIC SUKUN

NOTES top

       ISO 8859-6 lacks the glyphs required for many related languages, such as
       Urdu and Persian (Farsi).

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                       ISO_8859-6(7)


iso_8859-7(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-7(7)                Linux Programmer's Manual               ISO_8859-7(7)

NAME top

       iso_8859-7  -  ISO  8859-7  character  set  encoded  in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-7 encodes the
       characters used in modern monotonic Greek.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-7 Characters

       The following table displays the characters in ISO 8859-7, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-7.

       Oct   Dec   Hex   Char   Description
       -----------------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     LEFT SINGLE QUOTATION MARK
       242   162   A2     /c     RIGHT SINGLE QUOTATION MARK
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     EURO SIGN
       245   165   A5     =Y     DRACHMA SIGN
       246   166   A6     |     BROKEN BAR
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     DIAERESIS
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     GREEK YPOGEGRAMMENI
       253   171   AB     <<    LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254   172   AC     ~     NOT SIGN
       255   173   AD     _     SOFT HYPHEN
       257   175   AF           HORIZONTAL BAR
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    PLUS-MINUS SIGN
       262   178   B2     2     SUPERSCRIPT TWO
       263   179   B3     3     SUPERSCRIPT THREE
       264   180   B4     '     GREEK TONOS
       265   181   B5     ,u     GREEK DIALYTIKA TONOS
       266   182   B6     9|    GREEK CAPITAL LETTER ALPHA WITH TONOS
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     GREEK CAPITAL LETTER EPSILON WITH TONOS
       271   185   B9     1     GREEK CAPITAL LETTER ETA WITH TONOS
       272   186   BA     _o     GREEK CAPITAL LETTER IOTA WITH TONOS

       273   187   BB     >>    RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274   188   BC    1/4    GREEK CAPITAL LETTER OMICRON WITH TONOS
       275   189   BD    1/2    VULGAR FRACTION ONE HALF
       276   190   BE    3/4    GREEK CAPITAL LETTER UPSILON WITH TONOS
       277   191   BF     'c     GREEK CAPITAL LETTER OMEGA WITH TONOS
       300   192   C0     `A     GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS
       301   193   C1     'A     GREEK CAPITAL LETTER ALPHA
       302   194   C2     ^A     GREEK CAPITAL LETTER BETA
       303   195   C3     ~A     GREEK CAPITAL LETTER GAMMA
       304   196   C4     "A     GREEK CAPITAL LETTER DELTA
       305   197   C5     oA     GREEK CAPITAL LETTER EPSILON
       306   198   C6     AE    GREEK CAPITAL LETTER ZETA
       307   199   C7     ,C     GREEK CAPITAL LETTER ETA
       310   200   C8     `E     GREEK CAPITAL LETTER THETA
       311   201   C9     'E     GREEK CAPITAL LETTER IOTA
       312   202   CA     ^E     GREEK CAPITAL LETTER KAPPA
       313   203   CB     "E     GREEK CAPITAL LETTER LAMBDA
       314   204   CC     `I     GREEK CAPITAL LETTER MU
       315   205   CD     'I     GREEK CAPITAL LETTER NU
       316   206   CE     ^I     GREEK CAPITAL LETTER XI
       317   207   CF     "I     GREEK CAPITAL LETTER OMICRON
       320   208   D0     -D     GREEK CAPITAL LETTER PI
       321   209   D1     ~N     GREEK CAPITAL LETTER RHO
       323   211   D3     'O     GREEK CAPITAL LETTER SIGMA
       324   212   D4     ^O     GREEK CAPITAL LETTER TAU
       325   213   D5     ~O     GREEK CAPITAL LETTER UPSILON
       326   214   D6     "O     GREEK CAPITAL LETTER PHI
       327   215   D7     x     GREEK CAPITAL LETTER CHI
       330   216   D8     /O     GREEK CAPITAL LETTER PSI
       331   217   D9     `U     GREEK CAPITAL LETTER OMEGA
       332   218   DA     'U     GREEK CAPITAL LETTER IOTA WITH DIALYTIKA
       333   219   DB     ^U     GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA
       334   220   DC     "U     GREEK SMALL LETTER ALPHA WITH TONOS
       335   221   DD     'Y     GREEK SMALL LETTER EPSILON WITH TONOS
       336   222   DE     Ib     GREEK SMALL LETTER ETA WITH TONOS
       337   223   DF     B     GREEK SMALL LETTER IOTA WITH TONOS
       340   224   E0     `a     GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS
       341   225   E1     'a     GREEK SMALL LETTER ALPHA
       342   226   E2     ^a     GREEK SMALL LETTER BETA
       343   227   E3     ~a     GREEK SMALL LETTER GAMMA
       344   228   E4     "a     GREEK SMALL LETTER DELTA
       345   229   E5     oa     GREEK SMALL LETTER EPSILON
       346   230   E6     ae    GREEK SMALL LETTER ZETA
       347   231   E7     ,c     GREEK SMALL LETTER ETA
       350   232   E8     `e     GREEK SMALL LETTER THETA
       351   233   E9     'e     GREEK SMALL LETTER IOTA
       352   234   EA     ^e     GREEK SMALL LETTER KAPPA
       353   235   EB     "e     GREEK SMALL LETTER LAMBDA
       354   236   EC     `i     GREEK SMALL LETTER MU
       355   237   ED     'i     GREEK SMALL LETTER NU
       356   238   EE     ^i     GREEK SMALL LETTER XI
       357   239   EF     "i     GREEK SMALL LETTER OMICRON
       360   240   F0     `'o     GREEK SMALL LETTER PI
       361   241   F1     ~n     GREEK SMALL LETTER RHO
       362   242   F2     `o     GREEK SMALL LETTER FINAL SIGMA
       363   243   F3     'o     GREEK SMALL LETTER SIGMA
       364   244   F4     ^o     GREEK SMALL LETTER TAU
       365   245   F5     ~o     GREEK SMALL LETTER UPSILON
       366   246   F6     "o     GREEK SMALL LETTER PHI
       367   247   F7    -:-    GREEK SMALL LETTER CHI
       370   248   F8     /o     GREEK SMALL LETTER PSI
       371   249   F9     `u     GREEK SMALL LETTER OMEGA
       372   250   FA     'u     GREEK SMALL LETTER IOTA WITH DIALYTIKA
       373   251   FB     ^u     GREEK SMALL LETTER UPSILON WITH DIALYTIKA
       374   252   FC     "u     GREEK SMALL LETTER OMICRON WITH TONOS

       375   253   FD     'y     GREEK SMALL LETTER UPSILON WITH TONOS
       376   254   FE     pb     GREEK SMALL LETTER OMEGA WITH TONOS

NOTES top

       ISO 8859-7 was formerly known as ELOT-928 or ECMA-118:1986.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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-10-30                       ISO_8859-7(7)


iso_8859-8(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-8(7)                Linux Programmer's Manual               ISO_8859-8(7)

NAME top

       iso_8859-8  - ISO 8859-8 character set encoded in octal, decimal, and hexa-
       decimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-8, or "ISO Hebrew"
       encodes the characters used in Modern Hebrew (or Ivrit).  Neither short
       vowels nor diacritical marks are included, and Yiddish is not provided for.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-8 Characters

       The following table displays the characters in ISO 8859-8, which are
       printable and unlisted in the ascii(7) manual page.  The fourth column will
       only show the proper glyphs in an environment configured for ISO 8859-8.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       242   162   A2     /c     CENT SIGN
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     CURRENCY SIGN
       245   165   A5     =Y     YEN SIGN
       246   166   A6     |     BROKEN BAR
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     DIAERESIS
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     MULTIPLICATION SIGN
       253   171   AB     <<    LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254   172   AC     ~     NOT SIGN
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    REGISTERED SIGN
       257   175   AF           MACRON
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    PLUS-MINUS SIGN
       262   178   B2     2     SUPERSCRIPT TWO
       263   179   B3     3     SUPERSCRIPT THREE
       264   180   B4     '     ACUTE ACCENT
       265   181   B5     ,u     MICRO SIGN
       266   182   B6     9|    PILCROW SIGN
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     CEDILLA
       271   185   B9     1     SUPERSCRIPT ONE

       272   186   BA     _o     DIVISION SIGN
       273   187   BB     >>    RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274   188   BC    1/4    VULGAR FRACTION ONE QUARTER
       275   189   BD    1/2    VULGAR FRACTION ONE HALF
       276   190   BE    3/4    VULGAR FRACTION THREE QUARTERS
       337   223   DF     B     DOUBLE LOW LINE
       340   224   E0     `a     HEBREW LETTER ALEF
       341   225   E1     'a     HEBREW LETTER BET
       342   226   E2     ^a     HEBREW LETTER GIMEL
       343   227   E3     ~a     HEBREW LETTER DALET
       344   228   E4     "a     HEBREW LETTER HE
       345   229   E5     oa     HEBREW LETTER VAV
       346   230   E6     ae    HEBREW LETTER ZAYIN
       347   231   E7     ,c     HEBREW LETTER HET
       350   232   E8     `e     HEBREW LETTER TET
       351   233   E9     'e     HEBREW LETTER YOD
       352   234   EA     ^e     HEBREW LETTER FINAL KAF
       353   235   EB     "e     HEBREW LETTER KAF
       354   236   EC     `i     HEBREW LETTER LAMED
       355   237   ED     'i     HEBREW LETTER FINAL MEM
       356   238   EE     ^i     HEBREW LETTER MEM
       357   239   EF     "i     HEBREW LETTER FINAL NUN
       360   240   F0     `'o     HEBREW LETTER NUN
       361   241   F1     ~n     HEBREW LETTER SAMEKH
       362   242   F2     `o     HEBREW LETTER AYIN
       363   243   F3     'o     HEBREW LETTER FINAL PE
       364   244   F4     ^o     HEBREW LETTER PE
       365   245   F5     ~o     HEBREW LETTER FINAL TSADI
       366   246   F6     "o     HEBREW LETTER TSADI
       367   247   F7    -:-    HEBREW LETTER QOF
       370   248   F8     /o     HEBREW LETTER RESH
       371   249   F9     `u     HEBREW LETTER SHIN
       372   250   FA     'u     HEBREW LETTER TAV
       375   253   FD     'y     LEFT-TO-RIGHT MARK
       376   254   FE     pb     RIGHT-TO-LEFT MARK

NOTES top

       ISO 8859-8 was also known as ISO-IR-138.

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                       ISO_8859-8(7)


iso_8859-9(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ISO_8859-9(7)                Linux Programmer's Manual               ISO_8859-9(7)

NAME top

       iso_8859-9  -  ISO  8859-9  character  set  encoded  in octal, decimal, and
       hexadecimal

DESCRIPTION top

       The ISO 8859 standard includes several 8-bit extensions to the ASCII
       character set (also known as ISO 646-IRV).  ISO 8859-9, also known as the
       "Latin Alphabet No. 5", encodes the characters used in Turkish.

ISO 8859 Alphabets

       The full set of ISO 8859 alphabets includes:

       ISO 8859-1    West European languages (Latin-1)
       ISO 8859-2    Central and East European languages (Latin-2)
       ISO 8859-3    Southeast European and miscellaneous languages (Latin-3)
       ISO 8859-4    Scandinavian/Baltic languages (Latin-4)
       ISO 8859-5    Latin/Cyrillic
       ISO 8859-6    Latin/Arabic
       ISO 8859-7    Latin/Greek
       ISO 8859-8    Latin/Hebrew
       ISO 8859-9    Latin-1 modification for Turkish (Latin-5)
       ISO 8859-10   Lappish/Nordic/Eskimo languages (Latin-6)
       ISO 8859-11   Latin/Thai
       ISO 8859-13   Baltic Rim languages (Latin-7)
       ISO 8859-14   Celtic (Latin-8)
       ISO 8859-15   West European languages (Latin-9)
       ISO 8859-16   Romanian (Latin-10)

ISO 8859-9 Characters

       The following table displays the characters in ISO 8859-9 (Latin-5), which
       are printable and unlisted in the ascii(7) manual page.  The fourth column
       will only show the proper glyphs in an environment configured for ISO
       8859-9.

       Oct   Dec   Hex   Char   Description
       --------------------------------------------------------------------
       240   160   A0           NO-BREAK SPACE
       241   161   A1     ,i     INVERTED EXCLAMATION MARK
       242   162   A2     /c     CENT SIGN
       243   163   A3     -L     POUND SIGN
       244   164   A4     ox     CURRENCY SIGN
       245   165   A5     =Y     YEN SIGN
       246   166   A6     |     BROKEN BAR
       247   167   A7     S     SECTION SIGN
       250   168   A8     "     DIAERESIS
       251   169   A9    (C)    COPYRIGHT SIGN
       252   170   AA     _a     FEMININE ORDINAL INDICATOR
       253   171   AB     <<    LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
       254   172   AC     ~     NOT SIGN
       255   173   AD           SOFT HYPHEN
       256   174   AE    (R_)    REGISTERED SIGN
       257   175   AF           MACRON
       260   176   B0     o     DEGREE SIGN
       261   177   B1     +-    PLUS-MINUS SIGN
       262   178   B2     2     SUPERSCRIPT TWO
       263   179   B3     3     SUPERSCRIPT THREE
       264   180   B4     '     ACUTE ACCENT
       265   181   B5     ,u     MICRO SIGN
       266   182   B6     9|    PILCROW SIGN
       267   183   B7     .     MIDDLE DOT
       270   184   B8     ,     CEDILLA

       271   185   B9     1     SUPERSCRIPT ONE
       272   186   BA     _o     MASCULINE ORDINAL INDICATOR
       273   187   BB     >>    RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
       274   188   BC    1/4    VULGAR FRACTION ONE QUARTER
       275   189   BD    1/2    VULGAR FRACTION ONE HALF
       276   190   BE    3/4    VULGAR FRACTION THREE QUARTERS
       277   191   BF     'c     INVERTED QUESTION MARK
       300   192   C0     `A     LATIN CAPITAL LETTER A WITH GRAVE
       301   193   C1     'A     LATIN CAPITAL LETTER A WITH ACUTE
       302   194   C2     ^A     LATIN CAPITAL LETTER A WITH CIRCUMFLEX
       303   195   C3     ~A     LATIN CAPITAL LETTER A WITH TILDE
       304   196   C4     "A     LATIN CAPITAL LETTER A WITH DIAERESIS
       305   197   C5     oA     LATIN CAPITAL LETTER A WITH RING ABOVE
       306   198   C6     AE    LATIN CAPITAL LETTER AE
       307   199   C7     ,C     LATIN CAPITAL LETTER C WITH CEDILLA
       310   200   C8     `E     LATIN CAPITAL LETTER E WITH GRAVE
       311   201   C9     'E     LATIN CAPITAL LETTER E WITH ACUTE
       312   202   CA     ^E     LATIN CAPITAL LETTER E WITH CIRCUMFLEX
       313   203   CB     "E     LATIN CAPITAL LETTER E WITH DIAERESIS
       314   204   CC     `I     LATIN CAPITAL LETTER I WITH GRAVE
       315   205   CD     'I     LATIN CAPITAL LETTER I WITH ACUTE
       316   206   CE     ^I     LATIN CAPITAL LETTER I WITH CIRCUMFLEX
       317   207   CF     "I     LATIN CAPITAL LETTER I WITH DIAERESIS
       320   208   D0     -D     LATIN CAPITAL LETTER G WITH BREVE
       321   209   D1     ~N     LATIN CAPITAL LETTER N WITH TILDE
       322   210   D2     `O     LATIN CAPITAL LETTER O WITH GRAVE
       323   211   D3     'O     LATIN CAPITAL LETTER O WITH ACUTE
       324   212   D4     ^O     LATIN CAPITAL LETTER O WITH CIRCUMFLEX
       325   213   D5     ~O     LATIN CAPITAL LETTER O WITH TILDE
       326   214   D6     "O     LATIN CAPITAL LETTER O WITH DIAERESIS
       327   215   D7     x     MULTIPLICATION SIGN
       330   216   D8     /O     LATIN CAPITAL LETTER O WITH STROKE
       331   217   D9     `U     LATIN CAPITAL LETTER U WITH GRAVE
       332   218   DA     'U     LATIN CAPITAL LETTER U WITH ACUTE
       333   219   DB     ^U     LATIN CAPITAL LETTER U WITH CIRCUMFLEX
       334   220   DC     "U     LATIN CAPITAL LETTER U WITH DIAERESIS
       335   221   DD     'Y     LATIN CAPITAL LETTER I WITH DOT ABOVE
       336   222   DE     Ib     LATIN CAPITAL LETTER S WITH CEDILLA
       337   223   DF     B     LATIN SMALL LETTER SHARP S
       340   224   E0     `a     LATIN SMALL LETTER A WITH GRAVE
       341   225   E1     'a     LATIN SMALL LETTER A WITH ACUTE
       342   226   E2     ^a     LATIN SMALL LETTER A WITH CIRCUMFLEX
       343   227   E3     ~a     LATIN SMALL LETTER A WITH TILDE
       344   228   E4     "a     LATIN SMALL LETTER A WITH DIAERESIS
       345   229   E5     oa     LATIN SMALL LETTER A WITH RING ABOVE
       346   230   E6     ae    LATIN SMALL LETTER AE
       347   231   E7     ,c     LATIN SMALL LETTER C WITH CEDILLA
       350   232   E8     `e     LATIN SMALL LETTER E WITH GRAVE
       351   233   E9     'e     LATIN SMALL LETTER E WITH ACUTE
       352   234   EA     ^e     LATIN SMALL LETTER E WITH CIRCUMFLEX
       353   235   EB     "e     LATIN SMALL LETTER E WITH DIAERESIS
       354   236   EC     `i     LATIN SMALL LETTER I WITH GRAVE
       355   237   ED     'i     LATIN SMALL LETTER I WITH ACUTE
       356   238   EE     ^i     LATIN SMALL LETTER I WITH CIRCUMFLEX
       357   239   EF     "i     LATIN SMALL LETTER I WITH DIAERESIS
       360   240   F0     `'o     LATIN SMALL LETTER G WITH BREVE
       361   241   F1     ~n     LATIN SMALL LETTER N WITH TILDE
       362   242   F2     `o     LATIN SMALL LETTER O WITH GRAVE
       363   243   F3     'o     LATIN SMALL LETTER O WITH ACUTE
       364   244   F4     ^o     LATIN SMALL LETTER O WITH CIRCUMFLEX
       365   245   F5     ~o     LATIN SMALL LETTER O WITH TILDE
       366   246   F6     "o     LATIN SMALL LETTER O WITH DIAERESIS
       367   247   F7    -:-    DIVISION SIGN
       370   248   F8     /o     LATIN SMALL LETTER O WITH STROKE
       371   249   F9     `u     LATIN SMALL LETTER U WITH GRAVE

       372   250   FA     'u     LATIN SMALL LETTER U WITH ACUTE
       373   251   FB     ^u     LATIN SMALL LETTER U WITH CIRCUMFLEX
       374   252   FC     "u     LATIN SMALL LETTER U WITH DIAERESIS
       375   253   FD     'y     LATIN SMALL LETTER DOTLESS I
       376   254   FE     pb     LATIN SMALL LETTER S WITH CEDILLA
       377   255   FF     "y     LATIN SMALL LETTER Y WITH DIAERESIS

SEE ALSO top

       ascii(7)

COLOPHON top

       This page is part of release 3.45 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-09-24                       ISO_8859-9(7)


issue(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

ISSUE(5)                     Linux Programmer's Manual                    ISSUE(5)

NAME top

       issue - prelogin message and identification file

DESCRIPTION top

       The file /etc/issue is a text file which contains a message or system
       identification to be printed before the login prompt.  It may contain
       various @char and \char sequences, if supported by the getty-type program
       employed on the system.

FILES top

       /etc/issue

SEE ALSO top

       motd(5), agetty(8), mingetty(8)

COLOPHON top

       This page is part of release 3.45 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                               1993-07-24                            ISSUE(5)


iswalnum(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWALNUM(3)                  Linux Programmer's Manual                 ISWALNUM(3)

NAME top

       iswalnum - test for alphanumeric wide character

SYNOPSIS top

       #include <wctype.h>

       int iswalnum(wint_t wc);

DESCRIPTION top

       The iswalnum() function is the wide-character equivalent of the isalnum(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "alnum".

       The wide-character class "alnum" is a subclass of the wide-character class
       "graph", and therefore also a subclass of the wide-character class "print".

       Being a subclass of the wide-character class "print", the wide-character
       class "alnum" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "alnum" is disjoint from the wide-character class "space" and its
       subclass "blank".

       The wide-character class "alnum" is disjoint from the wide-character class
       "punct".

       The wide-character class "alnum" is the union of the wide-character classes
       "alpha" and "digit".  As such, it also contains the wide-character class
       "xdigit".

       The wide-character class "alnum" always contains at least the letters 'A'
       to 'Z', 'a' to 'z' and the digits '0' to '9'.

RETURN VALUE top

       The iswalnum() function returns nonzero if wc is a wide character belonging
       to the wide-character class "alnum".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswalnum() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isalnum(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWALNUM(3)


iswalpha(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWALPHA(3)                  Linux Programmer's Manual                 ISWALPHA(3)

NAME top

       iswalpha - test for alphabetic wide character

SYNOPSIS top

       #include <wctype.h>

       int iswalpha(wint_t wc);

DESCRIPTION top

       The iswalpha() function is the wide-character equivalent of the isalpha(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "alpha".

       The wide-character class "alpha" is a subclass of the wide-character class
       "alnum", and therefore also a subclass of the wide-character class "graph"
       and of the wide-character class "print".

       Being a subclass of the wide-character class "print", the wide-character
       class "alpha" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "alpha" is disjoint from the wide-character class "space" and its
       subclass "blank".

       Being a subclass of the wide-character class "alnum", the wide-character
       class "alpha" is disjoint from the wide-character class "punct".

       The wide-character class "alpha" is disjoint from the wide-character class
       "digit".

       The wide-character class "alpha" contains the wide-character classes
       "upper" and "lower".

       The wide-character class "alpha" always contains at least the letters 'A'
       to 'Z' and 'a' to 'z'.

RETURN VALUE top

       The iswalpha() function returns nonzero if wc is a wide character belonging
       to the wide-character class "alpha".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswalpha() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isalpha(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWALPHA(3)


iswblank(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWBLANK(3)                  Linux Programmer's Manual                 ISWBLANK(3)

NAME top

       iswblank - test for whitespace wide character

SYNOPSIS top

       #include <wctype.h>

       int iswblank(wint_t wc);

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

       iswblank():
              _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
              _POSIX_C_SOURCE >= 200112L;
              or cc -std=c99

DESCRIPTION top

       The iswblank() function is the wide-character equivalent of the isblank(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "blank".

       The wide-character class "blank" is a subclass of the wide-character class
       "space".

       Being a subclass of the wide-character class "space", the wide-character
       class "blank" is disjoint from the wide-character class "graph" and
       therefore also disjoint from its subclasses "alnum", "alpha", "upper",
       "lower", "digit", "xdigit", "punct".

       The wide-character class "blank" always contains at least the space
       character and the control character '\t'.

RETURN VALUE top

       The iswblank() function returns nonzero if wc is a wide character belonging
       to the wide-character class "blank".  Otherwise it returns zero.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The behavior of iswblank() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isblank(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                         ISWBLANK(3)


iswcntrl(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWCNTRL(3)                  Linux Programmer's Manual                 ISWCNTRL(3)

NAME top

       iswcntrl - test for control wide character

SYNOPSIS top

       #include <wctype.h>

       int iswcntrl(wint_t wc);

DESCRIPTION top

       The iswcntrl() function is the wide-character equivalent of the iscntrl(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "cntrl".

       The wide-character class "cntrl" is disjoint from the wide-character class
       "print" and therefore also disjoint from its subclasses "graph", "alpha",
       "upper", "lower", "digit", "xdigit", "punct".

       For an unsigned char c, iscntrl(c) implies iswcntrl(btowc(c)), but not vice
       versa.

RETURN VALUE top

       The iswcntrl() function returns nonzero if wc is a wide character belonging
       to the wide-character class "cntrl".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswcntrl() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       iscntrl(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWCNTRL(3)


iswctype(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWCTYPE(3)                  Linux Programmer's Manual                 ISWCTYPE(3)

NAME top

       iswctype - wide-character classification

SYNOPSIS top

       #include <wctype.h>

       int iswctype(wint_t wc, wctype_t desc);

DESCRIPTION top

       If wc is a wide character having the character property designated by desc
       (or in other words: belongs to the character class designated by desc), the
       iswctype() function returns nonzero.  Otherwise it returns zero.  If wc is
       WEOF, zero is returned.

       desc must be a character property descriptor returned by the wctype(3)
       function.

RETURN VALUE top

       The iswctype() function returns nonzero if the wc has the designated
       property.  Otherwise it returns 0.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswctype() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       iswalnum(3), iswalpha(3), iswblank(3), iswcntrl(3), iswdigit(3),
       iswgraph(3), iswlower(3), iswprint(3), iswpunct(3), iswspace(3),
       iswupper(3), iswxdigit(3), wctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWCTYPE(3)


iswdigit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWDIGIT(3)                  Linux Programmer's Manual                 ISWDIGIT(3)

NAME top

       iswdigit - test for decimal digit wide character

SYNOPSIS top

       #include <wctype.h>

       int iswdigit(wint_t wc);

DESCRIPTION top

       The iswdigit() function is the wide-character equivalent of the isdigit(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "digit".

       The wide-character class "digit" is a subclass of the wide-character class
       "xdigit", and therefore also a subclass of the wide-character class
       "alnum", of the wide-character class "graph" and of the wide-character
       class "print".

       Being a subclass of the wide character class "print", the wide-character
       class "digit" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "digit" is disjoint from the wide-character class "space" and its
       subclass "blank".

       Being a subclass of the wide-character class "alnum", the wide-character
       class "digit" is disjoint from the wide-character class "punct".

       The wide-character class "digit" is disjoint from the wide-character class
       "alpha" and therefore also disjoint from its subclasses "lower", "upper".

       The wide-character class "digit" always contains exactly the digits '0' to
       '9'.

RETURN VALUE top

       The iswdigit() function returns nonzero if wc is a wide character belonging
       to the wide-character class "digit".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswdigit() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isdigit(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWDIGIT(3)


iswgraph(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWGRAPH(3)                  Linux Programmer's Manual                 ISWGRAPH(3)

NAME top

       iswgraph - test for graphic wide character

SYNOPSIS top

       #include <wctype.h>

       int iswgraph(wint_t wc);

DESCRIPTION top

       The iswgraph() function is the wide-character equivalent of the isgraph(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "graph".

       The wide-character class "graph" is a subclass of the wide-character class
       "print".

       Being a subclass of the wide-character class "print", the wide-character
       class "graph" is disjoint from the wide-character class "cntrl".

       The wide-character class "graph" is disjoint from the wide-character class
       "space" and therefore also disjoint from its subclass "blank".

       The wide-character class "graph" contains all the wide characters from the
       wide-character class "print" except the space character.  It therefore
       contains the wide-character classes "alnum" and "punct".

RETURN VALUE top

       The iswgraph() function returns nonzero if wc is a wide character belonging
       to the wide-character class "graph".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswgraph() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isgraph(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWGRAPH(3)


iswlower(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWLOWER(3)                  Linux Programmer's Manual                 ISWLOWER(3)

NAME top

       iswlower - test for lowercase wide character

SYNOPSIS top

       #include <wctype.h>

       int iswlower(wint_t wc);

DESCRIPTION top

       The iswlower() function is the wide-character equivalent of the islower(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "lower".

       The wide-character class "lower" is a subclass of the wide-character class
       "alpha", and therefore also a subclass of the wide-character class "alnum",
       of the wide-character class "graph" and of the wide-character class
       "print".

       Being a subclass of the wide-character class "print", the wide-character
       class "lower" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "lower" is disjoint from the wide-character class "space" and its
       subclass "blank".

       Being a subclass of the wide-character class "alnum", the wide-character
       class "lower" is disjoint from the wide-character class "punct".

       Being a subclass of the wide-character class "alpha", the wide-character
       class "lower" is disjoint from the wide-character class "digit".

       The wide-character class "lower" contains at least those characters wc
       which are equal to towlower(wc) and different from towupper(wc).

       The wide-character class "lower" always contains at least the letters 'a'
       to 'z'.

RETURN VALUE top

       The iswlower() function returns nonzero if wc is a wide character belonging
       to the wide-character class "lower".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswlower() depends on the LC_CTYPE category of the current
       locale.

       This function is not very appropriate for dealing with Unicode characters,
       because Unicode knows about three cases: upper, lower and title case.

SEE ALSO top

       islower(3), iswctype(3), towlower(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWLOWER(3)


iswprint(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWPRINT(3)                  Linux Programmer's Manual                 ISWPRINT(3)

NAME top

       iswprint - test for printing wide character

SYNOPSIS top

       #include <wctype.h>

       int iswprint(wint_t wc);

DESCRIPTION top

       The iswprint() function is the wide-character equivalent of the isprint(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "print".

       The wide-character class "print" is disjoint from the wide-character class
       "cntrl".

       The wide-character class "print" contains the wide-character class "graph".

RETURN VALUE top

       The iswprint() function returns nonzero if wc is a wide character belonging
       to the wide-character class "print".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswprint() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isprint(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWPRINT(3)


iswpunct(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWPUNCT(3)                  Linux Programmer's Manual                 ISWPUNCT(3)

NAME top

       iswpunct - test for punctuation or symbolic wide character

SYNOPSIS top

       #include <wctype.h>

       int iswpunct(wint_t wc);

DESCRIPTION top

       The iswpunct() function is the wide-character equivalent of the ispunct(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "punct".

       The wide-character class "punct" is a subclass of the wide-character class
       "graph", and therefore also a subclass of the wide-character class "print".

       The wide-character class "punct" is disjoint from the wide-character class
       "alnum" and therefore also disjoint from its subclasses "alpha", "upper",
       "lower", "digit", "xdigit".

       Being a subclass of the wide-character class "print", the wide-character
       class "punct" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "punct" is disjoint from the wide-character class "space" and its
       subclass "blank".

RETURN VALUE top

       The iswpunct() function returns nonzero if wc is a wide-character belonging
       to the wide-character class "punct".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswpunct() depends on the LC_CTYPE category of the current
       locale.

       This function's name is a misnomer when dealing with Unicode characters,
       because the wide-character class "punct" contains both punctuation
       characters and symbol (math, currency, etc.) characters.

SEE ALSO top

       ispunct(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWPUNCT(3)


iswspace(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWSPACE(3)                  Linux Programmer's Manual                 ISWSPACE(3)

NAME top

       iswspace - test for whitespace wide character

SYNOPSIS top

       #include <wctype.h>

       int iswspace(wint_t wc);

DESCRIPTION top

       The iswspace() function is the wide-character equivalent of the isspace(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "space".

       The wide-character class "space" is disjoint from the wide-character class
       "graph" and therefore also disjoint from its subclasses "alnum", "alpha",
       "upper", "lower", "digit", "xdigit", "punct".

       The wide-character class "space" contains the wide-character class "blank".

       The wide-character class "space" always contains at least the space
       character and the control characters '\f', '\n', '\r', '\t', '\v'.

RETURN VALUE top

       The iswspace() function returns nonzero if wc is a wide character belonging
       to the wide-character class "space".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswspace() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       isspace(3), iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWSPACE(3)


iswupper(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWUPPER(3)                  Linux Programmer's Manual                 ISWUPPER(3)

NAME top

       iswupper - test for uppercase wide character

SYNOPSIS top

       #include <wctype.h>

       int iswupper(wint_t wc);

DESCRIPTION top

       The iswupper() function is the wide-character equivalent of the isupper(3)
       function.  It tests whether wc is a wide character belonging to the wide-
       character class "upper".

       The wide-character class "upper" is a subclass of the wide-character class
       "alpha", and therefore also a subclass of the wide-character class "alnum",
       of the wide-character class "graph" and of the wide-character class
       "print".

       Being a subclass of the wide-character class "print", the wide-character
       class "upper" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "upper" is disjoint from the wide-character class "space" and its
       subclass "blank".

       Being a subclass of the wide-character class "alnum", the wide-character
       class "upper" is disjoint from the wide-character class "punct".

       Being a subclass of the wide-character class "alpha", the wide-character
       class "upper" is disjoint from the wide-character class "digit".

       The wide-character class "upper" contains at least those characters wc
       which are equal to towupper(wc) and different from towlower(wc).

       The wide-character class "upper" always contains at least the letters 'A'
       to 'Z'.

RETURN VALUE top

       The iswupper() function returns nonzero if wc is a wide character belonging
       to the wide-character class "upper".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswupper() depends on the LC_CTYPE category of the current
       locale.

       This function is not very appropriate for dealing with Unicode characters,
       because Unicode knows about three cases: upper, lower and title case.

SEE ALSO top

       isupper(3), iswctype(3), towupper(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         ISWUPPER(3)


iswxdigit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ISWXDIGIT(3)                 Linux Programmer's Manual                ISWXDIGIT(3)

NAME top

       iswxdigit - test for hexadecimal digit wide character

SYNOPSIS top

       #include <wctype.h>

       int iswxdigit(wint_t wc);

DESCRIPTION top

       The iswxdigit() function is the wide-character equivalent of the
       isxdigit(3) function.  It tests whether wc is a wide character belonging to
       the wide-character class "xdigit".

       The wide-character class "xdigit" is a subclass of the wide-character class
       "alnum", and therefore also a subclass of the wide-character class "graph"
       and of the wide-character class "print".

       Being a subclass of the wide-character class "print", the wide-character
       class "xdigit" is disjoint from the wide-character class "cntrl".

       Being a subclass of the wide-character class "graph", the wide-character
       class "xdigit" is disjoint from the wide-character class "space" and its
       subclass "blank".

       Being a subclass of the wide-character class "alnum", the wide-character
       class "xdigit" is disjoint from the wide-character class "punct".

       The wide-character class "xdigit" always contains at least the letters 'A'
       to 'F', 'a' to 'f' and the digits '0' to '9'.

RETURN VALUE top

       The iswxdigit() function returns nonzero if wc is a wide character
       belonging to the wide-character class "xdigit".  Otherwise it returns zero.

CONFORMING TO top

       C99.

NOTES top

       The behavior of iswxdigit() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       iswctype(3), isxdigit(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                        ISWXDIGIT(3)


j0(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

J0(3)                        Linux Programmer's Manual                       J0(3)

NAME top

       j0,  j0f,  j0l,  j1, j1f, j1l, jn, jnf, jnl - Bessel functions of the first
       kind

SYNOPSIS top

       #include <math.h>

       double j0(double x);
       double j1(double x);
       double jn(int n, double x);

       float j0f(float x);
       float j1f(float x);
       float jnf(int n, float x);

       long double j0l(long double x);
       long double j1l(long double x);
       long double jnl(int n, long double x);

       Link with -lm.

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

       j0(), j1(), jn():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE
       j0f(), j0l(), j1f(), j1l(), jnf(), jnl():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 600

DESCRIPTION top

       The j0() and j1() functions return Bessel functions of x of the first kind
       of orders 0 and 1, respectively.  The jn() function returns the Bessel
       function of x of the first kind of order n.

       The j0f() etc. and j0l() etc. functions are versions that take and return
       float and long double values, respectively.

RETURN VALUE top

       On success, these functions return the appropriate Bessel value of the
       first kind for x.

       If x is a NaN, a NaN is returned.

       If x is too large in magnitude, or the result underflows, a range error
       occurs, and the return value is 0.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result underflow, or x is too large in magnitude
              errno is set to ERANGE.

       These functions do not raise exceptions for fetestexcept(3).

CONFORMING TO top

       The functions returning double conform to SVr4, 4.3BSD, POSIX.1-2001.  The
       others are nonstandard functions that also exist on the BSDs.

BUGS top

       There are errors of up to 2e-16 in the values returned by j0(), j1() and
       jn() for values of x between -8 and 8.

SEE ALSO top

       y0(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                               J0(3)


kexec_load(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

KEXEC_LOAD(2)                Linux Programmer's Manual               KEXEC_LOAD(2)

NAME top

       kexec_load - load a new kernel for later execution

SYNOPSIS top

       #include <linux/kexec.h>
       long kexec_load(unsigned long entry, unsigned long nr_segments,
                       struct kexec_segment *segments, unsigned long flags);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The kexec_load() system call loads a new kernel that can be executed later
       by reboot(2).

       The flags argument is a mask whose high-order bits control the operation of
       the call.  The following values can be specified in flags:

       KEXEC_ON_CRASH (since Linux 2.6.13)
              Execute the new kernel automatically on a system crash.

       KEXEC_PRESERVE_CONTEXT (since Linux 2.6.27)
              Preserve the system hardware and software states before executing
              the new kernel.  This could be used for system suspend.  This flag
              is only available if the kernel was configured with
              CONFIG_KEXEC_JUMP, and is only effective if nr_segments is greater
              than 0.

       The low-order bits of flags contain the architecture of the to-be-executed
       kernel.  Specify (OR) the constant KEXEC_ARCH_DEFAULT to use the current
       architecture, or one of the following architecture constants
       KEXEC_ARCH_386, KEXEC_ARCH_X86_64, KEXEC_ARCH_PPC, KEXEC_ARCH_PPC64,
       KEXEC_ARCH_IA_64, KEXEC_ARCH_ARM, KEXEC_ARCH_S390, KEXEC_ARCH_SH,
       KEXEC_ARCH_MIPS, and KEXEC_ARCH_MIPS_LE.  The architecture must be
       executable on the CPU of the system.

       The entry argument is the physical entry address in the kernel image.  The
       nr_segments argument is the number of segments pointed to by the segments
       pointer.  The segments argument is an array of kexec_segment structures
       which define the kernel layout:

           struct kexec_segment {
               void   *buf;        /* Buffer in user space */
               size_t  bufsz;      /* Buffer length in user space */
               void   *mem;        /* Physical address of kernel */
               size_t  memsz;      /* Physical address length */
           };

       The kernel image defined by segments is copied from the calling process
       into previously reserved memory.

RETURN VALUE top

       On success, kexec_load() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       EBUSY  Another crash kernel is already being loaded or a crash kernel is
              already in use.

       EINVAL flags is invalid; or nr_segments is too large

       EPERM  The caller does not have the CAP_SYS_BOOT capability.

VERSIONS top

       The kexec_load() system call first appeared in Linux 2.6.13.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       Currently, there is no glibc support for kexec_load().  Call it using
       syscall(2).

       The required constants are in the Linux kernel source file linux/kexec.h,
       which is not currently exported to glibc.  Therefore, these constants must
       be defined manually.

       This system call is only available if the kernel was configured with
       CONFIG_KEXEC.

SEE ALSO top

       reboot(2), syscall(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                       KEXEC_LOAD(2)


keyctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | LINKING | SEE ALSO | COLOPHON The Linux Programming Interface

KEYCTL(2)                   Linux Key Management Calls                   KEYCTL(2)

NAME top

       keyctl - manipulate the kernel's key management facility

SYNOPSIS top

       #include <keyutils.h>

       long keyctl(int cmd, ...);

DESCRIPTION top

       keyctl() has a number of functions available:

       KEYCTL_GET_KEYRING_ID
              Ask for a keyring's ID.

       KEYCTL_JOIN_SESSION_KEYRING
              Join or start named session keyring.

       KEYCTL_UPDATE
              Update a key.

       KEYCTL_REVOKE
              Revoke a key.

       KEYCTL_CHOWN
              Set ownership of a key.

       KEYCTL_SETPERM
              Set perms on a key.

       KEYCTL_DESCRIBE
              Describe a key.

       KEYCTL_CLEAR
              Clear contents of a keyring.

       KEYCTL_LINK
              Link a key into a keyring.

       KEYCTL_UNLINK
              Unlink a key from a keyring.

       KEYCTL_SEARCH
              Search for a key in a keyring.

       KEYCTL_READ
              Read a key or keyring's contents.

       KEYCTL_INSTANTIATE
              Instantiate a partially constructed key.

       KEYCTL_NEGATE
              Negate a partially constructed key.

       KEYCTL_SET_REQKEY_KEYRING
              Set default request-key keyring.

       KEYCTL_SET_TIMEOUT
              Set timeout on a key.

       KEYCTL_ASSUME_AUTHORITY
              Assume authority to instantiate key.

       These are wrapped by libkeyutils into individual functions to permit
       compiler the compiler to check types.  See the See Also section at the
       bottom.

RETURN VALUE top

       On success keyctl() returns the serial number of the key it found.  On
       error, the value -1 will be returned and errno will have been set to an
       appropriate error.

ERRORS top

       EACCES A key operation wasn't permitted.

       EDQUOT The key quota for the caller's user would be exceeded by creating a
              key or linking it to the keyring.

       EKEYEXPIRED
              An expired key was found or specified.

       EKEYREJECTED
              A rejected key was found or specified.

       EKEYREVOKED
              A revoked key was found or specified.

       ENOKEY No matching key was found or an invalid key was specified.

LINKING top

       Although this is a Linux system call, it is not present in libc but can be
       found rather in libkeyutils.  When linking, -lkeyutils should be specified
       to the linker.

SEE ALSO top

       keyctl(1), add_key(2), request_key(2), keyctl_set_timeout(3),
       keyctl_chown(3), keyctl_clear(3), keyctl_describe(3),
       keyctl_describe_alloc(3), keyctl_get_keyring_ID(3), keyctl_instantiate(3),
       keyctl_join_session_keyring(3), keyctl_link(3), keyctl_negate(3),
       keyctl_revoke(3), keyctl_search(3), keyctl_setperm(3),
       keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_read(3),
       keyctl_read_alloc(3), keyctl_unlink(3), keyctl_update(3), request-key(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-25                           KEYCTL(2)


key_setsecret(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

KEY_SETSECRET(3)             Linux Programmer's Manual            KEY_SETSECRET(3)

NAME top

       key_decryptsession,    key_encryptsession,    key_setsecret,    key_gendes,
       key_secretkey_is_set - interfaces to rpc keyserver daemon

SYNOPSIS top

       #include <rpc/rpc.h>

       int key_decryptsession(const char *remotename, des_block *deskey);

       int key_encryptsession(const char *remotename, des_block *deskey);

       int key_gendes(des_block *deskey);

       int key_setsecret(const char *key);

       int key_secretkey_is_set(void);

DESCRIPTION top

       The functions here are used within the RPC's secure authentication
       mechanism (AUTH_DES).  There should be no need for user programs to use
       this functions.

       The function key_decryptsession() uses the (remote) server netname and
       takes the DES key for decrypting.  It uses the public key of the server and
       the secret key associated with the effective UID of the calling process.

       The function key_encryptsession() is the inverse of key_decryptsession().
       It encrypts the DES keys with the public key of the server and the secret
       key associated with the effective UID of the calling process.

       The function key_gendes() is used to ask the keyserver for a secure
       conversation key.

       The function key_setsecret() is used to set the key for the effective UID
       of the calling process.

       The function key_secretkey_is_set() can be used to determine whether a key
       has been set for the effective UID of the calling process.

RETURN VALUE top

       These functions return 1 on success and 0 on failure.

NOTES top

       Note that we talk about two types of encryption here.  One is asymmetric
       using a public and secret key.  The other is symmetric, the 64-bit DES.

       These routines were part of the Linux/Doors-project, abandoned by now.

SEE ALSO top

       crypt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2002-07-18                    KEY_SETSECRET(3)


kill(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

KILL(2)                      Linux Programmer's Manual                     KILL(2)

NAME top

       kill - send signal to a process

SYNOPSIS top

       #include <sys/types.h>
       #include <signal.h>

       int kill(pid_t pid, int sig);

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

       kill(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The kill() system call can be used to send any signal to any process group
       or process.

       If pid is positive, then signal sig is sent to the process with the ID
       specified by pid.

       If pid equals 0, then sig is sent to every process in the process group of
       the calling process.

       If pid equals -1, then sig is sent to every process for which the calling
       process has permission to send signals, except for process 1 (init), but
       see below.

       If pid is less than -1, then sig is sent to every process in the process
       group whose ID is -pid.

       If sig is 0, then no signal is sent, but error checking is still performed;
       this can be used to check for the existence of a process ID or process
       group ID.

       For a process to have permission to send a signal it must either be
       privileged (under Linux: have the CAP_KILL capability), or the real or
       effective user ID of the sending process must equal the real or saved set-
       user-ID of the target process.  In the case of SIGCONT it suffices when the
       sending and receiving processes belong to the same session.

RETURN VALUE top

       On success (at least one signal was sent), zero is returned.  On error, -1
       is returned, and errno is set appropriately.

ERRORS top

       EINVAL An invalid signal was specified.

       EPERM  The process does not have permission to send the signal to any of
              the target processes.

       ESRCH  The pid or process group does not exist.  Note that an existing
              process might be a zombie, a process which already committed
              termination, but has not yet been wait(2)ed for.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       The only signals that can be sent to process ID 1, the init process, are
       those for which init has explicitly installed signal handlers.  This is
       done to assure the system is not brought down accidentally.

       POSIX.1-2001 requires that kill(-1,sig) send sig to all processes that the
       calling process may send signals to, except possibly for some
       implementation-defined system processes.  Linux allows a process to signal
       itself, but on Linux the call kill(-1,sig) does not signal the calling
       process.

       POSIX.1-2001 requires that if a process sends a signal to itself, and the
       sending thread does not have the signal blocked, and no other thread has it
       unblocked or is waiting for it in sigwait(3), at least one unblocked signal
       must be delivered to the sending thread before the kill() returns.

Linux Notes

       Across different kernel versions, Linux has enforced different rules for
       the permissions required for an unprivileged process to send a signal to
       another process.  In kernels 1.0 to 1.2.2, a signal could be sent if the
       effective user ID of the sender matched that of the receiver, or the real
       user ID of the sender matched that of the receiver.  From kernel 1.2.3
       until 1.3.77, a signal could be sent if the effective user ID of the sender
       matched either the real or effective user ID of the receiver.  The current
       rules, which conform to POSIX.1-2001, were adopted in kernel 1.3.78.

BUGS top

       In 2.6 kernels up to and including 2.6.7, there was a bug that meant that
       when sending signals to a process group, kill() failed with the error EPERM
       if the caller did have permission to send the signal to any (rather than
       all) of the members of the process group.  Notwithstanding this error
       return, the signal was still delivered to all of the processes for which
       the caller had permission to signal.

SEE ALSO top

       _exit(2), killpg(2), signal(2), tkill(2), exit(3), sigqueue(3),
       capabilities(7), credentials(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-09-15                             KILL(2)


killpg(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

KILLPG(2)                    Linux Programmer's Manual                   KILLPG(2)

NAME top

       killpg - send signal to a process group

SYNOPSIS top

       #include <signal.h>

       int killpg(int pgrp, int sig);

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

       killpg():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       killpg() sends the signal sig to the process group pgrp.  See signal(7) for
       a list of signals.

       If pgrp is 0, killpg() sends the signal to the calling process's process
       group.  (POSIX says: If pgrp is less than or equal to 1, the behavior is
       undefined.)

       For a process to have permission to send a signal it must either be
       privileged (under Linux: have the CAP_KILL capability), or the real or
       effective user ID of the sending process must equal the real or saved set-
       user-ID of the target process.  In the case of SIGCONT it suffices when the
       sending and receiving processes belong to the same session.

RETURN VALUE top

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

ERRORS top

       EINVAL Sig is not a valid signal number.

       EPERM  The process does not have permission to send the signal to any of
              the target processes.

       ESRCH  No process can be found in the process group specified by pgrp.

       ESRCH  The process group was given as 0 but the sending process does not
              have a process group.

CONFORMING TO top

       SVr4, 4.4BSD (the killpg() function call first appeared in 4BSD),
       POSIX.1-2001.

NOTES top

       There are various differences between the permission checking in BSD-type
       systems and System V-type systems.  See the POSIX rationale for kill().  A
       difference not mentioned by POSIX concerns the return value EPERM: BSD
       documents that no signal is sent and EPERM returned when the permission
       check failed for at least one target process, while POSIX documents EPERM
       only when the permission check failed for all target processes.

       On Linux, killpg() is implemented as a library function that makes the call
       kill(-pgrp, sig).

SEE ALSO top

       getpgrp(2), kill(2), signal(2), capabilities(7), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                           KILLPG(2)


syslog(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYSLOG(2)                    Linux Programmer's Manual                   SYSLOG(2)

NAME top

       syslog,  klogctl  -  read and/or clear kernel message ring buffer; set con-
       sole_loglevel

SYNOPSIS top

       int syslog(int type, char *bufp, int len);
                       /* No wrapper provided in glibc */

       /* The glibc interface */
       #include <sys/klog.h>

       int klogctl(int type, char *bufp, int len);

DESCRIPTION top

       If you need the C library function syslog() (which talks to syslogd(8)),
       then look at syslog(3).  The system call of this name is about controlling
       the kernel printk() buffer, and the glibc wrapper function is called
       klogctl().

The kernel log buffer

       The kernel has a cyclic buffer of length LOG_BUF_LEN in which messages
       given as arguments to the kernel function printk() are stored (regardless
       of their loglevel).  In early kernels, LOG_BUF_LEN had the value 4096; from
       kernel 1.3.54, it was 8192; from kernel 2.1.113 it was 16384; since
       2.4.23/2.6 the value is a kernel configuration option
       (CONFIG_LOG_BUF_SHIFT).  In recent kernels the size can be queried with
       command type 10 (see below).

Commands

       The type argument determines the action taken by this function.  The list
       below specifies the values for type.  The symbolic names are defined in the
       kernel source, but are not exported to user space; you will either need to
       use the numbers, or define the names yourself.

       SYSLOG_ACTION_CLOSE (0)
              Close the log.  Currently a NOP.

       SYSLOG_ACTION_OPEN (1)
              Open the log.  Currently a NOP.

       SYSLOG_ACTION_READ (2)
              Read from the log.  The call waits until the kernel log buffer is
              nonempty, and then reads at most len bytes into the buffer pointed
              to by bufp.  The call returns the number of bytes read.  Bytes read
              from the log disappear from the log buffer: the information can only
              be read once.  This is the function executed by the kernel when a
              user program reads /proc/kmsg.

       SYSLOG_ACTION_READ_ALL (3)
              Read all messages remaining in the ring buffer, placing then in the
              buffer pointed to by bufp.  The call reads the last len bytes from
              the log buffer (nondestructively), but will not read more than was
              written into the buffer since the last "clear ring buffer" command
              (see command 5 below)).  The call returns the number of bytes read.

       SYSLOG_ACTION_READ_CLEAR (4)
              Read and clear all messages remaining in the ring buffer.  The call
              does precisely the same as for a type of 3, but also executes the
              "clear ring buffer" command.

       SYSLOG_ACTION_CLEAR (5)
              The call executes just the "clear ring buffer" command.  The bufp
              and len arguments are ignored.

              This command does not really clear the ring buffer.  Rather, it sets
              a kernel bookkeeping variable that determines the results returned
              by commands 3 (SYSLOG_ACTION_READ_ALL) and 4
              (SYSLOG_ACTION_READ_CLEAR).  This command has no effect on commands
              2 (SYSLOG_ACTION_READ) and 9 (SYSLOG_ACTION_SIZE_UNREAD).

       SYSLOG_ACTION_CONSOLE_OFF (6)
              Disable printk to console.  The call sets the console log level to
              the minimum, so that no messages are printed to the console.  The
              bufp and len arguments are ignored.

       SYSLOG_ACTION_CONSOLE_ON (7)
              The call sets the console log level to the default, so that messages
              are printed to the console.  The bufp and len arguments are ignored.

       SYSLOG_ACTION_CONSOLE_LEVEL (8)
              The call sets the console log level to the value given in len, which
              must be an integer between 1 and 8 (inclusive).  See the loglevel
              section for details.  The bufp argument is ignored.

       SYSLOG_ACTION_SIZE_UNREAD (9) (since Linux 2.4.10)
              The call returns the number of bytes currently available to be read
              from the kernel log buffer via command 2 (SYSLOG_ACTION_READ).  The
              bufp and len arguments are ignored.

       SYSLOG_ACTION_SIZE_BUFFER (10) (since Linux 2.6.6)
              This command returns the total size of the kernel log buffer.  The
              bufp and len arguments are ignored.

       All commands except 3 and 10 require privilege.  In Linux kernels before
       2.6.37, command types 3 and 10 are allowed to unprivileged processes; since
       Linux 2.6.37, these commands are allowed to unprivileged processes only if
       /proc/sys/kernel/dmesg_restrict has the value 0.  Before Linux 2.6.37,
       "privileged" means that the caller has the CAP_SYS_ADMIN capability.  Since
       Linux 2.6.37, "privileged" means that the caller has either the
       CAP_SYS_ADMIN capability (now deprecated for this purpose) or the (new)
       CAP_SYSLOG capability.

The loglevel

       The kernel routine printk() will only print a message on the console, if it
       has a loglevel less than the value of the variable console_loglevel.  This
       variable initially has the value DEFAULT_CONSOLE_LOGLEVEL (7), but is set
       to 10 if the kernel command line contains the word "debug", and to 15 in
       case of a kernel fault (the 10 and 15 are just silly, and equivalent to 8).
       This variable is set (to a value in the range 1-8) by a syslog() call with
       a type of 8.  Calls to syslog() with type equal to 6 or 7 set the variable
       to 1 (kernel panics only) or 7 (all except debugging messages),
       respectively.

       Every text line in a message has its own loglevel.  This level is
       DEFAULT_MESSAGE_LOGLEVEL - 1 (6) unless the line starts with <d> where d is
       a digit in the range 1-7, in which case the level is d.  The conventional
       meaning of the loglevel is defined in <linux/kernel.h> as follows:

       #define KERN_EMERG    "<0>"  /* system is unusable               */
       #define KERN_ALERT    "<1>"  /* action must be taken immediately */
       #define KERN_CRIT     "<2>"  /* critical conditions              */
       #define KERN_ERR      "<3>"  /* error conditions                 */
       #define KERN_WARNING  "<4>"  /* warning conditions               */
       #define KERN_NOTICE   "<5>"  /* normal but significant condition */
       #define KERN_INFO     "<6>"  /* informational                    */
       #define KERN_DEBUG    "<7>"  /* debug-level messages             */

RETURN VALUE top

       For type equal to 2, 3, or 4, a successful call to syslog() returns the
       number of bytes read.  For type 9, syslog() returns the number of bytes
       currently available to be read on the kernel log buffer.  For type 10,
       syslog() returns the total size of the kernel log buffer.  For other values
       of type, 0 is returned on success.

       In case of error, -1 is returned, and errno is set to indicate the error.

ERRORS top

       EINVAL Bad arguments (e.g., bad type; or for type 2, 3, or 4, buf is NULL,
              or len is less than zero; or for type 8, the level is outside the
              range 1 to 8).

       ENOSYS This syslog() system call is not available, because the kernel was
              compiled with the CONFIG_PRINTK kernel-configuration option
              disabled.

       EPERM  An attempt was made to change console_loglevel or clear the kernel
              message ring buffer by a process without sufficient privilege (more
              precisely: without the CAP_SYS_ADMIN or CAP_SYSLOG capability).

       ERESTARTSYS
              System call was interrupted by a signal; nothing was read.  (This
              can be seen only during a trace.)

CONFORMING TO top

       This system call is Linux-specific and should not be used in programs
       intended to be portable.

NOTES top

       From the very start people noted that it is unfortunate that a system call
       and a library routine of the same name are entirely different animals.

SEE ALSO top

       syslog(3), capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-11-29                           SYSLOG(2)


mem(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

MEM(4)                       Linux Programmer's Manual                      MEM(4)

NAME top

       mem, kmem, port - system memory, kernel memory and system ports

DESCRIPTION top

       mem is a character device file that is an image of the main memory of the
       computer.  It may be used, for example, to examine (and even patch) the
       system.

       Byte addresses in mem are interpreted as physical memory addresses.
       References to nonexistent locations cause errors to be returned.

       Examining and patching is likely to lead to unexpected results when read-
       only or write-only bits are present.

       It is typically created by:

              mknod -m 660 /dev/mem c 1 1
              chown root:kmem /dev/mem

       The file kmem is the same as mem, except that the kernel virtual memory
       rather than physical memory is accessed.

       It is typically created by:

              mknod -m 640 /dev/kmem c 1 2
              chown root:kmem /dev/kmem

       port is similar to mem, but the I/O ports are accessed.

       It is typically created by:

              mknod -m 660 /dev/port c 1 4
              chown root:mem /dev/port

FILES top

       /dev/mem
       /dev/kmem
       /dev/port

SEE ALSO top

       chown(1), mknod(1), ioperm(2)

COLOPHON top

       This page is part of release 3.45 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                               1992-11-21                              MEM(4)


koi8-r(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

KOI8-R(7)                    Linux Programmer's Manual                   KOI8-R(7)

NAME top

       koi8-r - Russian character set encoded in octal, decimal, and hexadecimal

DESCRIPTION top

       KOI8-R is the character set of choice for encoding Russian texts for many
       UNIX-like operation systems.  KOI8-R is a successor for KOI-8, a de-facto
       standard for Internet Mail, News, WWW and other interactive services at
       least all over the ex-SU territory.

       KOI8-R is defined by RFC 1489 (Registration of a Cyrillic Character Set).

NOTES top

       KOI8-R was designed for mixed Russian/English texts and covers only Russian
       Cyrillic characters, so if you're looking for Cyrillic characters for
       Ukrainian, Byelorussian, and so on, try ISO-IR-111, or KOI8-U (Ukrainian
       Character Set), or KOI8-C (for ancient Russian texts) instead, which are
       identical to KOI8-R in the Russian Cyrillic letters area.

       A more complete set of Cyrillic characters is also defined by the
       ISO-8859-5 character set.

KOI8-R Characters

       The following table displays the characters in KOI8-R, which are printable
       and unlisted in the ascii(7) manual page.

       Oct   Dec   Hex   Char   Description
       ----------------------------------------------------------------------------
       200   128   80           BOX DRAWINGS LIGHT HORIZONTAL
       201   129   81           BOX DRAWINGS LIGHT VERTICAL
       202   130   82           BOX DRAWINGS LIGHT DOWN AND RIGHT
       203   131   83           BOX DRAWINGS LIGHT DOWN AND LEFT
       204   132   84           BOX DRAWINGS LIGHT UP AND RIGHT
       205   133   85           BOX DRAWINGS LIGHT UP AND LEFT
       206   134   86           BOX DRAWINGS LIGHT VERTICAL AND RIGHT
       207   135   87           BOX DRAWINGS LIGHT VERTICAL AND LEFT
       210   136   88           BOX DRAWINGS LIGHT DOWN AND HORIZONTAL
       211   137   89           BOX DRAWINGS LIGHT UP AND HORIZONTAL
       212   138   8A           BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL
       213   139   8B           UPPER HALF BLOCK
       214   140   8C           LOWER HALF BLOCK
       215   141   8D           FULL BLOCK
       216   142   8E           LEFT HALF BLOCK
       217   143   8F           RIGHT HALF BLOCK
       220   144   90           LIGHT SHADE
       221   145   91           MEDIUM SHADE
       222   146   92           DARK SHADE
       223   147   93           TOP HALF INTEGRAL
       224   148   94           BLACK SQUARE
       225   149   95           BULLET OPERATOR
       226   150   96           SQUARE ROOT
       227   151   97           ALMOST EQUAL TO
       230   152   98           LESS-THAN OR EQUAL TO
       231   153   99           GREATER-THAN OR EQUAL TO
       232   154   9A           NO-BREAK SPACE
       233   155   9B           BOTTOM HALF INTEGRAL
       234   156   9C           DEGREE SIGN
       235   157   9D           SUPERSCRIPT TWO
       236   158   9E           MIDDLE DOT
       237   159   9F           DIVISION SIGN
       240   160   A0           BOX DRAWINGS DOUBLE HORIZONTAL
       241   161   A1     ,i     BOX DRAWINGS DOUBLE VERTICAL

       242   162   A2     /c     BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE
       243   163   A3     -L     CYRILLIC SMALL LETTER IO
       244   164   A4     ox     BOX DRAWINGS DOWN DOUBLE AND RIGHT SINGLE
       245   165   A5     =Y     BOX DRAWINGS DOUBLE DOWN AND RIGHT
       246   166   A6     |     BOX DRAWINGS DOWN SINGLE AND LEFT DOUBLE
       247   167   A7     S     BOX DRAWINGS DOWN DOUBLE AND LEFT SINGLE
       250   168   A8     "     BOX DRAWINGS DOUBLE DOWN AND LEFT
       251   169   A9    (C)    BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE
       252   170   AA     _a     BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE
       253   171   AB     <<    BOX DRAWINGS DOUBLE UP AND RIGHT
       254   172   AC     ~     BOX DRAWINGS UP SINGLE AND LEFT DOUBLE
       255   173   AD           BOX DRAWINGS UP DOUBLE AND LEFT SINGLE
       256   174   AE    (R_)    BOX DRAWINGS DOUBLE UP AND LEFT
       257   175   AF           BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE
       260   176   B0     o     BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE
       261   177   B1     +-    BOX DRAWINGS DOUBLE VERTICAL AND RIGHT
       262   178   B2     2     BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE
       263   179   B3     3     CYRILLIC CAPITAL LETTER IO
       264   180   B4     '     BOX DRAWINGS VERTICAL DOUBLE AND LEFT SINGLE
       265   181   B5     ,u     BOX DRAWINGS DOUBLE VERTICAL AND LEFT
       266   182   B6     9|    BOX DRAWINGS DOWN SINGLE AND HORIZONTAL DOUBLE
       267   183   B7     .     BOX DRAWINGS DOWN DOUBLE AND HORIZONTAL SINGLE
       270   184   B8     ,     BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL
       271   185   B9     1     BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE
       272   186   BA     _o     BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE
       273   187   BB     >>    BOX DRAWINGS DOUBLE UP AND HORIZONTAL
       274   188   BC    1/4    BOX DRAWINGS VERTICAL SINGLE AND HORIZONTAL DOUBLE
       275   189   BD    1/2    BOX DRAWINGS VERTICAL DOUBLE AND HORIZONTAL SINGLE
       276   190   BE    3/4    BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL
       277   191   BF     'c     COPYRIGHT SIGN
       300   192   C0     `A     CYRILLIC SMALL LETTER YU
       301   193   C1     'A     CYRILLIC SMALL LETTER A
       302   194   C2     ^A     CYRILLIC SMALL LETTER BE
       303   195   C3     ~A     CYRILLIC SMALL LETTER TSE
       304   196   C4     "A     CYRILLIC SMALL LETTER DE
       305   197   C5     oA     CYRILLIC SMALL LETTER IE
       306   198   C6     AE    CYRILLIC SMALL LETTER EF
       307   199   C7     ,C     CYRILLIC SMALL LETTER GHE
       310   200   C8     `E     CYRILLIC SMALL LETTER HA
       311   201   C9     'E     CYRILLIC SMALL LETTER I
       312   202   CA     ^E     CYRILLIC SMALL LETTER SHORT I
       313   203   CB     "E     CYRILLIC SMALL LETTER KA
       314   204   CC     `I     CYRILLIC SMALL LETTER EL
       315   205   CD     'I     CYRILLIC SMALL LETTER EM
       316   206   CE     ^I     CYRILLIC SMALL LETTER EN
       317   207   CF     "I     CYRILLIC SMALL LETTER O
       320   208   D0     -D     CYRILLIC SMALL LETTER PE
       321   209   D1     ~N     CYRILLIC SMALL LETTER YA
       322   210   D2     `O     CYRILLIC SMALL LETTER ER
       323   211   D3     'O     CYRILLIC SMALL LETTER ES
       324   212   D4     ^O     CYRILLIC SMALL LETTER TE
       325   213   D5     ~O     CYRILLIC SMALL LETTER U
       326   214   D6     "O     CYRILLIC SMALL LETTER ZHE
       327   215   D7     x     CYRILLIC SMALL LETTER VE
       330   216   D8     /O     CYRILLIC SMALL LETTER SOFT SIGN
       331   217   D9     `U     CYRILLIC SMALL LETTER YERU
       332   218   DA     'U     CYRILLIC SMALL LETTER ZE
       333   219   DB     ^U     CYRILLIC SMALL LETTER SHA
       334   220   DC     "U     CYRILLIC SMALL LETTER E
       335   221   DD     'Y     CYRILLIC SMALL LETTER SHCHA
       336   222   DE     Ib     CYRILLIC SMALL LETTER CHE
       337   223   DF     B     CYRILLIC SMALL LETTER HARD SIGN
       340   224   E0     `a     CYRILLIC CAPITAL LETTER YU
       341   225   E1     'a     CYRILLIC CAPITAL LETTER A
       342   226   E2     ^a     CYRILLIC CAPITAL LETTER BE

       343   227   E3     ~a     CYRILLIC CAPITAL LETTER TSE
       344   228   E4     "a     CYRILLIC CAPITAL LETTER DE
       345   229   E5     oa     CYRILLIC CAPITAL LETTER IE
       346   230   E6     ae    CYRILLIC CAPITAL LETTER EF
       347   231   E7     ,c     CYRILLIC CAPITAL LETTER GHE
       350   232   E8     `e     CYRILLIC CAPITAL LETTER HA
       351   233   E9     'e     CYRILLIC CAPITAL LETTER I
       352   234   EA     ^e     CYRILLIC CAPITAL LETTER SHORT I
       353   235   EB     "e     CYRILLIC CAPITAL LETTER KA
       354   236   EC     `i     CYRILLIC CAPITAL LETTER EL
       355   237   ED     'i     CYRILLIC CAPITAL LETTER EM
       356   238   EE     ^i     CYRILLIC CAPITAL LETTER EN
       357   239   EF     "i     CYRILLIC CAPITAL LETTER O
       360   240   F0     `'o     CYRILLIC CAPITAL LETTER PE
       361   241   F1     ~n     CYRILLIC CAPITAL LETTER YA
       362   242   F2     `o     CYRILLIC CAPITAL LETTER ER
       363   243   F3     'o     CYRILLIC CAPITAL LETTER ES
       364   244   F4     ^o     CYRILLIC CAPITAL LETTER TE
       365   245   F5     ~o     CYRILLIC CAPITAL LETTER U
       366   246   F6     "o     CYRILLIC CAPITAL LETTER ZHE
       367   247   F7    -:-    CYRILLIC CAPITAL LETTER VE
       370   248   F8     /o     CYRILLIC CAPITAL LETTER SOFT SIGN
       371   249   F9     `u     CYRILLIC CAPITAL LETTER YERU
       372   250   FA     'u     CYRILLIC CAPITAL LETTER ZE
       373   251   FB     ^u     CYRILLIC CAPITAL LETTER SHA
       374   252   FC     "u     CYRILLIC CAPITAL LETTER E
       375   253   FD     'y     CYRILLIC CAPITAL LETTER SHCHA
       376   254   FE     pb     CYRILLIC CAPITAL LETTER CHE
       377   255   FF     "y     CYRILLIC CAPITAL LETTER HARD SIGN

SEE ALSO top

       ascii(7), iso-8859-5(7), koi8-u(7)

       RFC 1489, <http://koi8.pp.ru/>

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                           KOI8-R(7)


koi8-u(7) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

KOI8-U(7)                    Linux Programmer's Manual                   KOI8-U(7)

NAME top

       koi8-u - Ukrainian character set encoded in octal, decimal, and hexadecimal

DESCRIPTION top

       KOI8-U (KOI8 Ukrainian, described in RFC 2310) is the de-facto standard
       character set for encoding Ukrainian texts.  KOI8-U is compatible with
       KOI8-R (RFC 1489) for all Russian letters, and extends KOI8-R with four
       Ukrainian letters (in both upper and lower case) in locations that are
       compliant with ISO-IR-111.

KOI8-U Characters

       The following table displays the characters in KOI8-U, which are printable
       and unlisted in the ascii(7) manual page.  The fourth column will only show
       the proper glyphs in an environment configured for koi8-u.

       Oct   Dec   Hex   Char   Description
       ----------------------------------------------------------------------------
       200   128   80           BOX DRAWINGS LIGHT HORIZONTAL
       201   129   81           BOX DRAWINGS LIGHT VERTICAL
       202   130   82           BOX DRAWINGS LIGHT DOWN AND RIGHT
       203   131   83           BOX DRAWINGS LIGHT DOWN AND LEFT
       204   132   84           BOX DRAWINGS LIGHT UP AND RIGHT
       205   133   85           BOX DRAWINGS LIGHT UP AND LEFT
       206   134   86           BOX DRAWINGS LIGHT VERTICAL AND RIGHT
       207   135   87           BOX DRAWINGS LIGHT VERTICAL AND LEFT
       210   136   88           BOX DRAWINGS LIGHT DOWN AND HORIZONTAL
       211   137   89           BOX DRAWINGS LIGHT UP AND HORIZONTAL
       212   138   8A           BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL
       213   139   8B           UPPER HALF BLOCK
       214   140   8C           LOWER HALF BLOCK
       215   141   8D           FULL BLOCK
       216   142   8E           LEFT HALF BLOCK
       217   143   8F           RIGHT HALF BLOCK
       220   144   90           LIGHT SHADE
       221   145   91           MEDIUM SHADE
       222   146   92           DARK SHADE
       223   147   93           TOP HALF INTEGRAL
       224   148   94           BLACK SQUARE
       225   149   95           BULLET OPERATOR
       226   150   96           SQUARE ROOT
       227   151   97           ALMOST EQUAL TO
       230   152   98           LESS-THAN OR EQUAL TO
       231   153   99           GREATER-THAN OR EQUAL TO
       232   154   9A           NO-BREAK SPACE
       233   155   9B           BOTTOM HALF INTEGRAL
       234   156   9C           DEGREE SIGN
       235   157   9D           SUPERSCRIPT TWO
       236   158   9E           MIDDLE DOT
       237   159   9F           DIVISION SIGN
       240   160   A0           BOX DRAWINGS DOUBLE HORIZONTAL
       241   161   A1     ,i     BOX DRAWINGS DOUBLE VERTICAL
       242   162   A2     /c     BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE
       243   163   A3     -L     CYRILLIC SMALL LETTER IO
       244   164   A4     ox     CYRILLIC SMALL LETTER UKRAINIAN IE
       245   165   A5     =Y     BOX DRAWINGS DOUBLE DOWN AND RIGHT
       246   166   A6     |     CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I
       247   167   A7     S     CYRILLIC SMALL LETTER YI (Ukrainian)
       250   168   A8     "     BOX DRAWINGS DOUBLE DOWN AND LEFT
       251   169   A9    (C)    BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE
       252   170   AA     _a     BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE
       253   171   AB     <<    BOX DRAWINGS DOUBLE UP AND RIGHT

       254   172   AC     ~     BOX DRAWINGS UP SINGLE AND LEFT DOUBLE
       255   173   AD           CYRILLIC SMALL LETTER GHE WITH UPTURN
       256   174   AE    (R_)    BOX DRAWINGS DOUBLE UP AND LEFT
       257   175   AF           BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE
       260   176   B0     o     BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE
       261   177   B1     +-    BOX DRAWINGS DOUBLE VERTICAL AND RIGHT
       262   178   B2     2     BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE
       263   179   B3     3     CYRILLIC CAPITAL LETTER IO
       264   180   B4     '     CYRILLIC CAPITAL LETTER UKRAINIAN IE
       265   181   B5     ,u     BOX DRAWINGS DOUBLE VERTICAL AND LEFT
       266   182   B6     9|    CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I
       267   183   B7     .     CYRILLIC CAPITAL LETTER YI (Ukrainian)
       270   184   B8     ,     BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL
       271   185   B9     1     BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE
       272   186   BA     _o     BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE
       273   187   BB     >>    BOX DRAWINGS DOUBLE UP AND HORIZONTAL
       274   188   BC    1/4    BOX DRAWINGS VERTICAL SINGLE AND HORIZONTAL DOUBLE
       275   189   BD    1/2    CYRILLIC CAPITAL LETTER GHE WITH UPTURN
       276   190   BE    3/4    BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL
       277   191   BF     'c     COPYRIGHT SIGN
       300   192   C0     `A     CYRILLIC SMALL LETTER YU
       301   193   C1     'A     CYRILLIC SMALL LETTER A
       302   194   C2     ^A     CYRILLIC SMALL LETTER BE
       303   195   C3     ~A     CYRILLIC SMALL LETTER TSE
       304   196   C4     "A     CYRILLIC SMALL LETTER DE
       305   197   C5     oA     CYRILLIC SMALL LETTER IE
       306   198   C6     AE    CYRILLIC SMALL LETTER EF
       307   199   C7     ,C     CYRILLIC SMALL LETTER GHE
       310   200   C8     `E     CYRILLIC SMALL LETTER HA
       311   201   C9     'E     CYRILLIC SMALL LETTER I
       312   202   CA     ^E     CYRILLIC SMALL LETTER SHORT I
       313   203   CB     "E     CYRILLIC SMALL LETTER KA
       314   204   CC     `I     CYRILLIC SMALL LETTER EL
       315   205   CD     'I     CYRILLIC SMALL LETTER EM
       316   206   CE     ^I     CYRILLIC SMALL LETTER EN
       317   207   CF     "I     CYRILLIC SMALL LETTER O
       320   208   D0     -D     CYRILLIC SMALL LETTER PE
       321   209   D1     ~N     CYRILLIC SMALL LETTER YA
       322   210   D2     `O     CYRILLIC SMALL LETTER ER
       323   211   D3     'O     CYRILLIC SMALL LETTER ES
       324   212   D4     ^O     CYRILLIC SMALL LETTER TE
       325   213   D5     ~O     CYRILLIC SMALL LETTER U
       326   214   D6     "O     CYRILLIC SMALL LETTER ZHE
       327   215   D7     x     CYRILLIC SMALL LETTER VE
       330   216   D8     /O     CYRILLIC SMALL LETTER SOFT SIGN
       331   217   D9     `U     CYRILLIC SMALL LETTER YERU
       332   218   DA     'U     CYRILLIC SMALL LETTER ZE
       333   219   DB     ^U     CYRILLIC SMALL LETTER SHA
       334   220   DC     "U     CYRILLIC SMALL LETTER E
       335   221   DD     'Y     CYRILLIC SMALL LETTER SHCHA
       336   222   DE     Ib     CYRILLIC SMALL LETTER CHE
       337   223   DF     B     CYRILLIC SMALL LETTER HARD SIGN
       340   224   E0     `a     CYRILLIC CAPITAL LETTER YU
       341   225   E1     'a     CYRILLIC CAPITAL LETTER A
       342   226   E2     ^a     CYRILLIC CAPITAL LETTER BE
       343   227   E3     ~a     CYRILLIC CAPITAL LETTER TSE
       344   228   E4     "a     CYRILLIC CAPITAL LETTER DE
       345   229   E5     oa     CYRILLIC CAPITAL LETTER IE
       346   230   E6     ae    CYRILLIC CAPITAL LETTER EF
       347   231   E7     ,c     CYRILLIC CAPITAL LETTER GHE
       350   232   E8     `e     CYRILLIC CAPITAL LETTER HA
       351   233   E9     'e     CYRILLIC CAPITAL LETTER I
       352   234   EA     ^e     CYRILLIC CAPITAL LETTER SHORT I
       353   235   EB     "e     CYRILLIC CAPITAL LETTER KA
       354   236   EC     `i     CYRILLIC CAPITAL LETTER EL

       355   237   ED     'i     CYRILLIC CAPITAL LETTER EM
       356   238   EE     ^i     CYRILLIC CAPITAL LETTER EN
       357   239   EF     "i     CYRILLIC CAPITAL LETTER O
       360   240   F0     `'o     CYRILLIC CAPITAL LETTER PE
       361   241   F1     ~n     CYRILLIC CAPITAL LETTER YA
       362   242   F2     `o     CYRILLIC CAPITAL LETTER ER
       363   243   F3     'o     CYRILLIC CAPITAL LETTER ES
       364   244   F4     ^o     CYRILLIC CAPITAL LETTER TE
       365   245   F5     ~o     CYRILLIC CAPITAL LETTER U
       366   246   F6     "o     CYRILLIC CAPITAL LETTER ZHE
       367   247   F7    -:-    CYRILLIC CAPITAL LETTER VE
       370   248   F8     /o     CYRILLIC CAPITAL LETTER SOFT SIGN
       371   249   F9     `u     CYRILLIC CAPITAL LETTER YERU
       372   250   FA     'u     CYRILLIC CAPITAL LETTER ZE
       373   251   FB     ^u     CYRILLIC CAPITAL LETTER SHA
       374   252   FC     "u     CYRILLIC CAPITAL LETTER E
       375   253   FD     'y     CYRILLIC CAPITAL LETTER SHCHA
       376   254   FE     pb     CYRILLIC CAPITAL LETTER CHE
       377   255   FF     "y     CYRILLIC CAPITAL LETTER HARD SIGN

NOTES top

       The differences from KOI8-R are in the hex positions A4, A6, A7, AD, B4,
       B6, B7, and BD.

SEE ALSO top

       ascii(7), koi8-r(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                           KOI8-U(7)


a64l(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

A64L(3)                      Linux Programmer's Manual                     A64L(3)

NAME top

       a64l, l64a - convert between long and base-64

SYNOPSIS top

       #include <stdlib.h>

       long a64l(char *str64);

       char *l64a(long value);

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

       a64l(), l64a():
           _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       These functions provide a conversion between 32-bit long integers and
       little-endian base-64 ASCII strings (of length zero to six).  If the string
       used as argument for a64l() has length greater than six, only the first six
       bytes are used.  If the type long has more than 32 bits, then l64a() uses
       only the low order 32 bits of value, and a64l() sign-extends its 32-bit
       result.

       The 64 digits in the base-64 system are:

              '.'  represents a 0
              '/'  represents a 1
              0-9  represent  2-11
              A-Z  represent 12-37
              a-z  represent 38-63

       So 123 = 59*64^0 + 1*64^1 = "v/".

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The value returned by l64a() may be a pointer to a static buffer, possibly
       overwritten by later calls.

       The behavior of l64a() is undefined when value is negative.  If value is
       zero, it returns an empty string.

       These functions are broken in glibc before 2.2.5 (puts most significant
       digit first).

       This is not the encoding used by uuencode(1).

SEE ALSO top

       uuencode(1), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             A64L(3)


ld.so(8) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | HARDWARE CAPABILITIES | ENVIRONMENT | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LD.SO(8)                     Linux Programmer's Manual                    LD.SO(8)

NAME top

       ld.so, ld-linux.so* - dynamic linker/loader

SYNOPSIS top

       The dynamic linker can be run either indirectly by running some dynamically
       linked program or library (in which case no  command-line  options  to  the
       dynamic linker can be passed and, in the ELF case, the dynamic linker which
       is stored in the .interp section of the program is executed) or directly by
       running:

       /lib/ld-linux.so.*  [OPTIONS] [PROGRAM [ARGUMENTS]]

DESCRIPTION top

       The programs ld.so and ld-linux.so* find and load the shared libraries
       needed by a program, prepare the program to run, and then run it.

       Linux binaries require dynamic linking (linking at run time) unless the
       -static option was given to ld(1) during compilation.

       The program ld.so handles a.out binaries, a format used long ago; ld-
       linux.so* handles ELF (/lib/ld-linux.so.1 for libc5, /lib/ld-linux.so.2 for
       glibc2), which everybody has been using for years now.  Otherwise both have
       the same behavior, and use the same support files and programs ldd(1),
       ldconfig(8) and /etc/ld.so.conf.

       When resolving library dependencies, the dynamic linker first inspects each
       dependency string to see if it contains a slash (this can occur if a
       library pathname containing slashes was specified at link time).  If a
       slash is found, then the dependency string is interpreted as a (relative or
       absolute) pathname, and the library is loaded using that pathname.

       If a library dependency does not contain a slash, then it is searched for
       in the following order:

       o  (ELF only) Using the directories specified in the DT_RPATH dynamic
          section attribute of the binary if present and DT_RUNPATH attribute does
          not exist.  Use of DT_RPATH is deprecated.

       o  Using the environment variable LD_LIBRARY_PATH.  Except if the
          executable is a set-user-ID/set-group-ID binary, in which case it is
          ignored.

       o  (ELF only) Using the directories specified in the DT_RUNPATH dynamic
          section attribute of the binary if present.

       o  From the cache file /etc/ld.so.cache, which contains a compiled list of
          candidate libraries previously found in the augmented library path.  If,
          however, the binary was linked with the -z nodeflib linker option,
          libraries in the default library paths are skipped.  Libraries installed
          in hardware capability directories (see below) are preferred to other
          libraries.

       o  In the default path /lib, and then /usr/lib.  If the binary was linked
          with the -z nodeflib linker option, this step is skipped.

$ORIGIN and rpath

       ld.so understands the string $ORIGIN (or equivalently ${ORIGIN}) in an
       rpath specification (DT_RPATH or DT_RUNPATH) to mean the directory
       containing the application executable.  Thus, an application located in
       somedir/app could be compiled with gcc -Wl,-rpath,'$ORIGIN/../lib' so that
       it finds an associated shared library in somedir/lib no matter where
       somedir is located in the directory hierarchy.  This facilitates the
       creation of "turn-key" applications that do not need to be installed into
       special directories, but can instead be unpacked into any directory and
       still find their own shared libraries.

OPTIONS top

       --list List all dependencies and how they are resolved.

       --verify
              Verify that program is dynamically linked and this dynamic linker
              can handle it.

       --library-path PATH
              Use PATH instead of LD_LIBRARY_PATH environment variable setting
              (see below).

       --inhibit-rpath LIST
              Ignore RPATH and RUNPATH information in object names in LIST.  This
              option is ignored if ld.so is set-user-ID or set-group-ID.

       --audit LIST
              Use objects named in LIST as auditors.

HARDWARE CAPABILITIES top

       Some libraries are compiled using hardware-specific instructions which do
       not exist on every CPU.  Such libraries should be installed in directories
       whose names define the required hardware capabilities, such as
       /usr/lib/sse2/.  The dynamic linker checks these directories against the
       hardware of the machine and selects the most suitable version of a given
       library.  Hardware capability directories can be cascaded to combine CPU
       features.  The list of supported hardware capability names depends on the
       CPU.  The following names are currently recognized:

       Alpha  ev4, ev5, ev56, ev6, ev67

       MIPS   loongson2e, loongson2f, octeon, octeon2

       PowerPC
              4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp,
              efpdouble, efpsingle, fpu, ic_snoop, mmu, notb, pa6t, power4,
              power5, power5+, power6x, ppc32, ppc601, ppc64, smt, spe, ucache,
              vsx

       SPARC  flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2

       s390   dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
              z900, z990, z9-109, z10, zarch

       x86 (32-bit only)
              acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486,
              i586, i686, mca, mmx, mtrr, pat, pbe, pge, pn, pse36, sep,
              ss, sse, sse2, tm

ENVIRONMENT top

       There are four important environment variables.

       LD_BIND_NOW
              (libc5; glibc since 2.1.1) If set to a nonempty string,
              causes the dynamic linker to resolve all symbols at program
              startup instead of deferring function call resolution to the
              point when they are first referenced.  This is useful when
              using a debugger.

       LD_LIBRARY_PATH
              A colon-separated list of directories in which to search for
              ELF libraries at execution-time.  Similar to the PATH
              environment variable.  Ignored in set-user-ID and set-group-
              ID programs.

       LD_PRELOAD
              A list of additional, user-specified, ELF shared libraries to
              be loaded before all others.  The items of the list can be
              separated by spaces or colons.  This can be used to
              selectively override functions in other shared libraries.
              The libraries are searched for using the rules given under
              DESCRIPTION.  For set-user-ID/set-group-ID ELF binaries,
              preload pathnames containing slashes are ignored, and
              libraries in the standard search directories are loaded only
              if the set-user-ID permission bit is enabled on the library
              file.

       LD_TRACE_LOADED_OBJECTS
              (ELF only) If set to a nonempty string, causes the program to
              list its dynamic library dependencies, as if run by ldd(1),
              instead of running normally.

       Then there are lots of more or less obscure variables, many obsolete
       or only for internal use.

       LD_AOUT_LIBRARY_PATH
              (libc5) Version of LD_LIBRARY_PATH for a.out binaries only.
              Old versions of ld-linux.so.1 also supported
              LD_ELF_LIBRARY_PATH.

       LD_AOUT_PRELOAD
              (libc5) Version of LD_PRELOAD for a.out binaries only.  Old
              versions of ld-linux.so.1 also supported LD_ELF_PRELOAD.

       LD_AUDIT
              (glibc since 2.4) A colon-separated list of user-specified,
              ELF shared objects to be loaded before all others in a
              separate linker namespace (i.e., one that does not intrude
              upon the normal symbol bindings that would occur in the
              process).  These libraries can be used to audit the operation
              of the dynamic linker.  LD_AUDIT is ignored for set-user-
              ID/set-group-ID binaries.

              The dynamic linker will notify the audit libraries at so-
              called auditing checkpoints--for example, loading a new
              library, resolving a symbol, or calling a symbol from another
              shared object--by calling an appropriate function within the
              audit library.  For details, see rtld-audit(7).  The auditing
              interface is largely compatible with that provided on
              Solaris, as described in its Linker and Libraries Guide, in
              the chapter Runtime Linker Auditing Interface.

       LD_BIND_NOT
              (glibc since 2.1.95) Do not update the GOT (global offset
              table) and PLT (procedure linkage table) after resolving a
              symbol.

       LD_DEBUG
              (glibc since 2.1) Output verbose debugging information about
              the dynamic linker.  If set to all prints all debugging
              information it has, if set to help prints a help message
              about which categories can be specified in this environment
              variable.  Since glibc 2.3.4, LD_DEBUG is ignored for set-
              user-ID/set-group-ID binaries.

       LD_DEBUG_OUTPUT
              (glibc since 2.1) File where LD_DEBUG output should be fed
              into, default is standard output.  LD_DEBUG_OUTPUT is ignored
              for set-user-ID/set-group-ID binaries.

       LD_DYNAMIC_WEAK
              (glibc since 2.1.91) Allow weak symbols to be overridden
              (reverting to old glibc behavior).  For security reasons,
              since glibc 2.3.4, LD_DYNAMIC_WEAK is ignored for set-user-
              ID/set-group-ID binaries.

       LD_HWCAP_MASK
              (glibc since 2.1) Mask for hardware capabilities.

       LD_KEEPDIR
              (a.out only)(libc5) Don't ignore the directory in the names
              of a.out libraries to be loaded.  Use of this option is
              strongly discouraged.

       LD_NOWARN
              (a.out only)(libc5) Suppress warnings about a.out libraries
              with incompatible minor version numbers.

       LD_ORIGIN_PATH
              (glibc since 2.1) Path where the binary is found (for non-
              set-user-ID programs).  For security reasons, since glibc
              2.4, LD_ORIGIN_PATH is ignored for set-user-ID/set-group-ID
              binaries.

       LD_POINTER_GUARD
              (glibc since 2.4) Set to 0 to disable pointer guarding.  Any
              other value enables pointer guarding, which is also the
              default.  Pointer guarding is a security mechanism whereby
              some pointers to code stored in writable program memory
              (return addresses saved by setjmp(3) or function pointers
              used by various glibc internals) are mangled semi-randomly to
              make it more difficult for an attacker to hijack the pointers
              for use in the event of a buffer overrun or stack-smashing
              attack.

       LD_PROFILE
              (glibc since 2.1) Shared object to be profiled, specified
              either as a pathname or a soname.  Profiling output is
              written to the file whose name is:
              "$LD_PROFILE_OUTPUT/$LD_PROFILE.profile".

       LD_PROFILE_OUTPUT
              (glibc since 2.1) Directory where LD_PROFILE output should be
              written.  If this variable is not defined, or is defined as
              an empty string, then the default is /var/tmp.
              LD_PROFILE_OUTPUT is ignored for set-user-ID and set-group-ID
              programs, which always use /var/profile.

       LD_SHOW_AUXV
              (glibc since 2.1) Show auxiliary array passed up from the
              kernel.  For security reasons, since glibc 2.3.5,
              LD_SHOW_AUXV is ignored for set-user-ID/set-group-ID
              binaries.

       LD_USE_LOAD_BIAS
              By default (i.e., if this variable is not defined)
              executables and prelinked shared objects will honor base
              addresses of their dependent libraries and (nonprelinked)
              position-independent executables (PIEs) and other shared
              objects will not honor them.  If LD_USE_LOAD_BIAS is defined
              wit the value, both executables and PIEs will honor the base
              addresses.  If LD_USE_LOAD_BIAS is defined with the value 0,
              neither executables nor PIEs will honor the base addresses.
              This variable is ignored by set-user-ID and set-group-ID
              programs.

       LD_VERBOSE
              (glibc since 2.1) If set to a nonempty string, output symbol
              versioning information about the program if querying
              information about the program (i.e., either
              LD_TRACE_LOADED_OBJECTS has been set, or --list or --verify
              options have been given to the dynamic linker).

       LD_WARN
              (ELF only)(glibc since 2.1.3) If set to a nonempty string,
              warn about unresolved symbols.

       LDD_ARGV0
              (libc5) argv[0] to be used by ldd(1) when none is present.

FILES top

       /lib/ld.so
              a.out dynamic linker/loader
       /lib/ld-linux.so.{1,2}
              ELF dynamic linker/loader
       /etc/ld.so.cache
              File containing a compiled list of directories in which to
              search for libraries and an ordered list of candidate
              libraries.
       /etc/ld.so.preload
              File containing a whitespace-separated list of ELF shared
              libraries to be loaded before the program.
       lib*.so*
              shared libraries

NOTES top

       The ld.so functionality is available for executables compiled using
       libc version 4.4.3 or greater.  ELF functionality is available since
       Linux 1.1.52 and libc5.

SEE ALSO top

       ldd(1), getauxval(3), rtld-audit(7), ldconfig(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-26                            LD.SO(8)


ldconfig(8) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

LDCONFIG(8)                  Linux Programmer's Manual                 LDCONFIG(8)

NAME top

       ldconfig - configure dynamic linker run-time bindings

SYNOPSIS top

       /sbin/ldconfig  [  -nNvXV  ]  [  -f conf  ] [ -C cache ] [ -r root ] direc-
       tory ...
       /sbin/ldconfig -l [ -v ] library ...
       /sbin/ldconfig -p

DESCRIPTION top

       ldconfig creates the necessary links and cache to the most recent shared
       libraries found in the directories specified on the command line, in the
       file /etc/ld.so.conf, and in the trusted directories (/lib and /usr/lib).
       The cache is used by the run-time linker, ld.so or ld-linux.so.  ldconfig
       checks the header and filenames of the libraries it encounters when
       determining which versions should have their links updated.

       ldconfig will attempt to deduce the type of ELF libs (i.e., libc5 or
       libc6/glibc) based on what C libs, if any, the library was linked against.

       Some existing libs do not contain enough information to allow the deduction
       of their type.  Therefore, the /etc/ld.so.conf file format allows the
       specification of an expected type.  This is only used for those ELF libs
       which we can not work out.  The format is "dirname=TYPE", where TYPE can be
       libc4, libc5, or libc6.  (This syntax also works on the command line.)
       Spaces are not allowed.  Also see the -p option.  ldconfig should normally
       be run by the superuser as it may require write permission on some root
       owned directories and files.

OPTIONS top

       -v     Verbose mode.  Print current version number, the name of each
              directory as it is scanned, and any links that are created.
              Overrides quiet mode.

       -n     Only process directories specified on the command line.  Don't
              process the trusted directories (/lib and /usr/lib) nor those
              specified in /etc/ld.so.conf.  Implies -N.

       -N     Don't rebuild the cache.  Unless -X is also specified, links are
              still updated.

       -X     Don't update links.  Unless -N is also specified, the cache is still
              rebuilt.

       -f conf
              Use conf instead of /etc/ld.so.conf.

       -C cache
              Use cache instead of /etc/ld.so.cache.

       -r root
              Change to and use root as the root directory.

       -l     Library mode.  Manually link individual libraries.  Intended for use
              by experts only.

       -p     Print the lists of directories and candidate libraries stored in the
              current cache.

FILES top

       /lib/ld.so          run-time linker/loader
       /etc/ld.so.conf     File containing a list of colon, space, tab, newline,
                           or comma-separated directories in which to search for
                           libraries.
       /etc/ld.so.cache    File containing an ordered list of libraries found in
                           the directories specified in /etc/ld.so.conf, as well
                           as those found in /lib and /usr/lib.

SEE ALSO top

       ldd(1), ld.so(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                         LDCONFIG(8)


ldd(1) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LDD(1)                       Linux Programmer's Manual                      LDD(1)

NAME top

       ldd - print shared library dependencies

SYNOPSIS top

       ldd [OPTION]... FILE...

DESCRIPTION top

       ldd prints the shared libraries required by each program or shared library
       specified on the command line.

Security

       In the usual case, ldd invokes the standard dynamic linker (see ld.so(8))
       with the LD_TRACE_LOADED_OBJECTS environment variable set to 1, which
       causes the linker to display the library dependencies.  Be aware, however,
       that in some circumstances, some versions of ldd may attempt to obtain the
       dependency information by directly executing the program.  Thus, you should
       never employ ldd on an untrusted executable, since this may result in the
       execution of arbitrary code.  A safer alternative when dealing with
       untrusted executables is:

           $ objdump -p /path/to/program | grep NEEDED

OPTIONS top

       --version
              Print the version number of ldd.

       -v --verbose
              Print all information, including, for example, symbol versioning
              information.

       -u --unused
              Print unused direct dependencies.  (Since glibc 2.3.4.)

       -d --data-relocs
              Perform relocations and report any missing objects (ELF only).

       -r --function-relocs
              Perform relocations for both data objects and functions, and report
              any missing objects or functions (ELF only).

       --help Usage information.

NOTES top

       The standard version of ldd comes with glibc2.  Libc5 came with an older
       version, still present on some systems.  The long options are not supported
       by the libc5 version.  On the other hand, the glibc2 version does not
       support -V and only has the equivalent --version.

       The libc5 version of this program will use the name of a library given on
       the command line as-is when it contains a '/'; otherwise it searches for
       the library in the standard locations.  To run it on a shared library in
       the current directory, prefix the name with "./".

BUGS top

       ldd does not work on a.out shared libraries.

       ldd does not work with some extremely old a.out programs which were built
       before ldd support was added to the compiler releases.  If you use ldd on
       one of these programs, the program will attempt to run with argc = 0 and
       the results will be unpredictable.

SEE ALSO top

       ld.so(8), ldconfig(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-07-16                              LDD(1)


ldexp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LDEXP(3)                     Linux Programmer's Manual                    LDEXP(3)

NAME top

       ldexp, ldexpf, ldexpl - multiply floating-point number by integral power of
       2

SYNOPSIS top

       #include <math.h>

       double ldexp(double x, int exp);
       float ldexpf(float x, int exp);
       long double ldexpl(long double x, int exp);

       Link with -lm.

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

       ldexpf(), ldexpl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The ldexp() function returns the result of multiplying the floating-point
       number x by 2 raised to the power exp.

RETURN VALUE top

       On success, these functions return x * (2^exp).

       If exp is zero, then x is returned.

       If x is a NaN, a NaN is returned.

       If x is positive infinity (negative infinity), positive infinity (negative
       infinity) is returned.

       If the result underflows, a range error occurs, and zero is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with a sign the same as x.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error, overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

       Range error, underflow
              errno is set to ERANGE.  An underflow floating-point exception
              (FE_UNDERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       frexp(3), modf(3), scalbln(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            LDEXP(3)


lsearch(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LSEARCH(3)                   Linux Programmer's Manual                  LSEARCH(3)

NAME top

       lfind, lsearch - linear search of an array

SYNOPSIS top

       #include <search.h>

       void *lfind(const void *key, const void *base, size_t *nmemb,
                size_t size, int(*compar)(const void *, const void *));

       void *lsearch(const void *key, void *base, size_t *nmemb,
                size_t size, int(*compar)(const void *, const void *));

DESCRIPTION top

       lfind() and lsearch() perform a linear search for key in the array base
       which has *nmemb elements of size bytes each.  The comparison function
       referenced by compar is expected to have two arguments which point to the
       key object and to an array member, in that order, and which returns zero if
       the key object matches the array member, and nonzero otherwise.

       If lsearch() does not find a matching element, then the key object is
       inserted at the end of the table, and *nmemb is incremented.  In
       particular, one should know that a matching element exists, or that more
       room is available.

RETURN VALUE top

       lfind() returns a pointer to a matching member of the array, or NULL if no
       match is found.  lsearch() returns a pointer to a matching member of the
       array, or to the newly added member if no match is found.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  Present in libc since libc-4.6.27.

BUGS top

       The naming is unfortunate.

SEE ALSO top

       bsearch(3), hsearch(3), tsearch(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-09-27                          LSEARCH(3)


lgamma(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LGAMMA(3)                    Linux Programmer's Manual                   LGAMMA(3)

NAME top

       lgamma,  lgammaf,  lgammal,  lgamma_r,  lgammaf_r, lgammal_r, signgam - log
       gamma function

SYNOPSIS top

       #include <math.h>

       double lgamma(double x);
       float lgammaf(float x);
       long double lgammal(long double x);

       double lgamma_r(double x, int *signp);
       float lgammaf_r(float x, int *signp);
       long double lgammal_r(long double x, int *signp);

       extern int signgam;

       Link with -lm.

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

       lgamma():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       lgammaf(), lgammal():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       lgamma_r(), lgammaf_r(), lgammal_r():
           _BSD_SOURCE || _SVID_SOURCE
       signgam:
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       For the definition of the Gamma function, see tgamma(3).

       The lgamma() function returns the natural logarithm of the absolute value
       of the Gamma function.  The sign of the Gamma function is returned in the
       external integer signgam declared in <math.h>.  It is 1 when the Gamma
       function is positive or zero, -1 when it is negative.

       Since using a constant location signgam is not thread-safe, the functions
       lgamma_r() etc. have been introduced; they return the sign via the argument
       signp.

RETURN VALUE top

       On success, these functions return the natural logarithm of Gamma(x).

       If x is a NaN, a NaN is returned.

       If x is 1 or 2, +0 is returned.

       If x is positive infinity or negative infinity, positive infinity is
       returned.

       If x is a nonpositive integer, a pole error occurs, and the functions
       return +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL, respectively.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with the correct
       mathematical sign.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Pole error: x is a nonpositive integer
              errno is set to ERANGE (but see BUGS).  A divide-by-zero floating-
              point exception (FE_DIVBYZERO) is raised.

       Range error: result overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

CONFORMING TO top

       The lgamma() functions are specified in C99 and POSIX.1-2001.  signgam is
       specified in POSIX.1-2001, but not in C99.  The lgamma_r() functions are
       nonstandard, but present on several other systems.

BUGS top

       In glibc 2.9 and earlier, when a pole error occurs, errno is set to EDOM;
       instead of the POSIX-mandated ERANGE.  Since version 2.10, glibc does the
       right thing.

SEE ALSO top

       tgamma(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-11                           LGAMMA(3)


link(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LINK(2)                      Linux Programmer's Manual                     LINK(2)

NAME top

       link - make a new name for a file

SYNOPSIS top

       #include <unistd.h>

       int link(const char *oldpath, const char *newpath);

DESCRIPTION top

       link() creates a new link (also known as a hard link) to an existing file.

       If newpath exists it will not be overwritten.

       This new name may be used exactly as the old one for any operation; both
       names refer to the same file (and so have the same permissions and
       ownership) and it is impossible to tell which name was the "original".

RETURN VALUE top

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

ERRORS top

       EACCES Write access to the directory containing newpath is denied, or
              search permission is denied for one of the directories in the path
              prefix of oldpath or newpath.  (See also path_resolution(7).)

       EEXIST newpath already exists.

       EFAULT oldpath or newpath points outside your accessible address space.

       EIO    An I/O error occurred.

       ELOOP  Too many symbolic links were encountered in resolving oldpath or
              newpath.

       EMLINK The file referred to by oldpath already has the maximum number of
              links to it.

       ENAMETOOLONG
              oldpath or newpath was too long.

       ENOENT A directory component in oldpath or newpath does not exist or is a
              dangling symbolic link.

       ENOMEM Insufficient kernel memory was available.

       ENOSPC The device containing the file has no room for the new directory
              entry.

       ENOTDIR
              A component used as a directory in oldpath or newpath is not, in
              fact, a directory.

       EPERM  oldpath is a directory.

       EPERM  The file system containing oldpath and newpath does not support the
              creation of hard links.

       EPERM (since Linux 3.6)
              The caller does not have permission to create a hard link to this
              file (see the description of /proc/sys/fs/protected_hardlink in
              proc(5)).

       EROFS  The file is on a read-only file system.

       EXDEV  oldpath and newpath are not on the same mounted file system.  (Linux
              permits a file system to be mounted at multiple points, but link()
              does not work across different mount points, even if the same file
              system is mounted on both.)

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES).

NOTES top

       Hard links, as created by link(), cannot span file systems.  Use symlink(2)
       if this is required.

       POSIX.1-2001 says that link() should dereference oldpath if it is a
       symbolic link.  However, since kernel 2.0, Linux does not do so: if oldpath
       is a symbolic link, then newpath is created as a (hard) link to the same
       symbolic link file (i.e., newpath becomes a symbolic link to the same file
       that oldpath refers to).  Some other implementations behave in the same
       manner as Linux.  POSIX.1-2008 changes the specification of link(), making
       it implementation-dependent whether or not oldpath is dereferenced if it is
       a symbolic link.  For precise control over the treatment of symbolic links
       when creating a link, see linkat(2).

BUGS top

       On NFS file systems, the return code may be wrong in case the NFS server
       performs the link creation and dies before it can say so.  Use stat(2) to
       find out if the link got created.

SEE ALSO top

       ln(1), linkat(2), open(2), rename(2), stat(2), symlink(2), unlink(2),
       path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-16                             LINK(2)


linkat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LINKAT(2)                    Linux Programmer's Manual                   LINKAT(2)

NAME top

       linkat - create a file link relative to directory file descriptors

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <unistd.h>

       int linkat(int olddirfd, const char *oldpath,
                  int newdirfd, const char *newpath, int flags);

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

       linkat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The linkat() system call operates in exactly the same way as link(2),
       except for the differences described in this manual page.

       If the pathname given in oldpath is relative, then it is interpreted
       relative to the directory referred to by the file descriptor olddirfd
       (rather than relative to the current working directory of the calling
       process, as is done by link(2) for a relative pathname).

       If oldpath is relative and olddirfd is the special value AT_FDCWD, then
       oldpath is interpreted relative to the current working directory of the
       calling process (like link(2)).

       If oldpath is absolute, then olddirfd is ignored.

       The interpretation of newpath is as for oldpath, except that a relative
       pathname is interpreted relative to the directory referred to by the file
       descriptor newdirfd.

       By default, linkat(), does not dereference oldpath if it is a symbolic link
       (like link(2)).  Since Linux 2.6.18, the flag AT_SYMLINK_FOLLOW can be
       specified in flags to cause oldpath to be dereferenced if it is a symbolic
       link.  Before kernel 2.6.18, the flags argument was unused, and had to be
       specified as 0.

RETURN VALUE top

       On success, linkat() returns 0.  On error, -1 is returned and errno is set
       to indicate the error.

ERRORS top

       The same errors that occur for link(2) can also occur for linkat().  The
       following additional errors can occur for linkat():

       EBADF  olddirfd or newdirfd is not a valid file descriptor.

       ENOTDIR
              oldpath is relative and olddirfd is a file descriptor referring to a
              file other than a directory; or similar for newpath and newdirfd

VERSIONS top

       linkat() was added to Linux in kernel 2.6.16; library support was added to
       glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for linkat().

SEE ALSO top

       link(2), openat(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                           LINKAT(2)


lio_listio(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LIO_LISTIO(3)                Linux Programmer's Manual               LIO_LISTIO(3)

NAME top

       lio_listio - initiate a list of I/O requests

SYNOPSIS top

       #include <aio.h>

       int lio_listio(int mode, struct aiocb *const aiocb_list[],
                      int nitems, struct sigevent *sevp);

       Link with -lrt.

DESCRIPTION top

       The lio_listio() function initiates the list of I/O operations described by
       the array aiocb_list.

       The mode operation has one of the following values:

       LIO_WAIT    The call blocks until all operations are complete.  The sevp
                   argument is ignored.

       LIO_NOWAIT  The I/O operations are queued for processing and the call
                   returns immediately.  When all of the I/O operations complete,
                   asynchronous notification occurs, as specified by the sevp
                   argument; see sigevent(7) for details.  If sevp is NULL, no
                   asynchronous notification occurs.

       The aiocb_list argument is an array of pointers to aiocb structures that
       describe I/O operations.  These operations are executed in an unspecified
       order.  The nitems argument specifies the size of the array aiocb_list.
       NULL pointers in aiocb_list are ignored.

       In each control block in aiocb_list, the aio_lio_opcode field specifies the
       I/O operation to be initiated, as follows:

       LIO_READ  Initiate a read operation.  The operation is queued as for a call
                 to aio_read(3) specifying this control block.

       LIO_WRITE Initiate a write operation.  The operation is queued as for a
                 call to aio_write(3) specifying this control block.

       LIO_NOP   Ignore this control block.

       The remaining fields in each control block have the same meanings as for
       aio_read(3) and aio_write(3).  The aio_sigevent fields of each control
       block can be used to specify notifications for the individual I/O
       operations (see sigevent(7)).

RETURN VALUE top

       If mode is LIO_NOWAIT, lio_listio() returns 0 if all I/O operations are
       successfully queued.  Otherwise, -1 is returned, and errno is set to
       indicate the error.

       If mode is LIO_WAIT, lio_listio() returns 0 when all of the I/O operations
       have completed successfully.  Otherwise, -1 is returned, and errno is set
       to indicate the error.

       The return status from lio_listio() provides information only about the
       call itself, not about the individual I/O operations.  One or more of the
       I/O operations may fail, but this does not prevent other operations
       completing.  The status of individual I/O operations in aiocb_list can be
       determined using aio_error(3).  When an operation has completed, its return
       status can be obtained using aio_return(3).  Individual I/O operations can
       fail for the reasons described in aio_read(3) and aio_write(3).

ERRORS top

       The lio_listio() function may fail for the following reasons:

       EAGAIN Out of resources.

       EAGAIN The number of I/O operations specified by nitems would cause the
              limit AIO_MAX to be exceeded.

       EINVAL mode is invalid, or nitems exceeds the limit AIO_LISTIO_MAX.

       EINTR  mode was LIO_WAIT and a signal was caught before all I/O operations
              completed.  (This may even be one of the signals used for
              asynchronous I/O completion notification.)

       EIO    One of more of the operations specified by aiocb_list failed.  The
              application can check the status of each operation using
              aio_return(3).

       If lio_listio() fails with the error EAGAIN, EINTR, or EIO, then some of
       the operations in aiocb_list may have been initiated.  If lio_listio()
       fails for any other reason, then none of the I/O operations has been
       initiated.

VERSIONS top

       The lio_listio() function is available since glibc 2.1.

CONFORMING TO top

       POSIX.1-2001, POSIX.1-2008.

NOTES top

       It is a good idea to zero out the control blocks before use.  The control
       blocks must not be changed while the I/O operations are in progress.  The
       buffer areas being read into or written from must not be accessed during
       the operations or undefined results may occur.  The memory areas involved
       must remain valid.

       Simultaneous I/O operations specifying the same aiocb structure produce
       undefined results.

SEE ALSO top

       aio_cancel(3), aio_error(3), aio_fsync(3), aio_return(3), aio_suspend(3),
       aio_write(3), aio(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-08                       LIO_LISTIO(3)


listen(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

LISTEN(2)                    Linux Programmer's Manual                   LISTEN(2)

NAME top

       listen - listen for connections on a socket

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int listen(int sockfd, int backlog);

DESCRIPTION top

       listen() marks the socket referred to by sockfd as a passive socket, that
       is, as a socket that will be used to accept incoming connection requests
       using accept(2).

       The sockfd argument is a file descriptor that refers to a socket of type
       SOCK_STREAM or SOCK_SEQPACKET.

       The backlog argument defines the maximum length to which the queue of
       pending connections for sockfd may grow.  If a connection request arrives
       when the queue is full, the client may receive an error with an indication
       of ECONNREFUSED or, if the underlying protocol supports retransmission, the
       request may be ignored so that a later reattempt at connection succeeds.

RETURN VALUE top

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

ERRORS top

       EADDRINUSE
              Another socket is already listening on the same port.

       EBADF  The argument sockfd is not a valid descriptor.

       ENOTSOCK
              The argument sockfd is not a socket.

       EOPNOTSUPP
              The socket is not of a type that supports the listen() operation.

CONFORMING TO top

       4.4BSD, POSIX.1-2001.  The listen() function call first appeared in 4.2BSD.

NOTES top

       To accept connections, the following steps are performed:

           1.  A socket is created with socket(2).

           2.  The socket is bound to a local address using bind(2), so that other
               sockets may be connect(2)ed to it.

           3.  A willingness to accept incoming connections and a queue limit for
               incoming connections are specified with listen().

           4.  Connections are accepted with accept(2).

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

       The behavior of the backlog argument on TCP sockets changed with Linux 2.2.
       Now it specifies the queue length for completely established sockets
       waiting to be accepted, instead of the number of incomplete connection
       requests.  The maximum length of the queue for incomplete sockets can be
       set using /proc/sys/net/ipv4/tcp_max_syn_backlog.  When syncookies are
       enabled there is no logical maximum length and this setting is ignored.
       See tcp(7) for more information.

       If the backlog argument is greater than the value in
       /proc/sys/net/core/somaxconn, then it is silently truncated to that value;
       the default value in this file is 128.  In kernels before 2.4.25, this
       limit was a hard coded value, SOMAXCONN, with the value 128.

EXAMPLE top

       See bind(2).

SEE ALSO top

       accept(2), bind(2), connect(2), socket(2), socket(7)

COLOPHON top

       This page is part of release 3.45 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-20                           LISTEN(2)


lrint(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LRINT(3)                     Linux Programmer's Manual                    LRINT(3)

NAME top

       lrint, lrintf, lrintl, llrint, llrintf, llrintl - round to nearest integer

SYNOPSIS top

       #include <math.h>

       long int lrint(double x);
       long int lrintf(float x);
       long int lrintl(long double x);

       long long int llrint(double x);
       long long int llrintf(float x);
       long long int llrintl(long double x);

       Link with -lm.

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

       All functions shown above:
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions round their argument to the nearest integer value, using
       the current rounding direction (see fesetround(3)).

       Note that unlike rint(3), etc., the return type of these functions differs
       from that of their arguments.

RETURN VALUE top

       These functions return the rounded integer value.

       If x is a NaN or an infinity, or the rounded value is too large to be
       stored in a long (long long in the case of the ll* functions) then a domain
       error occurs, and the return value is unspecified.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is a NaN or infinite, or the rounded value is too large
              An invalid floating-point exception (FE_INVALID) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       ceil(3), floor(3), lround(3), nearbyint(3), rint(3), round(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            LRINT(3)


lround(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LROUND(3)                    Linux Programmer's Manual                   LROUND(3)

NAME top

       lround,  lroundf,  lroundl,  llround, llroundf, llroundl - round to nearest
       integer, away from zero

SYNOPSIS top

       #include <math.h>

       long int lround(double x);
       long int lroundf(float x);
       long int lroundl(long double x);

       long long int llround(double x);
       long long int llroundf(float x);
       long long int llroundl(long double x);

       Link with -lm.

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

       All functions shown above:
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions round their argument to the nearest integer value, rounding
       away from zero, regardless of the current rounding direction (see fenv(3)).

       Note that unlike round(3), ceil(3), etc., the return type of these
       functions differs from that of their arguments.

RETURN VALUE top

       These functions return the rounded integer value.

       If x is a NaN or an infinity, or the rounded value is too large to be
       stored in a long (long long in the case of the ll* functions) then a domain
       error occurs, and the return value is unspecified.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is a NaN or infinite, or the rounded value is too large
              An invalid floating-point exception (FE_INVALID) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       ceil(3), floor(3), lrint(3), nearbyint(3), rint(3), round(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                           LROUND(3)


llseek(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LLSEEK(2)                    Linux Programmer's Manual                   LLSEEK(2)

NAME top

       _llseek - reposition read/write file offset

SYNOPSIS top

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

       int _llseek(unsigned int fd, unsigned long offset_high,
                   unsigned long offset_low, loff_t *result,
                   unsigned int whence);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The _llseek() function repositions the offset of the open file associated
       with the file descriptor fd to (offset_high<<32) | offset_low bytes
       relative to the beginning of the file, the current position in the file, or
       the end of the file, depending on whether whence is SEEK_SET, SEEK_CUR, or
       SEEK_END, respectively.  It returns the resulting file position in the
       argument result.

RETURN VALUE top

       Upon successful completion, _llseek() returns 0.  Otherwise, a value of -1
       is returned and errno is set to indicate the error.

ERRORS top

       EBADF  fd is not an open file descriptor.

       EFAULT Problem with copying results to user space.

       EINVAL whence is invalid.

CONFORMING TO top

       This function is Linux-specific, and should not be used in programs
       intended to be portable.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

SEE ALSO top

       lseek(2), lseek64(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                           LLSEEK(2)


locale(5) - Linux manual page

NAME | DESCRIPTION | FILES | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LOCALE(5)                        Linux User Manual                       LOCALE(5)

NAME top

       locale - describes a locale definition file

DESCRIPTION top

       The locale definition files contains all the information that the
       localedef(1) command needs to convert it into the binary locale database.

       The definition files consist of sections which each describe a locale
       category in detail.

Syntax

       The locale definition file starts with a header that may consist of the
       following keywords:

       <escape_char>
              is followed by a character that should be used as the escape-
              character for the rest of the file to mark characters that should be
              interpreted in a special way.  It defaults to the backslash (\).

       <comment_char>
              is followed by a character that will be used as the comment-
              character for the rest of the file.  It defaults to the number sign
              (#).

       The locale definition has one part for each locale category.  Each part can
       be copied from another existing locale or can be defined from scratch.  If
       the category should be copied, the only valid keyword in the definition is
       copy followed by the name of the locale which should be copied.

LC_CTYPE

       The definition for the LC_CTYPE category starts with the string LC_CTYPE in
       the first column.

       There are the following keywords allowed:

       upper  followed by a list of uppercase letters.  The letters A through Z
              are included automatically.  Characters also specified as cntrl,
              digit, punct, or space are not allowed.

       lower  followed by a list of lowercase letters.  The letters a through z
              are included automatically.  Characters also specified as cntrl,
              digit, punct, or space are not allowed.

       alpha  followed by a list of letters.  All character specified as either
              upper or lower are automatically included.  Characters also
              specified as cntrl, digit, punct, or space are not allowed.

       digit  followed by the characters classified as numeric digits.  Only the
              digits 0 through 9 are allowed.  They are included by default in
              this class.

       space  followed by a list of characters defined as white-space characters.
              Characters also specified as upper, lower, alpha, digit, graph, or
              xdigit are not allowed.  The characters <space>, <form-feed>,
              <newline>, <carriage-return>, <tab>, and <vertical-tab> are
              automatically included.

       cntrl  followed by a list of control characters.  Characters also specified
              as upper, lower, alpha, digit, punct, graph, print, or xdigit are
              not allowed.

       punct  followed by a list of punctuation characters.  Characters also
              specified as upper, lower, alpha, digit, cntrl, xdigit, or the
              <space> character are not allowed.

       graph  followed by a list of printable characters, not including the
              <space> character.  The characters defined as upper, lower, alpha,
              digit, xdigit, and punct are automatically included.  Characters
              also specified as cntrl are not allowed.

       print  followed by a list of printable characters, including the <space>
              character.  The characters defined as upper, lower, alpha, digit,
              xdigit, punct, and the <space> character are automatically included.
              Characters also specified as cntrl are not allowed.

       xdigit followed by a list of characters classified as hexadecimal digits.
              The decimal digits must be included followed by one or more set of
              six characters in ascending order.  The following characters are
              included by default: 0 through 9, a through f, A through F.

       blank  followed by a list of characters classified as blank.  The
              characters <space> and <tab> are automatically included.

       toupper
              followed by a list of mappings from lowercase to uppercase letters.
              Each mapping is a pair of a lowercase and an uppercase letter
              separated with a , and enclosed in parentheses.  The members of the
              list are separated with semicolons.

       tolower
              followed by a list of mappings from uppercase to lowercase letters.
              If the keyword tolower is not present, the reverse of the toupper
              list is used.

       The LC_CTYPE definition ends with the string END LC_CYTPE.

LC_COLLATE

       The LC_COLLATE category defines the rules for collating characters.  Due to
       limitations of libc not all POSIX-options are implemented.

       The definition starts with the string LC_COLLATE in the first column.

       There are the following keywords allowed:

       collating-element

       collating-symbol

       The order-definition starts with a line:

       order_start

       followed by a list of keywords out of forward, backward, or position.  The
       order definition consists of lines that describe the order and is
       terminated with the keyword

       order_end.

       For more details see the sources in /usr/lib/nls/src notably the examples
       POSIX, Example and Example2

       The LC_COLLATE definition ends with the string END LC_COLLATE.

LC_MONETARY

       The definition starts with the string LC_MONETARY in the first column.

       There are the following keywords allowed:

       int_curr_symbol
              followed by the international currency symbol.  This must be a
              4-character string containing the international currency symbol as
              defined by the ISO 4217 standard (three characters) followed by a
              separator.

       currency_symbol
              followed by the local currency symbol.

       mon_decimal_point
              followed by the string that will be used as the decimal delimiter
              when formatting monetary quantities.

       mon_thousands_sep
              followed by the string that will be used as a group separator when
              formatting monetary quantities.

       mon_grouping
              followed by a string that describes the formatting of numeric
              quantities.

       positive_sign
              followed by a string that is used to indicate a positive sign for
              monetary quantities.

       negative_sign
              followed by a string that is used to indicate a negative sign for
              monetary quantities.

       int_frac_digits
              followed by the number of fractional digits that should be used when
              formatting with the int_curr_symbol.

       frac_digits
              followed by the number of fractional digits that should be used when
              formatting with the currency_symbol.

       p_cs_precedes
              followed by an integer set to 1 if the currency_symbol or
              int_curr_symbol should precede the formatted monetary quantity or
              set to 0 if the symbol succeeds the value.

       p_sep_by_space
              followed by an integer.

              0      means that no space should be printed between the symbol and
                     the value.

              1      means that a space should be printed between the symbol and
                     the value.

              2      means that a space should be printed between the symbol and
                     the sign string, if adjacent.

       n_cs_precedes

              0      - the symbol succeeds the value.

              1      - the symbol precedes the value.

       n_sep_by_space
              An integer set to 0 if no space separates the currency_symbol or
              int_curr_symbol from the value for a negative monetary quantity, set
              to 1 if a space separates the symbol from the value and set to 2 if
              a space separates the symbol and the sign string, if adjacent.

       p_sign_posn

              0      Parentheses enclose the quantity and the currency_symbol or
                     int_curr_symbol.

              1      The sign string precedes the quantity and the currency_symbol
                     or the int_curr_symbol.

              2      The sign string succeeds the quantity and the currency_symbol
                     or the int_curr_symbol.

              3      The sign string precedes the currency_symbol or the
                     int_curr_symbol.

              4      The sign string succeeds the currency_symbol or the
                     int_curr_symbol.

       n_sign_posn

              0      Parentheses enclose the quantity and the currency_symbol or
                     int_curr_symbol.

              1      The sign string precedes the quantity and the currency_symbol
                     or the int_curr_symbol.

              2      The sign string succeeds the quantity and the currency_symbol
                     or the int_curr_symbol.

              3      The sign string precedes the currency_symbol or the
                     int_curr_symbol.

              4      The sign string succeeds the currency_symbol or the
                     int_curr_symbol.

       The LC_MONETARY definition ends with the string END LC_MONETARY.

LC_NUMERIC

       The definition starts with the string LC_NUMERIC in the first column.

       The following keywords are allowed:

       decimal_point
              followed by the string that will be used as the decimal delimiter
              when formatting numeric quantities.

       thousands_sep
              followed by the string that will be used as a group separator when
              formatting numeric quantities.

       grouping
              followed by a string that describes the formatting of numeric
              quantities.

       The LC_NUMERIC definition ends with the string END LC_NUMERIC.

LC_TIME

       The definition starts with the string LC_TIME in the first column.

       The following keywords are allowed:

       abday  followed by a list of abbreviated weekday names.  The list starts
              with the first day of the week as specified by week (Sunday by
              default).

       day    followed by a list of weekday names.  The list starts with the first
              day of the week as specified by week (Sunday by default).

       abmon  followed by a list of abbreviated month names.

       mon    followed by a list of month names.

       am_pm  The appropriate representation of the am and pm strings.

       d_t_fmt
              The appropriate date and time format.

       d_fmt  The appropriate date format.

       t_fmt  The appropriate time format.

       t_fmt_ampm
              The appropriate time format when using 12h clock format.

       week   followed by a list of three values: The number of days in a week (by
              default 7), a date of beginning of the week (by default corresponds
              to Sunday), and the minimal length of the first week in year (by
              default 4).  Regarding the start of the week, 19971130 shall be used
              for Sunday and 19971201 shall be used for Monday.  Thus, countries
              using 19971130 should have local Sunday name as the first day in the
              day list, while countries using 19971201 should have Monday
              translation as the first item in the day list.

       first_weekday (since glibc 2.2)
              Number of the first day from the day list to be shown in calendar
              applications.  The default value of 1 corresponds to either Sunday
              or Monday depending on the value of the second week list item.

       first_workday (since glibc 2.2)
              Number of the first working day from the day list.

       The LC_TIME definition ends with the string END LC_TIME.

LC_MESSAGES

       The definition starts with the string LC_MESSAGES in the first column.

       The following keywords are allowed:

       yesexpr
              followed by a regular expression that describes possible yes-
              responses.

       noexpr followed by a regular expression that describes possible no-
              responses.

       The LC_MESSAGES definition ends with the string END LC_MESSAGES.

       See the POSIX.2 standard for details.

FILES top

       /usr/lib/locale/ -- database for the current locale setting of that
       category
       /usr/lib/nls/charmap/* -- charmap-files

CONFORMING TO top

       POSIX.2, ISO/IEC 14652.

BUGS top

       This manual page isn't complete.

SEE ALSO top

       locale(1), localedef(1), localeconv(3), setlocale(3), charmap(5)

COLOPHON top

       This page is part of release 3.45 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-06-17                           LOCALE(5)


locale(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LOCALE(7)                    Linux Programmer's Manual                   LOCALE(7)

NAME top

       locale - description of multilanguage support

SYNOPSIS top

       #include <locale.h>

DESCRIPTION top

       A locale is a set of language and cultural rules.  These cover aspects such
       as language for messages, different character sets, lexicographic
       conventions, and so on.  A program needs to be able to determine its locale
       and act accordingly to be portable to different cultures.

       The header <locale.h> declares data types, functions and macros which are
       useful in this task.

       The functions it declares are setlocale(3) to set the current locale, and
       localeconv(3) to get information about number formatting.

       There are different categories for local information a program might need;
       they are declared as macros.  Using them as the first argument to the
       setlocale(3) function, it is possible to set one of these to the desired
       locale:

       LC_COLLATE
              This is used to change the behavior of the functions strcoll(3) and
              strxfrm(3), which are used to compare strings in the local alphabet.
              For example, the German sharp s is sorted as "ss".

       LC_CTYPE
              This changes the behavior of the character handling and
              classification functions, such as isupper(3) and toupper(3), and the
              multibyte character functions such as mblen(3) or wctomb(3).

       LC_MONETARY
              changes the information returned by localeconv(3) which describes
              the way numbers are usually printed, with details such as decimal
              point versus decimal comma.  This information is internally used by
              the function strfmon(3).

       LC_MESSAGES
              changes the language messages are displayed in and what an
              affirmative or negative answer looks like.  The GNU C-library
              contains the gettext(3), ngettext(3), and rpmatch(3) functions to
              ease the use of these information.  The GNU gettext family of
              functions also obey the environment variable LANGUAGE (containing a
              colon-separated list of locales) if the category is set to a valid
              locale other than "C".

       LC_NUMERIC
              changes the information used by the printf(3) and scanf(3) family of
              functions, when they are advised to use the locale-settings.  This
              information can also be read with the localeconv(3) function.

       LC_TIME
              changes the behavior of the strftime(3) function to display the
              current time in a locally acceptable form; for example, most of
              Europe uses a 24-hour clock versus the 12-hour clock used in the
              United States.

       LC_ALL All of the above.

       If the second argument to setlocale(3) is empty string, "", for the default
       locale, it is determined using the following steps:

       1.     If there is a non-null environment variable LC_ALL, the value of
              LC_ALL is used.

       2.     If an environment variable with the same name as one of the
              categories above exists and is non-null, its value is used for that
              category.

       3.     If there is a non-null environment variable LANG, the value of LANG
              is used.

       Values about local numeric formatting is made available in a struct lconv
       returned by the localeconv(3) function, which has the following
       declaration:

         struct lconv {

             /* Numeric (nonmonetary) information */

             char *decimal_point;     /* Radix character */
             char *thousands_sep;     /* Separator for digit groups to left
                                         of radix character */
             char *grouping; /* Each element is the number of digits in a
                                group; elements with higher indices are
                                further left.  An element with value CHAR_MAX
                                means that no further grouping is done.  An
                                element with value 0 means that the previous
                                element is used for all groups further left. */

             /* Remaining fields are for monetary information */

             char *int_curr_symbol;   /* First three chars are a currency symbol
                                         from ISO 4217.  Fourth char is the
                                         separator.  Fifth char is '\0'. */
             char *currency_symbol;   /* Local currency symbol */
             char *mon_decimal_point; /* Radix character */
             char *mon_thousands_sep; /* Like thousands_sep above */
             char *mon_grouping;      /* Like grouping above */
             char *positive_sign;     /* Sign for positive values */
             char *negative_sign;     /* Sign for negative values */
             char  int_frac_digits;   /* International fractional digits */
             char  frac_digits;       /* Local fractional digits */
             char  p_cs_precedes;     /* 1 if currency_symbol precedes a
                                         positive value, 0 if succeeds */
             char  p_sep_by_space;    /* 1 if a space separates currency_symbol
                                         from a positive value */
             char  n_cs_precedes;     /* 1 if currency_symbol precedes a
                                         negative value, 0 if succeeds */
             char  n_sep_by_space;    /* 1 if a space separates currency_symbol
                                         from a negative value */
             /* Positive and negative sign positions:
                0 Parentheses surround the quantity and currency_symbol.
                1 The sign string precedes the quantity and currency_symbol.
                2 The sign string succeeds the quantity and currency_symbol.
                3 The sign string immediately precedes the currency_symbol.
                4 The sign string immediately succeeds the currency_symbol. */
             char  p_sign_posn;
             char  n_sign_posn;
         };

CONFORMING TO top

       POSIX.1-2001.

       The GNU gettext functions are specified in LI18NUX2000.

SEE ALSO top

       locale(1), localedef(1), gettext(3), localeconv(3), ngettext(3),
       nl_langinfo(3), rpmatch(3), setlocale(3), strcoll(3), strfmon(3),
       strftime(3), strxfrm(3)

COLOPHON top

       This page is part of release 3.45 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-05                           LOCALE(7)


localeconv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LOCALECONV(3)                Linux Programmer's Manual               LOCALECONV(3)

NAME top

       localeconv - get numeric formatting information

SYNOPSIS top

       #include <locale.h>

       struct lconv *localeconv(void);

DESCRIPTION top

       The localeconv() function returns a pointer to a struct lconv for the
       current locale.  This structure is shown in locale(7), and contains all
       values associated with the locale categories LC_NUMERIC and LC_MONETARY.
       Programs may also use the functions printf(3) and strfmon(3), which behave
       according to the actual locale in use.

CONFORMING TO top

       C89, C99.

BUGS top

       The printf(3) family of functions may or may not honor the current locale.

SEE ALSO top

       locale(1), localedef(1), isalpha(3), nl_langinfo(3), setlocale(3),
       strcoll(3), strftime(3), locale(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-04-25                       LOCALECONV(3)


lockf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LOCKF(3)                     Linux Programmer's Manual                    LOCKF(3)

NAME top

       lockf - apply, test or remove a POSIX lock on an open file

SYNOPSIS top

       #include <unistd.h>

       int lockf(int fd, int cmd, off_t len);

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

       lockf():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       Apply, test or remove a POSIX lock on a section of an open file.  The file
       is specified by fd, a file descriptor open for writing, the action by cmd,
       and the section consists of byte positions pos..pos+len-1 if len is
       positive, and pos-len..pos-1 if len is negative, where pos is the current
       file position, and if len is zero, the section extends from the current
       file position to infinity, encompassing the present and future end-of-file
       positions.  In all cases, the section may extend past current end-of-file.

       On Linux, lockf() is just an interface on top of fcntl(2) locking.  Many
       other systems implement lockf() in this way, but note that POSIX.1-2001
       leaves the relationship between lockf() and fcntl(2) locks unspecified.  A
       portable application should probably avoid mixing calls to these
       interfaces.

       Valid operations are given below:

       F_LOCK Set an exclusive lock on the specified section of the file.  If
              (part of) this section is already locked, the call blocks until the
              previous lock is released.  If this section overlaps an earlier
              locked section, both are merged.  File locks are released as soon as
              the process holding the locks closes some file descriptor for the
              file.  A child process does not inherit these locks.

       F_TLOCK
              Same as F_LOCK but the call never blocks and returns an error
              instead if the file is already locked.

       F_ULOCK
              Unlock the indicated section of the file.  This may cause a locked
              section to be split into two locked sections.

       F_TEST Test the lock: return 0 if the specified section is unlocked or
              locked by this process; return -1, set errno to EAGAIN (EACCES on
              some other systems), if another process holds a lock.

RETURN VALUE top

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

ERRORS top

       EACCES or EAGAIN
              The file is locked and F_TLOCK or F_TEST was specified, or the
              operation is prohibited because the file has been memory-mapped by
              another process.

       EBADF  fd is not an open file descriptor; or cmd is F_LOCK or F_TLOCK and
              fd is not a writable file descriptor.

       EDEADLK
              The command was F_LOCK and this lock operation would cause a
              deadlock.

       EINVAL An invalid operation was specified in fd.

       ENOLCK Too many segment locks open, lock table is full.

CONFORMING TO top

       SVr4, POSIX.1-2001.

SEE ALSO top

       fcntl(2), flock(2)

       locks.txt and mandatory-locking.txt in the Linux kernel source directory
       Documentation/filesystems (on older kernels, these files are directly under
       the Documentation directory, and mandatory-locking.txt is called
       mandatory.txt)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-07-07                            LOCKF(3)


log(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

LOG(3)                       Linux Programmer's Manual                      LOG(3)

NAME top

       log, logf, logl - natural logarithmic function

SYNOPSIS top

       #include <math.h>

       double log(double x);
       float logf(float x);
       long double logl(long double x);

       Link with -lm.

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

       logf(), logl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The log() function returns the natural logarithm of x.

RETURN VALUE top

       On success, these functions return the natural logarithm of x.

       If x is a NaN, a NaN is returned.

       If x is 1, the result is +0.

       If x is positive infinity, positive infinity is returned.

       If x is zero, then a pole error occurs, and the functions return -HUGE_VAL,
       -HUGE_VALF, or -HUGE_VALL, respectively.

       If x is negative (including negative infinity), then a domain error occurs,
       and a NaN (not a number) is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is negative
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

       Pole error: x is zero
              errno is set to ERANGE.  A divide-by-zero floating-point exception
              (FE_DIVBYZERO) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

BUGS top

       In glibc 2.5 and earlier, taking the log() of a NaN produces a bogus
       invalid floating-point (FE_INVALID) exception.

SEE ALSO top

       cbrt(3), clog(3), log10(3), log1p(3), log2(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                              LOG(3)


log10(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LOG10(3)                     Linux Programmer's Manual                    LOG10(3)

NAME top

       log10, log10f, log10l -  base-10 logarithmic function

SYNOPSIS top

       #include <math.h>

       double log10(double x);
       float log10f(float x);
       long double log10l(long double x);

       Link with -lm.

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

       log10f(), log10l():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The log10() function returns the base 10 logarithm of x.

RETURN VALUE top

       On success, these functions return the base 10 logarithm of x.

       For special cases, including where x is 0, 1, negative, infinity, or NaN,
       see log(3).

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       For a discussion of the errors that can occur for these functions, see
       log(3).

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       cbrt(3), clog10(3), exp10(3), log(3), log2(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            LOG10(3)


log1p(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LOG1P(3)                     Linux Programmer's Manual                    LOG1P(3)

NAME top

       log1p, log1pf, log1pl -  logarithm of 1 plus argument

SYNOPSIS top

       #include <math.h>

       double log1p(double x);
       float log1pf(float x);
       long double log1pl(long double x);

       Link with -lm.

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

       log1p():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       log1pf(), log1pl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       log1p(x) returns a value equivalent to

           log (1 + x)

       It is computed in a way that is accurate even if the value of x is near
       zero.

RETURN VALUE top

       On success, these functions return the natural logarithm of (1 + x).

       If x is a NaN, a NaN is returned.

       If x is positive infinity, positive infinity is returned.

       If x is -1, a pole error occurs, and the functions return -HUGE_VAL,
       -HUGE_VALF, or -HUGE_VALL, respectively.

       If x is less than -1 (including negative infinity), a domain error occurs,
       and a NaN (not a number) is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is less than -1
              An invalid floating-point exception (FE_INVALID) is raised.

       Pole error: x is -1
              A divide-by-zero floating-point exception (FE_DIVBYZERO) is raised.

       These functions do not set errno.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       exp(3), expm1(3), log(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            LOG1P(3)


log2(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LOG2(3)                      Linux Programmer's Manual                     LOG2(3)

NAME top

       log2, log2f, log2l - base-2 logarithmic function

SYNOPSIS top

       #include <math.h>

       double log2(double x);
       float log2f(float x);
       long double log2l(long double x);

       Link with -lm.

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

       log2(), log2f(), log2l():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The log2() function returns the base 2 logarithm of x.

RETURN VALUE top

       On success, these functions return the base 2 logarithm of x.

       For special cases, including where x is 0, 1, negative, infinity, or NaN,
       see log(3).

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       For a discussion of the errors that can occur for these functions, see
       log(3).

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD.

SEE ALSO top

       cbrt(3), clog2(3), log(3), log10(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-12                             LOG2(3)


logb(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

LOGB(3)                      Linux Programmer's Manual                     LOGB(3)

NAME top

       logb, logbf, logbl - get exponent of a floating-point value

SYNOPSIS top

       #include <math.h>

       double logb(double x);
       float logbf(float x);
       long double logbl(long double x);

       Link with -lm.

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

       logb():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       logbf(), logbl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions extract the exponent from the internal floating-point
       representation of x and return it as a floating-point value.  The integer
       constant FLT_RADIX, defined in <float.h>, indicates the radix used for the
       system's floating-point representation.  If FLT_RADIX is 2, logb(x) is
       equal to floor(log2(x)), except that it is probably faster.

       If x is subnormal, logb() returns the exponent x would have if it were
       normalized.

RETURN VALUE top

       On success, these functions return the exponent of x.

       If x is a NaN, a NaN is returned.

       If x is zero, then a pole error occurs, and the functions return -HUGE_VAL,
       -HUGE_VALF, or -HUGE_VALL, respectively.

       If x is negative infinity or positive infinity, then positive infinity is
       returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Pole error: x is 0
              A divide-by-zero floating-point exception (FE_DIVBYZERO) is raised.

       These functions do not set errno.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       ilogb(3), log(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             LOGB(3)


login(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LOGIN(3)                     Linux Programmer's Manual                    LOGIN(3)

NAME top

       login, logout - write utmp and wtmp entries

SYNOPSIS top

       #include <utmp.h>

       void login(const struct utmp *ut);

       int logout(const char *ut_line);

       Link with -lutil.

DESCRIPTION top

       The utmp file records who is currently using the system.  The wtmp file
       records all logins and logouts.  See utmp(5).

       The function login() takes the supplied struct utmp, ut, and writes it to
       both the utmp and the wtmp file.

       The function logout() clears the entry in the utmp file again.

GNU Details

       More precisely, login() takes the argument ut struct, fills the field
       ut->ut_type (if there is such a field) with the value USER_PROCESS, and
       fills the field ut->ut_pid (if there is such a field) with the process ID
       of the calling process.  Then it tries to fill the field ut->ut_line.  It
       takes the first of stdin, stdout, stderr that is a tty, and stores the
       corresponding pathname minus a possible leading /dev/ into this field, and
       then writes the struct to the utmp file.  On the other hand, if no tty name
       was found, this field is filled with "???"  and the struct is not written
       to the utmp file.  After this, the struct is written to the wtmp file.

       The logout() function searches the utmp file for an entry matching the
       ut_line argument.  If a record is found, it is updated by zeroing out the
       ut_name and ut_host fields, updating the ut_tv timestamp field and setting
       ut_type (if there is such a field) to DEAD_PROCESS.

RETURN VALUE top

       The logout() function returns 1 if the entry was successfully written to
       the database, or 0 if an error occurred.

FILES top

       /var/run/utmp
              user accounting database, configured through _PATH_UTMP in <paths.h>

       /var/log/wtmp
              user accounting log file, configured through _PATH_WTMP in <paths.h>

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs.

NOTES top

       Note that the member ut_user of struct utmp is called ut_name in BSD.
       Therefore, ut_name is defined as an alias for ut_user in <utmp.h>.

SEE ALSO top

       getutent(3), utmp(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2004-05-06                            LOGIN(3)


updwtmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | CONFORMING TO | AVAILABILITY | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UPDWTMP(3)                   Linux Programmer's Manual                  UPDWTMP(3)

NAME top

       updwtmp, logwtmp - append an entry to the wtmp file

SYNOPSIS top

       #include <utmp.h>

       void updwtmp(const char *wtmp_file, const struct utmp *ut);
       void logwtmp(const char *line, const char *name, const char *host);

DESCRIPTION top

       updwtmp() appends the utmp structure ut to the wtmp file.

       logwtmp() constructs a utmp structure using line, name, host, current time
       and current process ID.  Then it calls updwtmp() to append the structure to
       the wtmp file.

FILES top

       /var/log/wtmp
              database of past user logins

CONFORMING TO top

       Not in POSIX.1-2001.  Present on Solaris, NetBSD, and perhaps other
       systems.

AVAILABILITY top

       Both functions are available under glibc2, but not under libc5.  However,
       logwtmp() used to occur in the old libbsd.  These days, the logwtmp()
       function is included in libutil.  (Hence you'll need to add -lutil to your
       compiler command line to get it.)

NOTES top

       For consistency with the other "utmpx" functions (see getutxent(3)), glibc
       provides (since version 2.1):

       #include <utmpx.h>

       void updwtmpx (const char *wtmpx_file, const struct utmpx *utx);

       This function performs the same task as updwtmp(), but differs in that it
       takes a utmpx structure as its last argument.

SEE ALSO top

       getutxent(3), wtmp(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-07-02                          UPDWTMP(3)


longjmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LONGJMP(3)                   Linux Programmer's Manual                  LONGJMP(3)

NAME top

       longjmp, siglongjmp - nonlocal jump to a saved stack context

SYNOPSIS top

       #include <setjmp.h>

       void longjmp(jmp_buf env, int val);

       void siglongjmp(sigjmp_buf env, int val);

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

       siglongjmp(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_C_SOURCE

DESCRIPTION top

       longjmp() and setjmp(3) are useful for dealing with errors and interrupts
       encountered in a low-level subroutine of a program.  longjmp() restores the
       environment saved by the last call of setjmp(3) with the corresponding env
       argument.  After longjmp() is completed, program execution continues as if
       the corresponding call of setjmp(3) had just returned the value val.
       longjmp() cannot cause 0 to be returned.  If longjmp() is invoked with a
       second argument of 0, 1 will be returned instead.

       siglongjmp() is similar to longjmp() except for the type of its env
       argument.  If, and only if, the sigsetjmp(3) call that set this env used a
       nonzero savesigs flag, siglongjmp() also restores the signal mask that was
       saved by sigsetjmp(3).

RETURN VALUE top

       These functions never return.

CONFORMING TO top

       C89, C99, and POSIX.1-2001 specify longjmp().  POSIX.1-2001 specifies
       siglongjmp().

NOTES top

       POSIX does not specify whether longjmp() will restore the signal context
       (see setjmp(3) for some more details).  If you want to portably save and
       restore signal masks, use sigsetjmp(3) and siglongjmp().

       The values of automatic variables are unspecified after a call to longjmp()
       if they meet all the following criteria:

       +o  they are local to the function that made the corresponding setjmp(3)
          call;

       +o  their values are changed between the calls to setjmp(3) and longjmp();
          and

       +o  they are not declared as volatile.

       Analogous remarks apply for siglongjmp().

       longjmp() and siglongjmp() make programs hard to understand and maintain.
       If possible an alternative should be used.

SEE ALSO top

       setjmp(3), sigsetjmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-01-13                          LONGJMP(3)


lookup_dcookie(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | COLOPHON The Linux Programming Interface

LOOKUP_DCOOKIE(2)            Linux Programmer's Manual           LOOKUP_DCOOKIE(2)

NAME top

       lookup_dcookie - return a directory entry's path

SYNOPSIS top

       int lookup_dcookie(u64 cookie, char *buffer, size_t len);

DESCRIPTION top

       Look up the full path of the directory entry specified by the value cookie.
       The cookie is an opaque identifier uniquely identifying a particular
       directory entry.  The buffer given is filled in with the full path of the
       directory entry.

       For lookup_dcookie() to return successfully, the kernel must still hold a
       cookie reference to the directory entry.

RETURN VALUE top

       On success, lookup_dcookie() returns the length of the path string copied
       into the buffer.  On error, -1 is returned, and errno is set appropriately.

ERRORS top

       EFAULT The buffer was not valid.

       EINVAL The kernel has no registered cookie/directory entry mappings at the
              time of lookup, or the cookie does not refer to a valid directory
              entry.

       ENAMETOOLONG
              The name could not fit in the buffer.

       ENOMEM The kernel could not allocate memory for the temporary buffer
              holding the path.

       EPERM  The process does not have the capability CAP_SYS_ADMIN required to
              look up cookie values.

       ERANGE The buffer was not large enough to hold the path of the directory
              entry.

VERSIONS top

       Available since Linux 2.5.43.  The ENAMETOOLONG error return was added in
       2.5.70.

CONFORMING TO top

       lookup_dcookie() is Linux-specific.

NOTES top

       lookup_dcookie() is a special-purpose system call, currently used only by
       the oprofile profiler.  It relies on a kernel driver to register cookies
       for directory entries.

       The path returned may be suffixed by the string " (deleted)" if the
       directory entry has been removed.

COLOPHON top

       This page is part of release 3.45 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                               2004-06-17                   LOOKUP_DCOOKIE(2)


lp(4) - Linux manual page

NAME | SYNOPSIS | CONFIGURATION | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

LP(4)                        Linux Programmer's Manual                       LP(4)

NAME top

       lp - line printer devices

SYNOPSIS top

       #include <linux/lp.h>

CONFIGURATION top

       lp[0-2]  are  character  devices  for the parallel line printers; they have
       major number 6 and minor number 0-2.  The minor numbers correspond  to  the
       printer  port  base addresses 0x03bc, 0x0378 and 0x0278.  Usually they have
       mode 220 and are owned by root and group lp.  You  can  use  printer  ports
       either  with  polling  or with interrupts.  Interrupts are recommended when
       high traffic is expected, for example, for laser printers.  For  usual  dot
       matrix printers polling will usually be enough.  The default is polling.

DESCRIPTION top

       The following ioctl(2) calls are supported:

       int ioctl(int fd, LPTIME, int arg)
              Sets the amount of time that the driver sleeps before rechecking the
              printer when the printer's buffer appears to be filled to arg.  If
              you have a fast printer, decrease this number; if you have a slow
              printer then increase it.  This is in hundredths of a second, the
              default 2 being 0.02 seconds.  It only influences the polling
              driver.

       int ioctl(int fd, LPCHAR, int arg)
              Sets the maximum number of busy-wait iterations which the polling
              driver does while waiting for the printer to get ready for receiving
              a character to arg.  If printing is too slow, increase this number;
              if the system gets too slow, decrease this number.  The default is
              1000.  It only influences the polling driver.

       int ioctl(int fd, LPABORT, int arg)
              If arg is 0, the printer driver will retry on errors, otherwise it
              will abort.  The default is 0.

       int ioctl(int fd, LPABORTOPEN, int arg)
              If arg is 0, open(2) will be aborted on error, otherwise error will
              be ignored.  The default is to ignore it.

       int ioctl(int fd, LPCAREFUL, int arg)
              If arg is 0, then the out-of-paper, offline and error signals are
              required to be false on all writes, otherwise they are ignored.  The
              default is to ignore them.

       int ioctl(int fd, LPWAIT, int arg)
              Sets the number of busy waiting iterations to wait before strobing
              the printer to accept a just-written character, and the number of
              iterations to wait before turning the strobe off again, to arg.  The
              specification says this time should be 0.5 microseconds, but
              experience has shown the delay caused by the code is already enough.
              For that reason, the default value is 0.  This is used for both the
              polling and the interrupt driver.

       int ioctl(int fd, LPSETIRQ, int arg)
              This ioctl(2) requires superuser privileges.  It takes an int
              containing the new IRQ as argument.  As a side effect, the printer
              will be reset.  When arg is 0, the polling driver will be used,
              which is also default.

       int ioctl(int fd, LPGETIRQ, int *arg)
              Stores the currently used IRQ in arg.

       int ioctl(int fd, LPGETSTATUS, int *arg)
              Stores the value of the status port in arg.  The bits have the
              following meaning:

              LP_PBUSY     inverted busy input, active high
              LP_PACK      unchanged acknowledge input, active low
              LP_POUTPA    unchanged out-of-paper input, active high
              LP_PSELECD   unchanged selected input, active high
              LP_PERRORP   unchanged error input, active low

              Refer to your printer manual for the meaning of the signals.  Note
              that undocumented bits may also be set, depending on your printer.

       int ioctl(int fd, LPRESET)
              Resets the printer.  No argument is used.

FILES top

       /dev/lp*

SEE ALSO top

       chmod(1), chown(1), mknod(1), lpcntl(8), tunelp(8)

COLOPHON top

       This page is part of release 3.45 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                               1995-01-15                               LP(4)


lseek(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

LSEEK(2)                     Linux Programmer's Manual                    LSEEK(2)

NAME top

       lseek - reposition read/write file offset

SYNOPSIS top

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

       off_t lseek(int fd, off_t offset, int whence);

DESCRIPTION top

       The lseek() function repositions the offset of the open file associated
       with the file descriptor fd to the argument offset according to the
       directive whence as follows:

       SEEK_SET
              The offset is set to offset bytes.

       SEEK_CUR
              The offset is set to its current location plus offset bytes.

       SEEK_END
              The offset is set to the size of the file plus offset bytes.

       The lseek() function allows the file offset to be set beyond the end of the
       file (but this does not change the size of the file).  If data is later
       written at this point, subsequent reads of the data in the gap (a "hole")
       return null bytes ('\0') until data is actually written into the gap.

Seeking file data and holes

       Since version 3.1, Linux supports the following additional values for
       whence:

       SEEK_DATA
              Adjust the file offset to the next location in the file greater than
              or equal to offset containing data.  If offset points to data, then
              the file offset is set to offset.

       SEEK_HOLE
              Adjust the file offset to the next hole in the file greater than or
              equal to offset.  If offset points into the middle of a hole, then
              the file offset is set to offset.  If there is no hole past offset,
              then the file offset is adjusted to the end of the file (i.e., there
              is an implicit hole at the end of any file).

       In both of the above cases, lseek() fails if offset points past the end of
       the file.

       These operations allow applications to map holes in a sparsely allocated
       file.  This can be useful for applications such as file backup tools, which
       can save space when creating backups and preserve holes, if they have a
       mechanism for discovering holes.

       For the purposes of these operations, a hole is a sequence of zeros that
       (normally) has not been allocated in the underlying file storage.  However,
       a file system is not obliged to report holes, so these operations are not a
       guaranteed mechanism for mapping the storage space actually allocated to a
       file.  (Furthermore, a sequence of zeros that actually has been written to
       the underlying storage may not be reported as a hole.)  In the simplest
       implementation, a file system can support the operations by making
       SEEK_HOLE always return the offset of the end of the file, and making
       SEEK_DATA always return offset (i.e., even if the location referred to by
       offset is a hole, it can be considered to consist of data that is a
       sequence of zeros).

RETURN VALUE top

       Upon successful completion, lseek() returns the resulting offset location
       as measured in bytes from the beginning of the file.  On error, the value
       (off_t) -1 is returned and errno is set to indicate the error.

ERRORS top

       EBADF  fd is not an open file descriptor.

       EINVAL whence is not valid.  Or: the resulting file offset would be
              negative, or beyond the end of a seekable device.

       EOVERFLOW
              The resulting file offset cannot be represented in an off_t.

       ESPIPE fd is associated with a pipe, socket, or FIFO.

       ENXIO  whence is SEEK_DATA or SEEK_HOLE, and the current file offset is
              beyond the end of the file.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

       SEEK_DATA and SEEK_HOLE are nonstandard extensions also present in Solaris,
       FreeBSD, and DragonFly BSD; they are proposed for inclusion in the next
       POSIX revision (Issue 8).

NOTES top

       Some devices are incapable of seeking and POSIX does not specify which
       devices must support lseek().

       On Linux, using lseek() on a tty device returns ESPIPE.

       When converting old code, substitute values for whence with the following
       macros:

        old       new
       0        SEEK_SET
       1        SEEK_CUR
       2        SEEK_END
       L_SET    SEEK_SET
       L_INCR   SEEK_CUR
       L_XTND   SEEK_END

       Note that file descriptors created by dup(2) or fork(2) share the current
       file position pointer, so seeking on such files may be subject to race
       conditions.

SEE ALSO top

       dup(2), fork(2), open(2), fseek(3), lseek64(3), posix_fallocate(3)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-25                            LSEEK(2)


lseek64(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

LSEEK64(3)                   Linux Programmer's Manual                  LSEEK64(3)

NAME top

       lseek64 - reposition 64-bit read/write file offset

SYNOPSIS top

       #define _LARGEFILE64_SOURCE     /* See feature_test_macros(7) */
       #include <sys/types.h>
       #include <unistd.h>

       off64_t lseek64(int fd, off64_t offset, int whence);

DESCRIPTION top

       The lseek(2) family of functions reposition the offset of the open file
       associated with the file descriptor fd to offset bytes relative to the
       start, current position, or end of the file, when whence has the value
       SEEK_SET, SEEK_CUR, or SEEK_END, respectively.

       For more details, return value, and errors, see lseek(2).

       Four interfaces are available: lseek(2), lseek64(), llseek(2), and the raw
       system call _llseek(2).

lseek

       Prototype:

           off_t lseek(int fd, off_t offset, int whence);

       lseek(2) uses the type off_t.  This is a 32-bit signed type on 32-bit
       architectures, unless one compiles with

           #define _FILE_OFFSET_BITS 64

       in which case it is a 64-bit signed type.

lseek64

       Prototype:

           off64_t lseek64(int fd, off64_t offset, int whence);

       The library routine lseek64() uses a 64-bit type even when off_t is a
       32-bit type.  Its prototype (and the type off64_t) is available only when
       one compiles with

           #define _LARGEFILE64_SOURCE

       The function lseek64() is available since glibc 2.1, and is defined to be
       an alias for llseek().

llseek

       Prototype:

           loff_t llseek(int fd, loff_t offset, int whence);

       The type loff_t is a 64-bit signed type.  The library routine llseek() is
       available in libc5 and glibc and works without special defines.  Its
       prototype was given in <unistd.h> with libc5, but glibc does not provide a
       prototype.  This is bad, since a prototype is needed.  Users should add the
       above prototype, or something equivalent, to their own source.  When users
       complained about data loss caused by a miscompilation of e2fsck(8), glibc
       2.1.3 added the link-time warning

           "the `llseek' function may be dangerous; use `lseek64' instead."

       This makes this function unusable if one desires a warning-free
       compilation.

_llseek

       All the above functions are implemented in terms of this system call.  The
       prototype is:

           int _llseek(int fd, off_t offset_hi, off_t offset_lo,
                       loff_t *result, int whence);

       For more details, see llseek(2).

SEE ALSO top

       llseek(2), lseek(2)

COLOPHON top

       This page is part of release 3.45 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                               2004-12-11                          LSEEK64(3)


madvise(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MADVISE(2)                   Linux Programmer's Manual                  MADVISE(2)

NAME top

       madvise - give advice about use of memory

SYNOPSIS top

       #include <sys/mman.h>

       int madvise(void *addr, size_t length, int advice);

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

       madvise(): _BSD_SOURCE

DESCRIPTION top

       The madvise() system call advises the kernel about how to handle paging
       input/output in the address range beginning at address addr and with size
       length bytes.  It allows an application to tell the kernel how it expects
       to use some mapped or shared memory areas, so that the kernel can choose
       appropriate read-ahead and caching techniques.  This call does not
       influence the semantics of the application (except in the case of
       MADV_DONTNEED), but may influence its performance.  The kernel is free to
       ignore the advice.

       The advice is indicated in the advice argument which can be

       MADV_NORMAL
              No special treatment.  This is the default.

       MADV_RANDOM
              Expect page references in random order.  (Hence, read ahead may be
              less useful than normally.)

       MADV_SEQUENTIAL
              Expect page references in sequential order.  (Hence, pages in the
              given range can be aggressively read ahead, and may be freed soon
              after they are accessed.)

       MADV_WILLNEED
              Expect access in the near future.  (Hence, it might be a good idea
              to read some pages ahead.)

       MADV_DONTNEED
              Do not expect access in the near future.  (For the time being, the
              application is finished with the given range, so the kernel can free
              resources associated with it.)  Subsequent accesses of pages in this
              range will succeed, but will result either in reloading of the
              memory contents from the underlying mapped file (see mmap(2)) or
              zero-fill-on-demand pages for mappings without an underlying file.

       MADV_REMOVE (Since Linux 2.6.16)
              Free up a given range of pages and its associated backing store.
              Currently, only shmfs/tmpfs supports this; other file systems return
              with the error ENOSYS.

       MADV_DONTFORK (Since Linux 2.6.16)
              Do not make the pages in this range available to the child after a
              fork(2).  This is useful to prevent copy-on-write semantics from
              changing the physical location of a page(s) if the parent writes to
              it after a fork(2).  (Such page relocations cause problems for
              hardware that DMAs into the page(s).)

       MADV_DOFORK (Since Linux 2.6.16)
              Undo the effect of MADV_DONTFORK, restoring the default behavior,
              whereby a mapping is inherited across fork(2).

       MADV_HWPOISON (Since Linux 2.6.32)
              Poison a page and handle it like a hardware memory corruption.  This
              operation is only available for privileged (CAP_SYS_ADMIN)
              processes.  This operation may result in the calling process
              receiving a SIGBUS and the page being unmapped.  This feature is
              intended for testing of memory error-handling code; it is only
              available if the kernel was configured with CONFIG_MEMORY_FAILURE.

       MADV_SOFT_OFFLINE (Since Linux 2.6.33)
              Soft offline the pages in the range specified by addr and length.
              The memory of each page in the specified range is preserved (i.e.,
              when next accessed, the same content will be visible, but in a new
              physical page frame), and the original page is offlined (i.e., no
              longer used, and taken out of normal memory management).  The effect
              of the MADV_SOFT_OFFLINE operation is invisible to (i.e., does not
              change the semantics of) the calling process.  This feature is
              intended for testing of memory error-handling code; it is only
              available if the kernel was configured with CONFIG_MEMORY_FAILURE.

       MADV_MERGEABLE (since Linux 2.6.32)
              Enable Kernel Samepage Merging (KSM) for the pages in the range
              specified by addr and length.  The kernel regularly scans those
              areas of user memory that have been marked as mergeable, looking for
              pages with identical content.  These are replaced by a single write-
              protected page (which is automatically copied if a process later
              wants to update the content of the page).  KSM only merges private
              anonymous pages (see mmap(2)).  The KSM feature is intended for
              applications that generate many instances of the same data (e.g.,
              virtualization systems such as KVM).  It can consume a lot of
              processing power; use with care.  See the Linux kernel source file
              Documentation/vm/ksm.txt for more details.  The MADV_MERGEABLE and
              MADV_UNMERGEABLE operations are only available if the kernel was
              configured with CONFIG_KSM.

       MADV_UNMERGEABLE (since Linux 2.6.32)
              Undo the effect of an earlier MADV_MERGEABLE operation on the
              specified address range; KSM unmerges whatever pages it had merged
              in the address range specified by addr and length.

       MADV_HUGEPAGE (since Linux 2.6.38)
              Enables Transparent Huge Pages (THP) for pages in the range
              specified by addr and length.  Currently, Transparent Huge Pages
              only work with private anonymous pages (see mmap(2)).  The kernel
              will regularly scan the areas marked as huge page candidates to
              replace them with huge pages.  The kernel will also allocate huge
              pages directly when the region is naturally aligned to the huge page
              size (see posix_memalign(2)).  This feature is primarily aimed at
              applications that use large mappings of data and access large
              regions of that memory at a time (e.g., virtualization systems such
              as QEMU).  It can very easily waste memory (e.g., a 2MB mapping that
              only ever accesses 1 byte will result in 2MB of wired memory instead
              of one 4KB page).  See the Linux kernel source file
              Documentation/vm/transhuge.txt for more details.  The MADV_HUGEPAGE
              and MADV_NOHUGEPAGE operations are only available if the kernel was
              configured with CONFIG_TRANSPARENT_HUGEPAGE.

       MADV_NOHUGEPAGE (since Linux 2.6.38)
              Ensures that memory in the address range specified by addr and
              length will not be collapsed into huge pages.

       MADV_DONTDUMP (since Linux 3.4)
              Exclude from a core dump those pages in the range specified by addr
              and length.  This is useful in applications that have large areas of
              memory that are known not to be useful in a core dump.  The effect
              of MADV_DONTDUMP takes precedence over the bit mask that is set via
              the /proc/PID/coredump_filter file (see core(5)).

       MADV_DODUMP (since Linux 3.4)
              Undo the effect of an earlier MADV_DONTDUMP.

RETURN VALUE top

       On success madvise() returns zero.  On error, it returns -1 and errno is
       set appropriately.

ERRORS top

       EAGAIN A kernel resource was temporarily unavailable.

       EBADF  The map exists, but the area maps something that isn't a file.

       EINVAL This error can occur for the following reasons:

              *  The value len is negative.

              *  addr is not page-aligned.

              *  advice is not a valid value

              *  The application is attempting to release locked or shared pages
                 (with MADV_DONTNEED).

              *  MADV_MERGEABLE or MADV_UNMERGEABLE was specified in advice, but
                 the kernel was not configured with CONFIG_KSM.

       EIO    (for MADV_WILLNEED) Paging in this area would exceed the process's
              maximum resident set size.

       ENOMEM (for MADV_WILLNEED) Not enough memory: paging in failed.

       ENOMEM Addresses in the specified range are not currently mapped, or are
              outside the address space of the process.

CONFORMING TO top

       POSIX.1b.  POSIX.1-2001 describes posix_madvise(3) with constants
       POSIX_MADV_NORMAL, etc., with a behavior close to that described here.
       There is a similar posix_fadvise(2) for file access.

       MADV_REMOVE, MADV_DONTFORK, MADV_DOFORK, MADV_HWPOISON, MADV_MERGEABLE, and
       MADV_UNMERGEABLE are Linux-specific.

NOTES top

Linux Notes

       The current Linux implementation (2.4.0) views this system call more as a
       command than as advice and hence may return an error when it cannot do what
       it usually would do in response to this advice.  (See the ERRORS
       description above.)  This is nonstandard behavior.

       The Linux implementation requires that the address addr be page-aligned,
       and allows length to be zero.  If there are some parts of the specified
       address range that are not mapped, the Linux version of madvise() ignores
       them and applies the call to the rest (but returns ENOMEM from the system
       call, as it should).

SEE ALSO          top
       getrlimit(2), mincore(2), mmap(2), mprotect(2), msync(2), munmap(2),
       core(5)

COLOPHON          top
       This page is part of release 3.45 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                               2012-04-28                          MADVISE(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


mailaddr(7) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

MAILADDR(7)                     Linux User's Manual                    MAILADDR(7)

NAME top

       mailaddr - mail addressing description

DESCRIPTION top

       This manual page gives a brief introduction to SMTP mail addresses, as used
       on the Internet.  These addresses are in the general format

            user@domain

       where a domain is a hierarchical dot-separated list of subdomains.  These
       examples are valid forms of the same address:

            eric@monet.berkeley.edu
            Eric Allman <eric@monet.berkeley.edu>
            eric@monet.berkeley.edu (Eric Allman)

       The domain part ("monet.berkeley.edu") is a mail-accepting domain.  It can
       be a host and in the past it usually was, but it doesn't have to be.  The
       domain part is not case sensitive.

       The local part ("eric") is often a username, but its meaning is defined by
       the local software.  Sometimes it is case sensitive, although that is
       unusual.  If you see a local-part that looks like garbage, it is usually
       because of a gateway between an internal e-mail system and the net, here
       are some examples:

            "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where
            USER%SOMETHING@some.where
            machine!machine!name@some.where
            I2461572@some.where

       (These are, respectively, an X.400 gateway, a gateway to an arbitrary
       internal mail system that lacks proper internet support, an UUCP gateway,
       and the last one is just boring username policy.)

       The real-name part ("Eric Allman") can either be placed before <>, or in ()
       at the end.  (Strictly speaking the two aren't the same, but the difference
       is beyond the scope of this page.)  The name may have to be quoted using
       "", for example, if it contains ".":

            "Eric P. Allman" <eric@monet.berkeley.edu>

Abbreviation.

       Many mail systems let users abbreviate the domain name.  For instance,
       users at berkeley.edu may get away with "eric@monet" to send mail to Eric
       Allman.  This behavior is deprecated.  Sometimes it works, but you should
       not depend on it.

Route-addrs.

       In the past, sometimes one had to route a message through several hosts to
       get it to its final destination.  Addresses which show these relays are
       termed "route-addrs".  These use the syntax:

            <@hosta,@hostb:user@hostc>

       This specifies that the message should be sent to hosta, from there to
       hostb, and finally to hostc.  Many hosts disregard route-addrs and send
       directly to hostc.

       Route-addrs are very unusual now.  They occur sometimes in old mail
       archives.  It is generally possible to ignore all but the "user@hostc" part
       of the address to determine the actual address.

Postmaster.

       Every site is required to have a user or user alias designated "postmaster"
       to which problems with the mail system may be addressed.  The "postmaster"
       address is not case sensitive.

FILES top

       /etc/aliases
       ~/.forward

SEE ALSO top

       binmail(1), mail(1), mconnect(1), aliases(5), forward(5), sendmail(8),
       vrfy(8)

       RFC 2822 (Internet Message Format)

COLOPHON top

       This page is part of release 3.45 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/.

4.2 Berkeley Distribution           2004-09-15                         MAILADDR(7)


makecontext(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MAKECONTEXT(3)               Linux Programmer's Manual              MAKECONTEXT(3)

NAME top

       makecontext, swapcontext - manipulate user context

SYNOPSIS top

       #include <ucontext.h>

       void makecontext(ucontext_t *ucp, void (*func)(), int argc, ...);

       int swapcontext(ucontext_t *oucp, ucontext_t *ucp);

DESCRIPTION top

       In a System V-like environment, one has the type ucontext_t defined in
       <ucontext.h> and the four functions getcontext(2), setcontext(2),
       makecontext() and swapcontext() that allow user-level context switching
       between multiple threads of control within a process.

       For the type and the first two functions, see getcontext(2).

       The makecontext() function modifies the context pointed to by ucp (which
       was obtained from a call to getcontext(2)).  Before invoking makecontext(),
       the caller must allocate a new stack for this context and assign its
       address to ucp->uc_stack, and define a successor context and assign its
       address to ucp->uc_link.

       When this context is later activated (using setcontext(2) or swapcontext())
       the function func is called, and passed the series of integer (int)
       arguments that follow argc; the caller must specify the number of these
       arguments in argc.  When this function returns, the successor context is
       activated.  If the successor context pointer is NULL, the thread exits.

       The swapcontext() function saves the current context in the structure
       pointed to by oucp, and then activates the context pointed to by ucp.

RETURN VALUE top

       When successful, swapcontext() does not return.  (But we may return later,
       in case oucp is activated, in which case it looks like swapcontext()
       returns 0.)  On error, swapcontext() returns -1 and sets errno
       appropriately.

ERRORS top

       ENOMEM Insufficient stack space left.

VERSIONS top

       makecontext() and swapcontext() are provided in glibc since version 2.1.

CONFORMING TO top

       SUSv2, POSIX.1-2001.  POSIX.1-2008 removes the specifications of
       makecontext() and swapcontext(), citing portability issues, and
       recommending that applications be rewritten to use POSIX threads instead.

NOTES top

       The interpretation of ucp->uc_stack is just as in sigaltstack(2), namely,
       this struct contains the start and length of a memory area to be used as
       the stack, regardless of the direction of growth of the stack.  Thus, it is
       not necessary for the user program to worry about this direction.

       On architectures where int and pointer types are the same size (e.g.,
       x86-32, where both types are 32 bits), you may be able to get away with
       passing pointers as arguments to makecontext() following argc.  However,
       doing this is not guaranteed to be portable, is undefined according to the
       standards, and won't work on architectures where pointers are larger than
       ints.  Nevertheless, starting with version 2.8, glibc makes some changes to
       makecontext(), to permit this on some 64-bit architectures (e.g., x86-64).

EXAMPLE top

       The example program below demonstrates the use of getcontext(2),
       makecontext(), and swapcontext().  Running the program produces the
       following output:

           $ ./a.out
           main: swapcontext(&uctx_main, &uctx_func2)
           func2: started
           func2: swapcontext(&uctx_func2, &uctx_func1)
           func1: started
           func1: swapcontext(&uctx_func1, &uctx_func2)
           func2: returning
           func1: returning
           main: exiting

Program source

       #include <ucontext.h>
       #include <stdio.h>
       #include <stdlib.h>

       static ucontext_t uctx_main, uctx_func1, uctx_func2;

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

       static void
       func1(void)
       {
           printf("func1: started\n");
           printf("func1: swapcontext(&uctx_func1, &uctx_func2)\n");
           if (swapcontext(&uctx_func1, &uctx_func2) == -1)
               handle_error("swapcontext");
           printf("func1: returning\n");
       }

       static void
       func2(void)
       {
           printf("func2: started\n");
           printf("func2: swapcontext(&uctx_func2, &uctx_func1)\n");
           if (swapcontext(&uctx_func2, &uctx_func1) == -1)
               handle_error("swapcontext");
           printf("func2: returning\n");
       }

       int
       main(int argc, char *argv[])
       {
           char func1_stack[16384];
           char func2_stack[16384];

           if (getcontext(&uctx_func1) == -1)
               handle_error("getcontext");
           uctx_func1.uc_stack.ss_sp = func1_stack;
           uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
           uctx_func1.uc_link = &uctx_main;
           makecontext(&uctx_func1, func1, 0);

           if (getcontext(&uctx_func2) == -1)
               handle_error("getcontext");
           uctx_func2.uc_stack.ss_sp = func2_stack;
           uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
           /* Successor context is f1(), unless argc > 1 */
           uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
           makecontext(&uctx_func2, func2, 0);

           printf("main: swapcontext(&uctx_main, &uctx_func2)\n");
           if (swapcontext(&uctx_main, &uctx_func2) == -1)
               handle_error("swapcontext");

           printf("main: exiting\n");
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getcontext(2), sigaction(2), sigaltstack(2), sigprocmask(2), sigsetjmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-03-31                      MAKECONTEXT(3)


mallinfo(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MALLINFO(3)                  Linux Programmer's Manual                 MALLINFO(3)

NAME top

       mallinfo - obtain memory allocation information

SYNOPSIS top

       #include <malloc.h>

       struct mallinfo mallinfo(void);

DESCRIPTION top

       The mallinfo() function returns a copy of a structure containing
       information about memory allocations performed by malloc(3) and related
       functions.  This structure is defined as follows:

           struct mallinfo {
               int arena;     /* Non-mmapped space allocated (bytes) */
               int ordblks;   /* Number of free chunks */
               int smblks;    /* Number of free fastbin blocks */
               int hblks;     /* Number of mmapped regions */
               int hblkhd;    /* Space allocated in mmapped regions (bytes) */
               int usmblks;   /* Maximum total allocated space (bytes) */
               int fsmblks;   /* Space in freed fastbin blocks (bytes) */
               int uordblks;  /* Total allocated space (bytes) */
               int fordblks;  /* Total free space (bytes) */
               int keepcost;  /* Top-most, releasable space (bytes) */
           };

       The fields of the mallinfo structure contain the following information:

       arena     The total amount of memory allocated by means other than mmap(2)
                 (i.e., memory allocated on the heap).  This figure includes both
                 in-use blocks and blocks on the free list.

       ordblks   The number of ordinary (i.e., non-fastbin) free blocks.

       smblks    The number of fastbin free blocks (see mallopt(3)).

       hblks     The number of blocks currently allocated using mmap(2).  (See the
                 discussion of M_MMAP_THRESHOLD in mallopt(3).)

       hblkhd    The number of bytes in blocks currently allocated using mmap(2).

       usmblks   The "highwater mark" for allocated space--that is, the maximum
                 amount of space that was ever allocated.  This field is
                 maintained only in nonthreading environments.

       fsmblks   The total number of bytes in fastbin free blocks.

       uordblks  The total number of bytes used by in-use allocations.

       fordblks  The total number of bytes in free blocks.

       keepcost  The total amount of releasable free space at the top of the heap.
                 This is the maximum number of bytes that could ideally (i.e.,
                 ignoring page alignment restrictions, and so on) be released by
                 malloc_trim(3).

CONFORMING TO top

       This function is not specified by POSIX or the C standards.  A similar
       function exists on many System V derivatives, and was specified in the
       SVID.

BUGS top

       Information is returned for only the main memory allocation area.
       Allocations in other arenas are excluded.  See malloc_stats(3) and
       malloc_info(3) for alternatives that include information about other
       arenas.

       The fields of the mallinfo structure are typed as int.  However, because
       some internal bookkeeping values may be of type long, the reported values
       may wrap around zero and thus be inaccurate.

EXAMPLE top

       The program below employs mallinfo() to retrieve memory allocation
       statistics before and after allocating and freeing some blocks of memory.
       The statistics are displayed on standard output.

       The first two command-line arguments specify the number and size of blocks
       to be allocated with malloc(3).

       The remaining three arguments specify which of the allocated blocks should
       be freed with free(3).  These three arguments are optional, and specify (in
       order): the step size to be used in the loop that frees blocks (the default
       is 1, meaning free all blocks in the range); the ordinal position of the
       first block to be freed (default 0, meaning the first allocated block); and
       a number one greater than the ordinal position of the last block to be
       freed (default is one greater than the maximum block number).  If these
       three arguments are omitted, then the defaults cause all allocated blocks
       to be freed.

       In the following example run of the program, 1000 allocations of 100 bytes
       are performed, and then every second allocated block is freed:

           $ ./a.out 1000 100 2
           ============== Before allocating blocks ==============
           Total non-mmapped bytes (arena):       0
           # of free chunks (ordblks):            1
           # of free fastbin blocks (smblks):     0
           # of mapped regions (hblks):           0
           Bytes in mapped regions (hblkhd):      0
           Max. total allocated space (usmblks):  0
           Free bytes held in fastbins (fsmblks): 0
           Total allocated space (uordblks):      0
           Total free space (fordblks):           0
           Topmost releasable block (keepcost):   0

           ============== After allocating blocks ==============
           Total non-mmapped bytes (arena):       135168
           # of free chunks (ordblks):            1
           # of free fastbin blocks (smblks):     0
           # of mapped regions (hblks):           0
           Bytes in mapped regions (hblkhd):      0
           Max. total allocated space (usmblks):  0
           Free bytes held in fastbins (fsmblks): 0
           Total allocated space (uordblks):      104000
           Total free space (fordblks):           31168
           Topmost releasable block (keepcost):   31168

           ============== After freeing blocks ==============
           Total non-mmapped bytes (arena):       135168
           # of free chunks (ordblks):            501
           # of free fastbin blocks (smblks):     0
           # of mapped regions (hblks):           0
           Bytes in mapped regions (hblkhd):      0
           Max. total allocated space (usmblks):  0
           Free bytes held in fastbins (fsmblks): 0
           Total allocated space (uordblks):      52000
           Total free space (fordblks):           83168
           Topmost releasable block (keepcost):   31168

Program source

       #include <malloc.h>
       #include "tlpi_hdr.h"

       static void
       display_mallinfo(void)
       {
           struct mallinfo mi;

           mi = mallinfo();

           printf("Total non-mmapped bytes (arena):       %d\n", mi.arena);
           printf("# of free chunks (ordblks):            %d\n", mi.ordblks);
           printf("# of free fastbin blocks (smblks):     %d\n", mi.smblks);
           printf("# of mapped regions (hblks):           %d\n", mi.hblks);
           printf("Bytes in mapped regions (hblkhd):      %d\n", mi.hblkhd);
           printf("Max. total allocated space (usmblks):  %d\n", mi.usmblks);
           printf("Free bytes held in fastbins (fsmblks): %d\n", mi.fsmblks);
           printf("Total allocated space (uordblks):      %d\n", mi.uordblks);
           printf("Total free space (fordblks):           %d\n", mi.fordblks);
           printf("Topmost releasable block (keepcost):   %d\n", mi.keepcost);
       }

       int
       main(int argc, char *argv[])
       {
       #define MAX_ALLOCS 2000000
           char *alloc[MAX_ALLOCS];
           int numBlocks, j, freeBegin, freeEnd, freeStep;
           size_t blockSize;

           if (argc < 3 || strcmp(argv[1], "--help") == 0)
               usageErr("%s num-blocks block-size [free-step [start-free "
                       "[end-free]]]\n", argv[0]);

           numBlocks = atoi(argv[1]);
           blockSize = atoi(argv[2]);
           freeStep = (argc > 3) ? atoi(argv[3]) : 1;
           freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
           freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;

           printf("============== Before allocating blocks ==============\n");
           display_mallinfo();

           for (j = 0; j < numBlocks; j++) {
               if (numBlocks >= MAX_ALLOCS)
                   fatal("Too many allocations");

               alloc[j] = malloc(blockSize);
               if (alloc[j] == NULL)
                   errExit("malloc");
           }

           printf("\n============== After allocating blocks ==============\n");
           display_mallinfo();

           for (j = freeBegin; j < freeEnd; j += freeStep)
               free(alloc[j]);

           printf("\n============== After freeing blocks ==============\n");
           display_mallinfo();

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       mmap(2), malloc(3), malloc_info(3), malloc_stats(3), malloc_trim(3),
       mallopt(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-06                         MALLINFO(3)


malloc_get_state(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC_GET_STATE(3)          Linux Programmer's Manual         MALLOC_GET_STATE(3)

NAME top

       malloc_get_state,  malloc_set_state  -  record  and restore state of malloc
       implementation

SYNOPSIS top

       #include <stdlib.h>

       void* malloc_get_state(void);

       int malloc_set_state(void *state);

DESCRIPTION top

       The malloc_get_state() function records the current state of all malloc(3)
       internal bookkeeping variables (but not the actual contents of the heap or
       the state of malloc_hook(3) functions pointers).  The state is recorded in
       a system-dependent opaque data structure dynamically allocated via
       malloc(3), and a pointer to that data structure is returned as the function
       result.  (It is the caller's responsibility to free(3) this memory.)

       The malloc_set_state() function restores the state of all malloc(3)
       internal bookkeeping variables to the values recorded in the opaque data
       structure pointed to by state.

RETURN VALUE top

       On success, malloc_get_state() returns a pointer to a newly allocated
       opaque data structure.  On error (for example, memory could not be
       allocated for the data structure), malloc_get_state() returns NULL.

       On success, malloc_set_state() returns 0.  If the implementation detects
       that state does not point to a correctly formed data structure,
       malloc_set_state() returns -1.  If the implementation detects that the
       version of the data structure referred to by state is a more recent version
       than this implementation knows about, malloc_set_state() returns -2.

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       These functions are especially useful when using this malloc(3)
       implementation as part of a shared library, and the heap contents are
       saved/restored via some other method.  This technique is used by the GNU
       Emacs to implement its "dumping" function.

       Hook function pointers are never saved or restored by these functions, with
       two exceptions: if malloc checking (see mallopt(3)) was in use when
       malloc_get_state() was called, then malloc_set_state() resets malloc
       checking hooks if possible; if malloc checking was not in use in the
       recorded state, but the caller has requested malloc checking, then the
       hooks are reset to 0.

SEE ALSO top

       malloc(3), mallopt(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-04                 MALLOC_GET_STATE(3)


malloc_hook(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC_HOOK(3)               Linux Programmer's Manual              MALLOC_HOOK(3)

NAME top

       __malloc_hook,   __malloc_initialize_hook,   __memalign_hook,  __free_hook,
       __realloc_hook, __after_morecore_hook - malloc debugging variables

SYNOPSIS top

       #include <malloc.h>

       void *(*__malloc_hook)(size_t size, const void *caller);

       void *(*__realloc_hook)(void *ptr, size_t size, const void *caller);

       void *(*__memalign_hook)(size_t alignment, size_t size,
                                const void *caller);

       void (*__free_hook)(void *ptr, const void *caller);

       void (*__malloc_initialize_hook)(void);

       void (*__after_morecore_hook)(void);

DESCRIPTION top

       The GNU C library lets you modify the behavior of malloc(3), realloc(3),
       and free(3) by specifying appropriate hook functions.  You can use these
       hooks to help you debug programs that use dynamic memory allocation, for
       example.

       The variable __malloc_initialize_hook points at a function that is called
       once when the malloc implementation is initialized.  This is a weak
       variable, so it can be overridden in the application with a definition like
       the following:

           void (*__malloc_initialize_hook)(void) = my_init_hook;

       Now the function my_init_hook() can do the initialization of all hooks.

       The four functions pointed to by __malloc_hook, __realloc_hook,
       __memalign_hook, __free_hook have a prototype like the functions malloc(3),
       realloc(3), memalign(3), free(3), respectively, except that they have a
       final argument caller that gives the address of the caller of malloc(3),
       etc.

       The variable __after_morecore_hook points at a function that is called each
       time after sbrk(2) was asked for more memory.

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       The use of these hook functions is not safe in multithreaded programs, and
       they are now deprecated.  Programmers should instead preempt calls to the
       relevant functions by defining and exporting functions such as "malloc" and
       "free".

EXAMPLE top

       Here is a short example of how to use these variables.

       #include <stdio.h>
       #include <malloc.h>

       /* Prototypes for our hooks.  */
       static void my_init_hook(void);
       static void *my_malloc_hook(size_t, const void *);

       /* Variables to save original hooks. */
       static void *(*old_malloc_hook)(size_t, const void *);

       /* Override initializing hook from the C library. */
       void (*__malloc_initialize_hook) (void) = my_init_hook;

       static void
       my_init_hook(void)
       {
           old_malloc_hook = __malloc_hook;
           __malloc_hook = my_malloc_hook;
       }

       static void *
       my_malloc_hook(size_t size, const void *caller)
       {
           void *result;

           /* Restore all old hooks */
           __malloc_hook = old_malloc_hook;

           /* Call recursively */
           result = malloc(size);

           /* Save underlying hooks */
           old_malloc_hook = __malloc_hook;

           /* printf() might call malloc(), so protect it too. */
           printf("malloc(%u) called from %p returns %p\n",
                   (unsigned int) size, caller, result);

           /* Restore our own hooks */
           __malloc_hook = my_malloc_hook;

           return result;
       }

SEE ALSO top

       mallinfo(3), malloc(3), mcheck(3), mtrace(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-13                      MALLOC_HOOK(3)


malloc_info(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC_INFO(3)               Linux Programmer's Manual              MALLOC_INFO(3)

NAME top

       malloc_info - export malloc state to a stream

SYNOPSIS top

       #include <malloc.h>

       int malloc_info(int options, FILE *fp);

DESCRIPTION top

       The malloc_info() function exports an XML string that describes the current
       state of the memory-allocation implementation in the caller.  The string is
       printed on the file stream fp.  The exported string includes information
       about all arenas (see malloc(3)).

       As currently implemented, options must be zero.

RETURN VALUE top

       On success, malloc_info() returns 0; on error, it returns -1.

ERRORS top

       EINVAL options was nonzero.

VERSIONS top

       malloc_info(3) was added to glibc in version 2.10.

CONFORMING TO top

       This function is a GNU extension.

NOTES top

       The memory-allocation information is provided as an XML string (rather than
       a C structure) because the information may change over time (according to
       changes in the underlying implementation).  The output XML string includes
       a version field.

       The open_memstream(3) function can be used to send the output of
       malloc_info() directly into a buffer in memory, rather than to a file.

       The malloc_info() function is designed to address deficiencies in
       malloc_stats(3) and mallinfo(3).

EXAMPLE top

       The program below takes up to four command-line arguments, of which the
       first three are mandatory.  The first argument specifies the number of
       threads that the program should create.  All of the threads, including the
       main thread, allocate the number of blocks of memory specified by the
       second argument.  The third argument controls the size of the blocks to be
       allocated.  The main thread creates blocks of this size, the second thread
       created by the program allocates blocks of twice this size, the third
       thread allocates blocks of three times this size, and so on.

       The program calls malloc_info() twice to display the memory-allocation
       state.  The first call takes place before any threads are created or memory
       allocated.  The second call is performed after all threads have allocated
       memory.

       In the following example, the command-line arguments specify the creation
       of one additional thread, and both the main thread and the additional
       thread allocate 10000 blocks of memory.  After the blocks of memory have
       been allocated, malloc_info() shows the state of two allocation arenas.

           $ getconf GNU_LIBC_VERSION
           glibc 2.13
           $ ./a.out 1 10000 100
           ============ Before allocating blocks ============
           <malloc version="1">
           <heap nr="0">
           <sizes>
           </sizes>
           <total type="fast" count="0" size="0"/>
           <total type="rest" count="0" size="0"/>
           <system type="current" size="135168"/>
           <system type="max" size="135168"/>
           <aspace type="total" size="135168"/>
           <aspace type="mprotect" size="135168"/>
           </heap>
           <total type="fast" count="0" size="0"/>
           <total type="rest" count="0" size="0"/>
           <system type="current" size="135168"/>
           <system type="max" size="135168"/>
           <aspace type="total" size="135168"/>
           <aspace type="mprotect" size="135168"/>
           </malloc>

           ============ After allocating blocks ============
           <malloc version="1">
           <heap nr="0">
           <sizes>
           </sizes>
           <total type="fast" count="0" size="0"/>
           <total type="rest" count="0" size="0"/>
           <system type="current" size="1081344"/>
           <system type="max" size="1081344"/>
           <aspace type="total" size="1081344"/>
           <aspace type="mprotect" size="1081344"/>
           </heap>
           <heap nr="1">
           <sizes>
           </sizes>
           <total type="fast" count="0" size="0"/>
           <total type="rest" count="0" size="0"/>
           <system type="current" size="1032192"/>
           <system type="max" size="1032192"/>
           <aspace type="total" size="1032192"/>
           <aspace type="mprotect" size="1032192"/>
           </heap>
           <total type="fast" count="0" size="0"/>
           <total type="rest" count="0" size="0"/>
           <system type="current" size="2113536"/>
           <system type="max" size="2113536"/>
           <aspace type="total" size="2113536"/>
           <aspace type="mprotect" size="2113536"/>
           </malloc>

Program source

       #include <unistd.h>
       #include <stdlib.h>
       #include <pthread.h>
       #include <malloc.h>
       #include <errno.h>

       static size_t blockSize;
       static int numThreads, numBlocks;

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

       static void *
       thread_func(void *arg)
       {
           int j;
           int tn = (int) arg;

           /* The multiplier '(2 + tn)' ensures that each thread (including
              the main thread) allocates a different amount of memory */

           for (j = 0; j < numBlocks; j++)
               if (malloc(blockSize * (2 + tn)) == NULL)
                   errExit("malloc-thread");

           sleep(100);         /* Sleep until main thread terminates */
           return NULL;
       }

       int
       main(int argc, char *argv[])
       {
           int j, tn, sleepTime;
           pthread_t *thr;

           if (argc < 4) {
               fprintf(stderr,
                       "%s num-threads num-blocks block-size [sleep-time]\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           numThreads = atoi(argv[1]);
           numBlocks = atoi(argv[2]);
           blockSize = atoi(argv[3]);
           sleepTime = (argc > 4) ? atoi(argv[4]) : 0;

           thr = calloc(numThreads, sizeof(pthread_t));
           if (thr == NULL)
               errExit("calloc");

           printf("============ Before allocating blocks ============\n");
           malloc_info(0, stdout);

           /* Create threads that allocate different amounts of memory */

           for (tn = 0; tn < numThreads; tn++) {
               errno = pthread_create(&thr[tn], NULL, thread_func,
                                      (void *) tn);
               if (errno != 0)
                   errExit("pthread_create");

               /* If we add a sleep interval after the start-up of each
                  thread, the threads likely won't contend for malloc
                  mutexes, and therefore additional arenas won't be
                  allocated (see malloc(3)). */

               if (sleepTime > 0)
                   sleep(sleepTime);
           }

           /* The main thread also allocates some memory */

           for (j = 0; j < numBlocks; j++)
               if (malloc(blockSize) == NULL)
                   errExit("malloc");

           sleep(2);           /* Give all threads a chance to
                                  complete allocations */

           printf("\n============ After allocating blocks ============\n");
           malloc_info(0, stdout);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       mallinfo(3), malloc(3), malloc_stats(3), mallopt(3), open_memstream(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-28                      MALLOC_INFO(3)


malloc_stats(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC_STATS(3)              Linux Programmer's Manual             MALLOC_STATS(3)

NAME top

       malloc_stats - print memory allocation statistics

SYNOPSIS top

       #include <malloc.h>

       void malloc_stats(void);

DESCRIPTION top

       The malloc_stats() function prints (on standard error) statistics about
       memory allocated by malloc(3) and related functions.  For each arena
       (allocation area), this function prints the total amount of memory
       allocated and the total number of bytes consumed by in-use allocations.
       (These two values correspond to the arena and uordblks fields retrieved by
       mallinfo(3).)  In addition, the function prints the sum of these two
       statistics for all arenas, and the maximum number of blocks and bytes that
       were ever simultaneously allocated using mmap(2).

CONFORMING TO top

       This function is a GNU extension.

NOTES top

       More detailed information about memory allocations in the main arena can be
       obtained using mallinfo(3).

SEE ALSO top

       mmap(2), mallinfo(3), malloc(3), malloc_info(3), mallopt(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-06                     MALLOC_STATS(3)


malloc_trim(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC_TRIM(3)               Linux Programmer's Manual              MALLOC_TRIM(3)

NAME top

       malloc_trim - release free memory from the top of the heap

SYNOPSIS top

       #include <malloc.h>

       void malloc_trim(size_t pad);

DESCRIPTION top

       The malloc_trim() function attempts to release free memory at the top of
       the heap (by calling sbrk(2) with a suitable argument).

       The pad argument specifies the amount of free space to leave untrimmed at
       the top of the heap.  If this argument is 0, only the minimum amount of
       memory is maintained at the top of the heap (i.e., one page or less).  A
       nonzero argument can be used to maintain some trailing space at the top of
       the heap in order to allow future allocations to be made without having to
       extend the heap with sbrk(2).

RETURN VALUE top

       The malloc_trim() function returns 1 if memory was actually released back
       to the system, or 0 if it was not possible to release any memory.

ERRORS top

       No errors are defined.

CONFORMING TO top

       This function is a GNU extension.

NOTES top

       This function is automatically called by free(3) in certain circumstances;
       see the discussion of M_TOP_PAD and M_TRIM_THRESHOLD in mallopt(3).

       This function cannot release free memory located at places other than the
       top of the heap.

NOTES top

       This function only releases memory in the main arena.

SEE ALSO top

       sbrk(2), malloc(3), mallopt(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-29                      MALLOC_TRIM(3)


malloc_usable_size(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOC_USABLE_SIZE(3)        Linux Programmer's Manual       MALLOC_USABLE_SIZE(3)

NAME top

       malloc_usable_size - obtain size of block of memory allocated from heap

SYNOPSIS top

       #include <malloc.h>

       size_t malloc_usable_size (void *ptr);

DESCRIPTION top

       The malloc_usable_size() function returns the number of usable bytes in the
       block pointed to by ptr, a pointer to a block of memory allocated by
       malloc(3) or a related function.

RETURN VALUE top

       malloc_usable_size() returns the number of usable bytes in the block of
       allocated memory pointed to by ptr.  If ptr is NULL, 0 is returned.

CONFORMING TO top

       This function is a GNU extension.

NOTES top

       The value returned by malloc_usable_size() may be greater than the
       requested size of the allocation because of alignment and minimum size
       constraints.  Although the excess bytes can be overwritten by the
       application without ill effects, this is not good programming practice: the
       number of excess bytes in an allocation depends on the underlying
       implementation.

       The main use of this function is for debugging and introspection.

SEE ALSO top

       malloc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-29               MALLOC_USABLE_SIZE(3)


mallopt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MALLOPT(3)                   Linux Programmer's Manual                  MALLOPT(3)

NAME top

       mallopt - set memory allocation parameters

SYNOPSIS top

       #include <malloc.h>

       int mallopt(int param, int value);

DESCRIPTION top

       The mallopt() function adjusts parameters that control the behavior of the
       memory-allocation functions (see malloc(3)).  The param argument specifies
       the parameter to be modified, and value specifies the new value for that
       parameter.

       The following values can be specified for param:

       M_CHECK_ACTION
              Setting this parameter controls how glibc responds when various
              kinds of programming errors are detected (e.g., freeing the same
              pointer twice).  The 3 least significant bits (2, 1, and 0) of the
              value assigned to this parameter determine the glibc behavior, as
              follows:

              Bit 0  If this bit is set, then print a one-line message on stderr
                     that provides details about the error.  The message starts
                     with the string "*** glibc detected ***", followed by the
                     program name, the name of the memory-allocation function in
                     which the error was detected, a brief description of the
                     error, and the memory address where the error was detected.

              Bit 1  If this bit is set, then, after printing any error message
                     specified by bit 0, the program is terminated by calling
                     abort(3).  In glibc versions since 2.4, if bit 0 is also set,
                     then, between printing the error message and aborting, the
                     program also prints a stack trace in the manner of
                     backtrace(3), and prints the process's memory mapping in the
                     style of /proc/[pid]/maps (see proc(5)).

              Bit 2 (since glibc 2.4)
                     This bit has an effect only if bit 0 is also set.  If this
                     bit is set, then the one-line message describing the error is
                     simplified to contain just the name of the function where the
                     error was detected and the brief description of the error.

              The remaining bits in value are ignored.

              Combining the above details, the following numeric values are
              meaningful for M_CHECK_ACTION:

                   0  Ignore error conditions; continue execution (with undefined
                      results).

                   1  Print a detailed error message and continue execution.

                   2  Abort the program.

                   3  Print detailed error message, stack trace, and memory
                      mappings, and abort the program.

                   5  Print a simple error message and continue execution.

                   7  Print simple error message, stack trace, and memory
                      mappings, and abort the program.

              Since glibc 2.3.4, the default value for the M_CHECK_ACTION
              parameter is 3.  In glibc version 2.3.3 and earlier, the default
              value is 1.

              Using a nonzero M_CHECK_ACTION value can be useful because otherwise
              a crash may happen much later, and the true cause of the problem is
              then very hard to track down.

       M_MMAP_MAX
              This parameter specifies the maximum number of allocation requests
              that may be simultaneously serviced using mmap(2).  This parameter
              exists because some systems have a limited number of internal tables
              for use by mmap(2), and using more than a few of them may degrade
              performance.

              The default value is 65,536, a value which has no special
              significance and which servers only as a safeguard.  Setting this
              parameter to 0 disables the use of mmap(2) for servicing large
              allocation requests.

       M_MMAP_THRESHOLD
              For allocations greater than or equal to the limit specified (in
              bytes) by M_MMAP_THRESHOLD that can't be satisfied from the free
              list, the memory-allocation functions employ mmap(2) instead of
              increasing the program break using sbrk(2).

              Allocating memory using mmap(2) has the significant advantage that
              the allocated memory blocks can always be independently released
              back to the system.  (By contrast, the heap can be trimmed only if
              memory is freed at the top end.)  On the other hand, there are some
              disadvantages to the use of mmap(2): deallocated space is not placed
              on the free list for reuse by later allocations; memory may be
              wasted because mmap(2) allocations must be page-aligned; and the
              kernel must perform the expensive task of zeroing out memory
              allocated via mmap(2).  Balancing these factors leads to a default
              setting of 128*1024 for the M_MMAP_THRESHOLD parameter.

              The lower limit for this parameter is 0.  The upper limit is
              DEFAULT_MMAP_THRESHOLD_MAX: 512*1024 on 32-bit systems or
              4*1024*1024*sizeof(long) on 64-bit systems.

              Note: Nowadays, glibc uses a dynamic mmap threshold by default.  The
              initial value of the threshold is 128*1024, but when blocks larger
              than the current threshold and less than or equal to
              DEFAULT_MMAP_THRESHOLD_MAX are freed, the threshold is adjusted
              upwards to the size of the freed block.  When dynamic mmap
              thresholding is in effect, the threshold for trimming the heap is
              also dynamically adjusted to be twice the dynamic mmap threshold.
              Dynamic adjustment of the mmap threshold is disabled if any of the
              M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, or M_MMAP_MAX
              parameters is set.

       M_MXFAST (since glibc 2.3)
              Set the upper limit for memory allocation requests that are
              satisfied using "fastbins".  (The measurement unit for this
              parameter is bytes.)  Fastbins are storage areas that hold
              deallocated blocks of memory of the same size without merging
              adjacent free blocks.  Subsequent reallocation of blocks of the same
              size can be handled very quickly by allocating from the fastbin,
              although memory fragmentation and the overall memory footprint of
              the program can increase.  The default value for this parameter is
              64*sizeof(size_t)/4 (i.e., 64 on 32-bit architectures).  The range
              for this parameter is 0 to 80*sizeof(size_t)/4.  Setting M_MXFAST to
              0 disables the use of fastbins.

       M_PERTURB (since glibc 2.4)
              If this parameter is set to a nonzero value, then bytes of allocated
              memory (other than allocations via calloc(3)) are initialized to the
              complement of the value in the least significant byte of value, and
              when allocated memory is released using free(3), the freed bytes are
              set to the least significant byte of value.  This can be useful for
              detecting errors where programs incorrectly rely on allocated memory
              being initialized to zero, or reuse values in memory that has
              already been freed.

       M_TOP_PAD
              This parameter defines the amount of padding to employ when calling
              sbrk(2) to modify the program break.  (The measurement unit for this
              parameter is bytes.)  This parameter has an effect in the following
              circumstances:

              *  When the program break is increased, then M_TOP_PAD bytes are
                 added to the sbrk(2) request.

              *  When the heap is trimmed as a consequence of calling free(3) (see
                 the discussion of M_TRIM_THRESHOLD) this much free space is
                 preserved at the top of the heap.

              In either case, the amount of padding is always rounded to a system
              page boundary.

              Modifying M_TOP_PAD is a trade-off between increasing the number of
              system calls (when the parameter is set low) and wasting unused
              memory at the top of the heap (when the parameter is set high).

              The default value for this parameter is 128*1024.

       M_TRIM_THRESHOLD
              When the amount of contiguous free memory at the top of the heap
              grows sufficiently large, free(3) employs sbrk(2) to release this
              memory back to the system.  (This can be useful in programs that
              continue to execute for a long period after freeing a significant
              amount of memory.)  The M_TRIM_THRESHOLD parameter specifies the
              minimum size (in bytes) that this block of memory must reach before
              sbrk(2) is used to trim the heap.

              The default value for this parameter is 128*1024.  Setting
              M_TRIM_THRESHOLD to -1 disables trimming completely.

              Modifying M_TRIM_THRESHOLD is a trade-off between increasing the
              number of system calls (when the parameter is set low) and wasting
              unused memory at the top of the heap (when the parameter is set
              high).

Environment Variables

       A number of environment variables can be defined to modify some of the same
       parameters as are controlled by mallopt().  Using these variables has the
       advantage that the source code of the program need not be changed.  To be
       effective, these variables must be defined before the first call to a
       memory-allocation function.  (If the same parameters are adjusted via
       mallopt() then the mallopt() settings take precedence.)  For security
       reasons, these variables are ignored in set-user-ID and set-group-ID
       programs.

       The environment variables are as follows (note the trailing underscore at
       the end of the name of each variable):

       MALLOC_CHECK_
              This environment variable controls the same parameter as mallopt()
              M_CHECK_ACTION.  If this variable is set to a nonzero value, then a
              special implementation of the memory-allocation functions is used.
              (This is accomplished using the malloc_hook(3) feature.)  This
              implementation performs additional error checking, but is slower
              than the standard set of memory-allocation functions.  (This
              implementation does not detect all possible errors; memory leaks can
              still occur.)

              The value assigned to this environment variable should be a single
              digit, whose meaning is as described for M_CHECK_ACTION.  Any
              characters beyond the initial digit are ignored.

              For security reasons, the effect of MALLOC_CHECK_ is disabled by
              default for set-user-ID and set-group-ID programs.  However, if the
              file /etc/suid-debug exists (the content of the file is irrelevant),
              then MALLOC_CHECK_ also has an effect for set-user-ID and set-group-
              ID programs.

       MALLOC_MMAP_MAX_
              Controls the same parameter as mallopt() M_MMAP_MAX.

       MALLOC_MMAP_THRESHOLD_
              Controls the same parameter as mallopt() M_MMAP_THRESHOLD.

       MALLOC_PERTURB_
              Controls the same parameter as mallopt() M_PERTURB.

       MALLOC_TRIM_THRESHOLD_
              Controls the same parameter as mallopt() M_TRIM_THRESHOLD.

       MALLOC_TOP_PAD_
              Controls the same parameter as mallopt() M_TOP_PAD.

RETURN VALUE top

       On success, mallopt() returns 1.  On error, it returns 0.

ERRORS top

       On error, errno is not set.

CONFORMING TO top

       This function is not specified by POSIX or the C standards.  A similar
       function exists on many System V derivatives, but the range of values for
       param varies across systems.  The SVID defined options M_MXFAST, M_NLBLKS,
       M_GRAIN, and M_KEEP, but only the first of these is implemented in glibc.

BUGS top

       Specifying an invalid value for param does not generate an error.

       A calculation error within the glibc implementation means that a call of
       the form:

           mallopt(M_MXFAST, n)

       does not result in fastbins being employed for all allocations of size up
       to n.  To ensure desired results, n should be rounded up to the next
       multiple greater than or equal to (2k+1)*sizeof(size_t), where k is an
       integer.

       The MALLOC_MMAP_THRESHOLD_ and MALLOC_MMAP_MAX_ variables are not ignored
       in set-group-ID programs.

       If mallopt() is used to set M_PERTURB, then, as expected, the bytes of
       allocated memory are initialized to the complement of the byte in value,
       and when that memory is freed, the bytes of the region are initialized to
       the byte specified in value.  However, there is an off-by-sizeof(size_t)
       error in the implementation: instead of initializing precisely the block of
       memory being freed by the call free(p), the block starting at
       p+sizeof(size_t) is initialized.

EXAMPLE top

       The program below demonstrates the use of M_CHECK_ACTION.  If the program
       is supplied with an (integer) command-line argument, then that argument is
       used to set the M_CHECK_ACTION parameter.  The program then allocates a
       block of memory, and frees it twice (an error).

       The following shell session shows what happens when we run this program
       under glibc, with the default value for M_CHECK_ACTION:

           $ ./a.out
           main(): returned from first free() call
           *** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
           ======= Backtrace: =========
           /lib/libc.so.6(+0x6c501)[0x523501]
           /lib/libc.so.6(+0x6dd70)[0x524d70]
           /lib/libc.so.6(cfree+0x6d)[0x527e5d]
           ./a.out[0x80485db]
           /lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
           ./a.out[0x8048471]
           ======= Memory map: ========
           001e4000-001fe000 r-xp 00000000 08:06 1083555    /lib/libgcc_s.so.1
           001fe000-001ff000 r--p 00019000 08:06 1083555    /lib/libgcc_s.so.1
           [some lines omitted]
           b7814000-b7817000 rw-p 00000000 00:00 0
           bff53000-bff74000 rw-p 00000000 00:00 0          [stack]
           Aborted (core dumped)

       The following runs show the results when employing other values for
       M_CHECK_ACTION:

           $ ./a.out 1             # Diagnose error and continue
           main(): returned from first free() call
           *** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
           main(): returned from second free() call
           $ ./a.out 2             # Abort without error message
           main(): returned from first free() call
           Aborted (core dumped)
           $ ./a.out 0             # Ignore error and continue
           main(): returned from first free() call
           main(): returned from second free() call

       The next run shows how to set the same parameter using the MALLOC_CHECK_
       environment variable:

           $ MALLOC_CHECK_=1 ./a.out
           main(): returned from first free() call
           *** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
           main(): returned from second free() call

Program source

       #include <malloc.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           char *p;

           if (argc > 1) {
               if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
                   fprintf(stderr, "mallopt() failed");
                   exit(EXIT_FAILURE);
               }
           }

           p = malloc(1000);
           if (p == NULL) {
               fprintf(stderr, "malloc() failed");
               exit(EXIT_FAILURE);
           }

           free(p);
           printf("main(): returned from first free() call\n");

           free(p);
           printf("main(): returned from second free() call\n");

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       mmap(2), sbrk(2), mallinfo(3), malloc(3), malloc_hook(3), malloc_info(3),
       malloc_stats(3), malloc_trim(3), mcheck(3), mtrace(3), posix_memalign(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-30                          MALLOPT(3)


man-pages(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MAN-PAGES(7)                 Linux Programmer's Manual                MAN-PAGES(7)

NAME top

       man-pages - conventions for writing Linux man pages

SYNOPSIS top

       man [section] title

DESCRIPTION top

       This page describes the conventions that should be employed when writing
       man pages for the Linux man-pages project, which comprises Sections 2, 3,
       4, 5, and 7 of the Linux manual pages.  The conventions described on this
       page may also be useful for authors writing man pages for other projects.

Sections of the Manual Pages

       The manual Sections are traditionally defined as follows:

       1 Commands (Programs)
                 Those commands that can be executed by the user from within a
                 shell.

       2 System calls
                 Those functions which must be performed by the kernel.

       3 Library calls
                 Most of the libc functions.

       4 Special files (devices)
                 Files found in /dev.

       5 File formats and conventions
                 The format for /etc/passwd and other human-readable files.

       6 Games

       7 Conventions and miscellaneous
                 Overviews of various topics, conventions and protocols, character
                 set standards, and miscellaneous other things.

       8 System management commands
                 Commands like mount(8), many of which only root can execute.

Macro package

       New manual pages should be marked up using the groff an.tmac package
       described in man(7).  This choice is mainly for consistency: the vast
       majority of existing Linux manual pages are marked up using these macros.

Conventions for source file layout

       Please limit source code line length to no more than about 75 characters
       wherever possible.  This helps avoid line-wrapping in some mail clients
       when patches are submitted inline.

       New sentences should be started on new lines.  This makes it easier to see
       the effect of patches, which often operate at the level of individual
       sentences.

Title line

       The first command in a man page should be a TH command:

              .TH title section date source manual

       where:

              title     The title of the man page, written in all caps (e.g., MAN-
                        PAGES).

              section   The section number in which the man page should be placed
                        (e.g., 7).

              date      The date of the last revision--remember to change this
                        every time a change is made to the man page, since this is
                        the most general way of doing version control.  Dates
                        should be written in the form YYYY-MM-DD.

              source    The source of the command, function, or system call.

                        For those few man-pages pages in Sections 1 and 8,
                        probably you just want to write GNU.

                        For system calls, just write Linux.  (An earlier practice
                        was to write the version number of the kernel from which
                        the manual page was being written/checked.  However, this
                        was never done consistently, and so was probably worse
                        than including no version number.  Henceforth, avoid
                        including a version number.)

                        For library calls that are part of glibc or one of the
                        other common GNU libraries, just use GNU C Library, GNU,
                        or an empty string.

                        For Section 4 pages, use Linux.

                        In cases of doubt, just write Linux, or GNU.

              manual    The title of the manual (e.g., for Section 2 and 3 pages
                        in the man-pages package, use Linux Programmer's Manual).

Sections within a manual page

       The list below shows conventional or suggested sections.  Most manual pages
       should include at least the highlighted sections.  Arrange a new manual
       page so that sections are placed in the order shown in the list.

            NAME
            SYNOPSIS
            CONFIGURATION      [Normally only in Section 4]
            DESCRIPTION
            OPTIONS            [Normally only in Sections 1, 8]
            EXIT STATUS        [Normally only in Sections 1, 8]
            RETURN VALUE       [Normally only in Sections 2, 3]
            ERRORS             [Typically only in Sections 2, 3]
            ENVIRONMENT
            FILES
            VERSIONS           [Normally only in Sections 2, 3]
            CONFORMING TO
            NOTES
            BUGS
            EXAMPLE
            SEE ALSO

       Where a traditional heading would apply, please use it; this kind of
       consistency can make the information easier to understand.  If you must,
       you can create your own headings if they make things easier to understand
       (this can be especially useful for pages in Sections 4 and 5).  However,
       before doing this, consider whether you could use the traditional headings,
       with some subsections (.SS) within those sections.

       The following list elaborates on the contents of each of the above
       sections.

       NAME          The name of this manual page.  See man(7) for important
                     details of the line(s) that should follow the .SH NAME
                     command.  All words in this line (including the word
                     immediately following the "\-") should be in lowercase,
                     except where English or technical terminological convention
                     dictates otherwise.

       SYNOPSIS      briefly describes the command or function's interface.  For
                     commands, this shows the syntax of the command and its
                     arguments (including options); boldface is used for as-is
                     text and italics are used to indicate replaceable arguments.
                     Brackets ([]) surround optional arguments, vertical bars (|)
                     separate choices, and ellipses (...) can be repeated.  For
                     functions, it shows any required data declarations or
                     #include directives, followed by the function declaration.

                     Where a feature test macro must be defined in order to obtain
                     the declaration of a function (or a variable) from a header
                     file, then the SYNOPSIS should indicate this, as described in
                     feature_test_macros(7).

       CONFIGURATION Configuration details for a device.  This section normally
                     only appears in Section 4 pages.

       DESCRIPTION   gives an explanation of what the program, function, or format
                     does.  Discuss how it interacts with files and standard
                     input, and what it produces on standard output or standard
                     error.  Omit internals and implementation details unless
                     they're critical for understanding the interface.  Describe
                     the usual case; for information on command-line options of a
                     program use the OPTIONS section.

       OPTIONS       describes the command-line options accepted by a program and
                     how they change its behavior.  This section should only
                     appear for Section 1 and 8 manual pages.

       EXIT STATUS   lists the possible exit status values of a program and the
                     conditions that cause these values to be returned.  This
                     section should only appear for Section 1 and 8 manual pages.

       RETURN VALUE  For Section 2 and 3 pages, this section gives a list of the
                     values the library routine will return to the caller and the
                     conditions that cause these values to be returned.

       ERRORS        For Section 2 and 3 manual pages, this is a list of the
                     values that may be placed in errno in the event of an error,
                     along with information about the cause of the errors.  The
                     error list should be in alphabetical order.

       ENVIRONMENT   lists all environment variables that affect the program or
                     function and how they affect it.

       FILES         lists the files the program or function uses, such as
                     configuration files, startup files, and files the program
                     directly operates on.  Give the full pathname of these files,
                     and use the installation process to modify the directory part
                     to match user preferences.  For many programs, the default
                     installation location is in /usr/local, so your base manual
                     page should use /usr/local as the base.

       VERSIONS      A brief summary of the Linux kernel or glibc versions where a
                     system call or library function appeared, or changed
                     significantly in its operation.  As a general rule, every new
                     interface should include a VERSIONS section in its manual
                     page.  Unfortunately, many existing manual pages don't
                     include this information (since there was no policy to do so
                     when they were written).  Patches to remedy this are welcome,
                     but, from the perspective of programmers writing new code,
                     this information probably only matters in the case of kernel
                     interfaces that have been added in Linux 2.4 or later (i.e.,
                     changes since kernel 2.2), and library functions that have
                     been added to glibc since version 2.1 (i.e., changes since
                     glibc 2.0).

                     The syscalls(2) manual page also provides information about
                     kernel versions in which various system calls first appeared.

       CONFORMING TO describes any standards or conventions that relate to the
                     function or command described by the manual page.  For a page
                     in Section 2 or 3, this section should note the POSIX.1
                     version(s) that the call conforms to, and also whether the
                     call is specified in C99.  (Don't worry too much about other
                     standards like SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD
                     implementation standards, unless the call was specified in
                     those standards, but isn't in the current version of
                     POSIX.1.)  (See standards(7).)

                     If the call is not governed by any standards but commonly
                     exists on other systems, note them.  If the call is Linux-
                     specific, note this.

                     If this section consists of just a list of standards (which
                     it commonly does), terminate the list with a period ('.').

       NOTES         provides miscellaneous notes.  For Section 2 and 3 man pages
                     you may find it useful to include subsections (SS) named
                     Linux Notes and Glibc Notes.

       BUGS          lists limitations, known defects or inconveniences, and other
                     questionable activities.

       EXAMPLE       provides one or more examples describing how this function,
                     file or command is used.  For details on writing example
                     programs, see Example Programs below.

       AUTHORS       lists authors of the documentation or program.  Use of an
                     AUTHORS section is strongly discouraged.  Generally, it is
                     better not to clutter every page with a list of (over time
                     potentially numerous) authors; if you write or significantly
                     amend a page, add a copyright notice as a comment in the
                     source file.  If you are the author of a device driver and
                     want to include an address for reporting bugs, place this
                     under the BUGS section.

       SEE ALSO      provides a comma-separated list of related man pages, ordered
                     by section number and then alphabetically by name, possibly
                     followed by other related pages or documents.  Do not
                     terminate this with a period.

                     Where the SEE ALSO list contains many long manual page names,
                     to improve the visual result of the output, it may be useful
                     to employ the .ad l (don't right justify) and .nh (don't
                     hyphenate) directives.  Hyphenation of individual page names
                     can be prevented by preceding words with the string "\%".

Font conventions

       For functions, the arguments are always specified using italics, even in
       the SYNOPSIS section, where the rest of the function is specified in bold:

           int myfunction(int argc, char **argv);

       Variable names should, like argument names, be specified in italics.

       Filenames (whether pathnames, or references to files in the /usr/include
       directory) are always in italics (e.g., <stdio.h>), except in the SYNOPSIS
       section, where included files are in bold (e.g., #include <stdio.h>).  When
       referring to a standard include file under /usr/include, specify the header
       file surrounded by angle brackets, in the usual C way (e.g., <stdio.h>).

       Special macros, which are usually in upper case, are in bold (e.g.,
       MAXINT).  Exception: don't boldface NULL.

       When enumerating a list of error codes, the codes are in bold (this list
       usually uses the .TP macro).

       Complete commands should, if long, be written as in an indented line on
       their own, for example

           man 7 man-pages

       If the command is short, then it can be included inline in the text, in
       italic format, for example, man 7 man-pages.  In this case, it may be worth
       using nonbreaking spaces ("\ ") at suitable places in the command.  Command
       options should be written in italics, e.g., -l.

       Expressions, if not written on a separate indented line, should be
       specified in italics.  Again, the use of nonbreaking spaces may be
       appropriate if the expression is inlined with normal text.

       Any reference to the subject of the current manual page should be written
       with the name in bold.  If the subject is a function (i.e., this is a
       Section 2 or 3 page), then the name should be followed by a pair of
       parentheses in Roman (normal) font.  For example, in the fcntl(2) man page,
       references to the subject of the page would be written as: fcntl().  The
       preferred way to write this in the source file is:

           .BR fcntl ()

       (Using this format, rather than the use of "\fB...\fP()" makes it easier to
       write tools that parse man page source files.)

       Any reference to another man page should be written with the name in bold,
       always followed by the section number, formatted in Roman (normal) font,
       without any separating spaces (e.g., intro(2)).  The preferred way to write
       this in the source file is:

           .BR intro (2)

       (Including the section number in cross references lets tools like
       man2html(1) create properly hyperlinked pages.)

Spelling

       Starting with release 2.59, man-pages follows American spelling
       conventions; please write all new pages and patches according to these
       conventions.

Example Programs and Shell Sessions

       Manual pages can include example programs demonstrating how to use a system
       call or library function.  However, note the following:

       *  Example programs should be written in C.

       *  An example program is only necessary and useful if it demonstrates
          something beyond what can easily be provided in a textual description of
          the interface.  An example program that does nothing other than call an
          interface usually serves little purpose.

       *  Example programs should be fairly short (preferably less than 100 lines;
          ideally less than 50 lines).

       *  Example programs should do error checking after system calls and library
          function calls.

       *  Example programs should be complete, and compile without warnings when
          compiled with cc -Wall.

       *  Where possible and appropriate, example programs should allow
          experimentation, by varying their behavior based on inputs (ideally from
          command-line arguments, or alternatively, via input read by the
          program).

       *  Example programs should be laid out according to Kernighan and Ritchie
          style, with 4-space indents.  (Avoid the use of TAB characters in source
          code!)

       For some examples of what example programs should look like, see wait(2)
       and pipe(2).

       If you include a shell session demonstrating the use of a program or other
       system feature, boldface the user input text, to distinguish it from output
       produced by the system.

Indentation of structure definitions, shell session logs, etc.

       When structure definitions, shell session logs, and so on are included in
       running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n
       and .in).

EXAMPLE top

       For canonical examples of how man pages in the man-pages package should
       look, see pipe(2) and fcntl(2).

SEE ALSO top

       man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-21                        MAN-PAGES(7)


man(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MAN(7)                       Linux Programmer's Manual                      MAN(7)

NAME top

       man - macros to format man pages

SYNOPSIS top

       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

DESCRIPTION top

       This manual page explains the groff an.tmac macro package (often called the
       man macro package).  This macro package should be used by developers when
       writing or porting man pages for Linux.  It is fairly compatible with other
       versions of this macro package, so porting man pages should not be a major
       problem (exceptions include the NET-2 BSD release, which uses a totally
       different macro package called mdoc; see mdoc(7)).

       Note that NET-2 BSD mdoc man pages can be used with groff simply by
       specifying the -mdoc option instead of the -man option.  Using the -mandoc
       option is, however, recommended, since this will automatically detect which
       macro package is in use.

       For conventions that should be employed when writing man pages for the
       Linux man-pages package, see man-pages(7).

Title line

       The first command in a man page (after comment lines, that is, lines that
       start with .\") should be

              .TH title section date source manual

       For details of the arguments that should be supplied to the TH command, see
       man-pages(7).

       Note that BSD mdoc-formatted pages begin with the Dd command, not the TH
       command.

Sections

       Sections are started with .SH followed by the heading name.

       The only mandatory heading is NAME, which should be the first section and
       be followed on the next line by a one-line description of the program:

              .SH NAME
              item \- description

       It is extremely important that this format is followed, and that there is a
       backslash before the single dash which follows the item name.  This syntax
       is used by the mandb(8) program to create a database of short descriptions
       for the whatis(1) and apropos(1) commands.  (See lexgrog(1) for further
       details on the syntax of the NAME section.)

       For a list of other sections that might appear in a manual page, see man-
       pages(7).

Fonts

       The commands to select the type face are:

       .B  Bold

       .BI Bold alternating with italics (especially useful for function
           specifications)

       .BR Bold alternating with Roman (especially useful for referring to other
           manual pages)

       .I  Italics

       .IB Italics alternating with bold

       .IR Italics alternating with Roman

       .RB Roman alternating with bold

       .RI Roman alternating with italics

       .SB Small alternating with bold

       .SM Small (useful for acronyms)

       Traditionally, each command can have up to six arguments, but the GNU
       implementation removes this limitation (you might still want to limit
       yourself to 6 arguments for portability's sake).  Arguments are delimited
       by spaces.  Double quotes can be used to specify an argument which contains
       spaces.  All of the arguments will be printed next to each other without
       intervening spaces, so that the .BR command can be used to specify a word
       in bold followed by a mark of punctuation in Roman.  If no arguments are
       given, the command is applied to the following line of text.

Other Macros and Strings

       Below are other relevant macros and predefined strings.  Unless noted
       otherwise, all macros cause a break (end the current line of text).  Many
       of these macros set or use the "prevailing indent."  The "prevailing
       indent" value is set by any macro with the parameter i below; macros may
       omit i in which case the current prevailing indent will be used.  As a
       result, successive indented paragraphs can use the same indent without
       respecifying the indent value.  A normal (nonindented) paragraph resets the
       prevailing indent value to its default value (0.5 inches).  By default a
       given indent is measured in ens; try to use ens or ems as units for
       indents, since these will automatically adjust to font size changes.  The
       other key macro definitions are:

Normal Paragraphs

       .LP      Same as .PP (begin a new paragraph).

       .P       Same as .PP (begin a new paragraph).

       .PP      Begin a new paragraph and reset prevailing indent.

Relative Margin Indent

       .RS i    Start relative margin indent: moves the left margin i to the right
                (if i is omitted, the prevailing indent value is used).  A new
                prevailing indent is set to 0.5 inches.  As a result, all
                following paragraph(s) will be indented until the corresponding
                .RE.

       .RE      End relative margin indent and restores the previous value of the
                prevailing indent.

Indented Paragraph Macros

       .HP i    Begin paragraph with a hanging indent (the first line of the
                paragraph is at the left margin of normal paragraphs, and the rest
                of the paragraph's lines are indented).

       .IP x i  Indented paragraph with optional hanging tag.  If the tag x is
                omitted, the entire following paragraph is indented by i.  If the
                tag x is provided, it is hung at the left margin before the
                following indented paragraph (this is just like .TP except the tag
                is included with the command instead of being on the following
                line).  If the tag is too long, the text after the tag will be
                moved down to the next line (text will not be lost or garbled).
                For bulleted lists, use this macro with \(bu (bullet) or \(em (em
                dash) as the tag, and for numbered lists, use the number or letter
                followed by a period as the tag; this simplifies translation to
                other formats.

       .TP i    Begin paragraph with hanging tag.  The tag is given on the next
                line, but its results are like those of the .IP command.

Hypertext Link Macros

       (Feature supported with groff only.)  In order to use hypertext link
       macros, it is necessary to load the www.tmac macro package.  Use the
       request .mso www.tmac to do this.

       .URL url link trailer
                Inserts a hypertext link to the URI (URL) url, with link as the
                text of the link.  The trailer will be printed immediately
                afterward.  When generating HTML this should translate into the
                HTML command <A HREF="url">link</A>trailer.

                This and other related macros are new, and many tools won't do
                anything with them, but since many tools (including troff) will
                simply ignore undefined macros (or at worst insert their text)
                these are safe to insert.

                It can be useful to define your own URL macro in manual pages for
                the benefit of those viewing it with a roff viewer other than
                groff.  That way, the URL, link text, and trailer text (if any)
                are still visible.

                Here's an example:
                      .de URL
                      \\$2 \(laURL: \\$1 \(ra\\$3
                      ..
                      .if \n[.g] .mso www.tmac
                      .TH ...
                      (later in the page)
                      This software comes from the
                      .URL "http://www.gnu.org/" "GNU Project" " of the"
                      .URL "http://www.fsf.org/" "Free Software Foundation" .

                In the above, if groff is being used, the www.tmac macro package's
                definition of the URL macro will supersede the locally defined
                one.

       A number of other link macros are available.  See groff_www(7) for more
       details.

Miscellaneous Macros

       .DT      Reset tabs to default tab values (every 0.5 inches); does not
                cause a break.

       .PD d    Set inter-paragraph vertical distance to d (if omitted, d=0.4v);
                does not cause a break.

       .SS t    Subheading t (like .SH, but used for a subsection inside a
                section).

Predefined Strings

       The man package has the following predefined strings:

       \*R    Registration Symbol: (R)

       \*S    Change to default font size

       \*(Tm  Trademark Symbol: tm

       \*(lq  Left angled double quote: "

       \*(rq  Right angled double quote: "

Safe Subset

       Although technically man is a troff macro package, in reality a large
       number of other tools process man page files that don't implement all of
       troff's abilities.  Thus, it's best to avoid some of troff's more exotic
       abilities where possible to permit these other tools to work correctly.
       Avoid using the various troff preprocessors (if you must, go ahead and use
       tbl(1), but try to use the IP and TP commands instead for two-column
       tables).  Avoid using computations; most other tools can't process them.
       Use simple commands that are easy to translate to other formats.  The
       following troff macros are believed to be safe (though in many cases they
       will be ignored by translators): \", ., ad, bp, br, ce, de, ds, el, ie, if,
       fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

       You may also use many troff escape sequences (those sequences beginning
       with \).  When you need to include the backslash character as normal text,
       use \e.  Other sequences you may use, where x or xx are any characters and
       N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N,
       \nx, \n(xx, \fx, and \f(xx.  Avoid using the escape sequences for drawing
       graphics.

       Do not use the optional parameter for bp (break page).  Use only positive
       values for sp (vertical space).  Don't define a macro (de) with the same
       name as a macro in this or the mdoc macro package with a different meaning;
       it's likely that such redefinitions will be ignored.  Every positive indent
       (in) should be paired with a matching negative indent (although you should
       be using the RS and RE macros instead).  The condition test (if,ie) should
       only have 't' or 'n' as the condition.  Only translations (tr) that can be
       ignored should be used.  Font changes (ft and the \f escape sequence)
       should only have the values 1, 2, 3, 4, R, I, B, P, or CW (the ft command
       may also have no parameters).

       If you use capabilities beyond these, check the results carefully on
       several tools.  Once you've confirmed that the additional capability is
       safe, let the maintainer of this document know about the safe command or
       sequence that should be added to this list.

FILES top

       /usr/share/groff/[*/]tmac/an.tmac
       /usr/man/whatis

NOTES top

       By all means include full URLs (or URIs) in the text itself; some tools
       such as man2html(1) can automatically turn them into hypertext links.  You
       can also use the new URL macro to identify links to related information.
       If you include URLs, use the full URL (e.g., <http://www.kernelnotes.org>)
       to ensure that tools can automatically find the URLs.

       Tools processing these files should open the file and examine the first
       nonwhitespace character.  A period (.) or single quote (') at the beginning
       of a line indicates a troff-based file (such as man or mdoc).  A left angle
       bracket (<) indicates an SGML/XML-based file (such as HTML or Docbook).
       Anything else suggests simple ASCII text (e.g., a "catman" result).

       Many man pages begin with '\" followed by a space and a list of characters,
       indicating how the page is to be preprocessed.  For portability's sake to
       non-troff translators we recommend that you avoid using anything other than
       tbl(1), and Linux can detect that automatically.  However, you might want
       to include this information so your man page can be handled by other (less
       capable) systems.  Here are the definitions of the preprocessors invoked by
       these characters:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

BUGS top

       Most of the macros describe formatting (e.g., font type and spacing)
       instead of marking semantic content (e.g., this text is a reference to
       another page), compared to formats like mdoc and DocBook (even HTML has
       more semantic markings).  This situation makes it harder to vary the man
       format for different media, to make the formatting consistent for a given
       media, and to automatically insert cross-references.  By sticking to the
       safe subset described above, it should be easier to automate transitioning
       to a different reference page format in the future.

       The Sun macro TX is not implemented.

SEE ALSO top

       apropos(1), groff(1), lexgrog(1), man(1), man2html(1), whatis(1),
       groff_man(7), groff_www(7), man-pages(7), mdoc(7), mdoc.samples(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                              MAN(7)


matherr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MATHERR(3)                   Linux Programmer's Manual                  MATHERR(3)

NAME top

       matherr - SVID math library exception handling

SYNOPSIS top

       #define _SVID_SOURCE             /* See feature_test_macros(7) */
       #include <math.h>

       int matherr(struct exception *exc);

       extern _LIB_VERSION_TYPE _LIB_VERSION;

       Link with -lm.

DESCRIPTION top

       The System V Interface Definition (SVID) specifies that various math
       functions should invoke a function called matherr() if a math exception is
       detected.  This function is called before the math function returns; after
       matherr() returns, the system then returns to the math function, which in
       turn returns to the caller.

       The matherr() mechanism is supported by glibc, but is now obsolete: new
       applications should use the techniques described in math_error(7) and
       fenv(3).  This page documents the glibc matherr() mechanism as an aid for
       maintaining and porting older applications.

       To employ matherr(), the programmer must define the _SVID_SOURCE feature
       test macro (before including any header files), and assign the value _SVID_
       to the external variable _LIB_VERSION.

       The system provides a default version of matherr().  This version does
       nothing, and returns zero (see below for the significance of this).  The
       default matherr() can be overridden by a programmer-defined version, which
       will be invoked when an exception occurs.  The function is invoked with one
       argument, a pointer to an exception structure, defined as follows:

           struct exception {
               int    type;      /* Exception type */
               char  *name;      /* Name of function causing exception */
               double arg1;      /* 1st argument to function */
               double arg2;      /* 2nd argument to function */
               double retval;    /* Function return value */
           }

       The type field has one of the following values:

       DOMAIN      A domain error occurred (the function argument was outside the
                   range for which the function is defined).  The return value
                   depends on the function; errno is set to EDOM.

       SING        A pole error occurred (the function result is an infinity).
                   The return value in most cases is HUGE (the largest single
                   precision floating-point number), appropriately signed.  In
                   most cases, errno is set to EDOM.

       OVERFLOW    An overflow occurred.  In most cases, the value HUGE is
                   returned, and errno is set to ERANGE.

       UNDERFLOW   An underflow occurred.  0.0 is returned, and errno is set to
                   ERANGE.

       TLOSS       Total loss of significance.  0.0 is returned, and errno is set
                   to ERANGE.

       PLOSS       Partial loss of significance.  This value is unused on glibc
                   (and many other systems).

       The arg1 and arg2 fields are the arguments supplied to the function (arg2
       is undefined for functions that take only one argument).

       The retval field specifies the return value that the math function will
       return to its caller.  The programmer-defined matherr() can modify this
       field to change the return value of the math function.

       If the matherr() function returns zero, then the system sets errno as
       described above, and may print an error message on standard error (see
       below).

       If the matherr() function returns a nonzero value, then the system does not
       set errno, and doesn't print an error message.

Math functions that employ matherr()

       The table below lists the functions and circumstances in which matherr() is
       called.  The "Type" column indicates the value assigned to exc->type when
       calling matherr().  The "Result" column is the default return value
       assigned to exc->retval.

       The "Msg?" and "errno" columns describe the default behavior if matherr()
       returns zero.  If the "Msg?" columns contains "y", then the system prints
       an error message on standard error.

       The table uses the following notations and abbreviations:

              x        first argument to function
              y        second argument to function
              fin      finite value for argument
              neg      negative value for argument
              int      integral value for argument
              o/f      result overflowed
              u/f      result underflowed
              |x|      absolute value of x
              X_TLOSS  is a constant defined in <math.h>

       Function             Type        Result         Msg?   errno
       acos(|x|>1)          DOMAIN      HUGE            y     EDOM
       asin(|x|>1)          DOMAIN      HUGE            y     EDOM
       atan2(0,0)           DOMAIN      HUGE            y     EDOM
       acosh(x<1)           DOMAIN      NAN             y     EDOM
       atanh(|x|>1)         DOMAIN      NAN             y     EDOM
       atanh(|x|==1)        SING        (x>0.0)?        y     EDOM
                                        HUGE_VAL :
                                        -HUGE_VAL
       cosh(fin) o/f        OVERFLOW    HUGE            n     ERANGE
       sinh(fin) o/f        OVERFLOW    (x>0.0) ?       n     ERANGE
                                        HUGE : -HUGE
       sqrt(x<0)            DOMAIN      0.0             y     EDOM
       hypot(fin,fin) o/f   OVERFLOW    HUGE            n     ERANGE
       exp(fin) o/f         OVERFLOW    HUGE            n     ERANGE
       exp(fin) u/f         UNDERFLOW   0.0             n     ERANGE
       exp2(fin) o/f        OVERFLOW    HUGE            n     ERANGE
       exp2(fin) u/f        UNDERFLOW   0.0             n     ERANGE
       exp10(fin) o/f       OVERFLOW    HUGE            n     ERANGE
       exp10(fin) u/f       UNDERFLOW   0.0             n     ERANGE
       j0(|x|>X_TLOSS)      TLOSS       0.0             y     ERANGE
       j1(|x|>X_TLOSS)      TLOSS       0.0             y     ERANGE
       jn(|x|>X_TLOSS)      TLOSS       0.0             y     ERANGE
       y0(x>X_TLOSS)        TLOSS       0.0             y     ERANGE
       y1(x>X_TLOSS)        TLOSS       0.0             y     ERANGE

       yn(x>X_TLOSS)        TLOSS       0.0             y     ERANGE
       y0(0)                DOMAIN      -HUGE           y     EDOM
       y0(x<0)              DOMAIN      -HUGE           y     EDOM
       y1(0)                DOMAIN      -HUGE           y     EDOM
       y1(x<0)              DOMAIN      -HUGE           y     EDOM
       yn(n,0)              DOMAIN      -HUGE           y     EDOM
       yn(x<0)              DOMAIN      -HUGE           y     EDOM
       lgamma(fin) o/f      OVERFLOW    HUGE            n     ERANGE
       lgamma(-int) or      SING        HUGE            y     EDOM
         lgamma(0)
       tgamma(fin) o/f      OVERFLOW    HUGE_VAL        n     ERANGE
       tgamma(-int)         SING        NAN             y     EDOM
       tgamma(0)            SING        copysign(       y     ERANGE
                                        HUGE_VAL,x)
       log(0)               SING        -HUGE           y     EDOM
       log(x<0)             DOMAIN      -HUGE           y     EDOM
       log2(0)              SING        -HUGE           n     EDOM
       log2(x<0)            DOMAIN      -HUGE           n     EDOM
       log10(0)             SING        -HUGE           y     EDOM
       log10(x<0)           DOMAIN      -HUGE           y     EDOM
       pow(0.0,0.0)         DOMAIN      0.0             y     EDOM
       pow(x,y) o/f         OVERFLOW    HUGE            n     ERANGE
       pow(x,y) u/f         UNDERFLOW   0.0             n     ERANGE
       pow(NaN,0.0)         DOMAIN      x               n     EDOM
       0**neg               DOMAIN      0.0             y     EDOM
       neg**non-int         DOMAIN      0.0             y     EDOM
       scalb() o/f          OVERFLOW    (x>0.0) ?       n     ERANGE
                                        HUGE_VAL :
                                        -HUGE_VAL
       scalb() u/f          UNDERFLOW   copysign(       n     ERANGE
                                          0.0,x)
       fmod(x,0)            DOMAIN      x               y     EDOM
       remainder(x,0)       DOMAIN      NAN             y     EDOM

EXAMPLE top

       The example program demonstrates the use of matherr() when calling log(3).
       The program takes up to three command-line arguments.  The first argument
       is the floating-point number to be given to log(3).  If the optional second
       argument is provided, then _LIB_VERSION is set to _SVID_ so that matherr()
       is called, and the integer supplied in the command-line argument is used as
       the return value from matherr().  If the optional third command-line
       argument is supplied, then it specifies an alternative return value that
       matherr() should assign as the return value of the math function.

       The following example run, where log(3) is given an argument of 0.0, does
       not use matherr():

           $ ./a.out 0.0
           errno: Numerical result out of range
           x=-inf

       In the following run, matherr() is called, and returns 0:

           $ ./a.out 0.0 0
           matherr SING exception in log() function
                   args:   0.000000, 0.000000
                   retval: -340282346638528859811704183484516925440.000000
           log: SING error
           errno: Numerical argument out of domain
           x=-340282346638528859811704183484516925440.000000

       The message "log: SING error" was printed by the C library.

       In the following run, matherr() is called, and returns a nonzero value:

           $ ./a.out 0.0 1
           matherr SING exception in log() function
                   args:   0.000000, 0.000000
                   retval: -340282346638528859811704183484516925440.000000
           x=-340282346638528859811704183484516925440.000000

       In this case, the C library did not print a message, and errno was not set.

       In the following run, matherr() is called, changes the return value of the
       math function, and returns a nonzero value:

           $ ./a.out 0.0 1 12345.0
           matherr SING exception in log() function
                   args:   0.000000, 0.000000
                   retval: -340282346638528859811704183484516925440.000000
           x=12345.000000

Program source

       #define _SVID_SOURCE
       #include <errno.h>
       #include <math.h>
       #include <stdio.h>
       #include <stdlib.h>

       static int matherr_ret = 0;     /* Value that matherr()
                                          should return */
       static int change_retval = 0;   /* Should matherr() change
                                          function's return value? */
       static double new_retval;       /* New function return value */

       int
       matherr(struct exception *exc)
       {
           fprintf(stderr, "matherr %s exception in %s() function\n",
                  (exc->type == DOMAIN) ?    "DOMAIN" :
                  (exc->type == OVERFLOW) ?  "OVERFLOW" :
                  (exc->type == UNDERFLOW) ? "UNDERFLOW" :
                  (exc->type == SING) ?      "SING" :
                  (exc->type == TLOSS) ?     "TLOSS" :
                  (exc->type == PLOSS) ?     "PLOSS" : "???",
                   exc->name);
           fprintf(stderr, "        args:   %f, %f\n",
                   exc->arg1, exc->arg2);
           fprintf(stderr, "        retval: %f\n", exc->retval);

           if (change_retval)
               exc->retval = new_retval;

           return matherr_ret;
       }

       int
       main(int argc, char *argv[])
       {
           double x;

           if (argc < 2) {
               fprintf(stderr, "Usage: %s <argval>"
                       " [<matherr-ret> [<new-func-retval>]]\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           if (argc > 2) {
               _LIB_VERSION = _SVID_;
               matherr_ret = atoi(argv[2]);
           }

           if (argc > 3) {
               change_retval = 1;
               new_retval = atof(argv[3]);
           }

           x = log(atof(argv[1]));
           if (errno != 0)
               perror("errno");

           printf("x=%f\n", x);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fenv(3), math_error(7), standards(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10                          MATHERR(3)


math_error(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MATH_ERROR(7)                Linux Programmer's Manual               MATH_ERROR(7)

NAME top

       math_error - detecting errors from mathematical functions

SYNOPSIS top

       #include <math.h>
       #include <errno.h>
       #include <fenv.h>

DESCRIPTION top

       When an error occurs, most library functions indicate this fact by
       returning a special value (e.g., -1 or NULL).  Because they typically
       return a floating-point number, the mathematical functions declared in
       <math.h> indicate an error using other mechanisms.  There are two error-
       reporting mechanisms: the older one sets errno; the newer one uses the
       floating-point exception mechanism (the use of feclearexcept(3) and
       fetestexcept(3), as outlined below) described in fenv(3).

       A portable program that needs to check for an error from a mathematical
       function should set errno to zero, and make the following call

           feclearexcept(FE_ALL_EXCEPT);

       before calling a mathematical function.

       Upon return from the mathematical function, if errno is nonzero, or the
       following call (see fenv(3)) returns nonzero

           fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |
                        FE_UNDERFLOW);

       then an error occurred in the mathematical function.

       The error conditions that can occur for mathematical functions are
       described below.

Domain Error

       A domain error occurs when a mathematical function is supplied with an
       argument whose value falls outside the domain for which the function is
       defined (e.g., giving a negative argument to log(3)).  When a domain error
       occurs, math functions commonly return a NaN (though some functions return
       a different value in this case); errno is set to EDOM, and an "invalid"
       (FE_INVALID) floating-point exception is raised.

Pole Error

       A pole error occurs when the mathematical result of a function is an exact
       infinity (e.g., the logarithm of 0 is negative infinity).  When a pole
       error occurs, the function returns the (signed) value HUGE_VAL, HUGE_VALF,
       or HUGE_VALL, depending on whether the function result type is double,
       float, or long double.  The sign of the result is that which is
       mathematically correct for the function.  errno is set to ERANGE, and a
       "divide-by-zero" (FE_DIVBYZERO) floating-point exception is raised.

Range Error

       A range error occurs when the magnitude of the function result means that
       it cannot be represented in the result type of the function.  The return
       value of the function depends on whether the range error was an overflow or
       an underflow.

       A floating result overflows if the result is finite, but is too large to
       represented in the result type.  When an overflow occurs, the function
       returns the value HUGE_VAL, HUGE_VALF, or HUGE_VALL, depending on whether
       the function result type is double, float, or long double.  errno is set to
       ERANGE, and an "overflow" (FE_OVERFLOW) floating-point exception is raised.

       A floating result underflows if the result is too small to be represented
       in the result type.  If an underflow occurs, a mathematical function
       typically returns 0.0 (C99 says a function shall return "an implementation-
       defined value whose magnitude is no greater than the smallest normalized
       positive number in the specified type").  errno may be set to ERANGE, and
       an "overflow" (FE_UNDERFLOW) floating-point exception may be raised.

       Some functions deliver a range error if the supplied argument value, or the
       correct function result, would be subnormal.  A subnormal value is one that
       is nonzero, but with a magnitude that is so small that it can't be
       presented in normalized form (i.e., with a 1 in the most significant bit of
       the significand).  The representation of a subnormal number will contain
       one or more leading zeros in the significand.

NOTES top

       The math_errhandling identifier specified by C99 and POSIX.1-2001 is not
       supported by glibc.  This identifier is supposed to indicate which of the
       two error-notification mechanisms (errno, exceptions retrievable via
       fettestexcept(3)) is in use.  The standards require that at least one be in
       use, but permit both to be available.  The current (version 2.8) situation
       under glibc is messy.  Most (but not all) functions raise exceptions on
       errors.  Some also set errno.  A few functions set errno, but don't raise
       an exception.  A very few functions do neither.  See the individual manual
       pages for details.

       To avoid the complexities of using errno and fetestexcept(3) for error
       checking, it is often advised that one should instead check for bad
       argument values before each call.  For example, the following code ensures
       that log(3)'s argument is not a NaN and is not zero (a pole error) or less
       than zero (a domain error):

           double x, r;

           if (isnan(x) || islessequal(x, 0)) {
               /* Deal with NaN / pole error / domain error */
           }

           r = log(x);

       The discussion on this page does not apply to the complex mathematical
       functions (i.e., those declared by <complex.h>), which in general are not
       required to return errors by C99 and POSIX.1-2001.

       The gcc(1) -fno-math-errno option causes the executable to employ
       implementations of some mathematical functions that are faster than the
       standard implementations, but do not set errno on error.  (The gcc(1)
       -ffast-math option also enables -fno-math-errno.)  An error can still be
       tested for using fetestexcept(3).

SEE ALSO top

       gcc(1), errno(3), fenv(3), fpclassify(3), INFINITY(3), isgreater(3),
       matherr(3), nan(3)

       info libc

COLOPHON top

       This page is part of release 3.45 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-11                       MATH_ERROR(7)


mbind(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBIND(2)                     Linux Programmer's Manual                    MBIND(2)

NAME top

       mbind - set memory policy for a memory range

SYNOPSIS top

       #include <numaif.h>

       int mbind(void *addr, unsigned long len, int mode,
                 unsigned long *nodemask, unsigned long maxnode,
                 unsigned flags);

       Link with -lnuma.

DESCRIPTION top

       mbind() sets the NUMA memory policy, which consists of a policy mode and
       zero or more nodes, for the memory range starting with addr and continuing
       for len bytes.  The memory policy defines from which node memory is
       allocated.

       If the memory range specified by the addr and len arguments includes an
       "anonymous" region of memory--that is a region of memory created using the
       mmap(2) system call with the MAP_ANONYMOUS--or a memory mapped file, mapped
       using the mmap(2) system call with the MAP_PRIVATE flag, pages will only be
       allocated according to the specified policy when the application writes
       [stores] to the page.  For anonymous regions, an initial read access will
       use a shared page in the kernel containing all zeros.  For a file mapped
       with MAP_PRIVATE, an initial read access will allocate pages according to
       the process policy of the process that causes the page to be allocated.
       This may not be the process that called mbind().

       The specified policy will be ignored for any MAP_SHARED mappings in the
       specified memory range.  Rather the pages will be allocated according to
       the process policy of the process that caused the page to be allocated.
       Again, this may not be the process that called mbind().

       If the specified memory range includes a shared memory region created using
       the shmget(2) system call and attached using the shmat(2) system call,
       pages allocated for the anonymous or shared memory region will be allocated
       according to the policy specified, regardless which process attached to the
       shared memory segment causes the allocation.  If, however, the shared
       memory region was created with the SHM_HUGETLB flag, the huge pages will be
       allocated according to the policy specified only if the page allocation is
       caused by the process that calls mbind() for that region.

       By default, mbind() only has an effect for new allocations; if the pages
       inside the range have been already touched before setting the policy, then
       the policy has no effect.  This default behavior may be overridden by the
       MPOL_MF_MOVE and MPOL_MF_MOVE_ALL flags described below.

       The mode argument must specify one of MPOL_DEFAULT, MPOL_BIND,
       MPOL_INTERLEAVE or MPOL_PREFERRED.  All policy modes except MPOL_DEFAULT
       require the caller to specify via the nodemask argument, the node or nodes
       to which the mode applies.

       The mode argument may also include an optional mode flag .  The supported
       mode flags are:

       MPOL_F_STATIC_NODES (since Linux-2.6.26)
              A nonempty nodemask specifies physical node ids.  Linux does not
              remap the nodemask when the process moves to a different cpuset
              context, nor when the set of nodes allowed by the process's current
              cpuset context changes.

       MPOL_F_RELATIVE_NODES (since Linux-2.6.26)
              A nonempty nodemask specifies node ids that are relative to the set
              of node ids allowed by the process's current cpuset.

       nodemask points to a bitmask of nodes containing up to maxnode bits.  The
       bit mask size is rounded to the next multiple of sizeof(unsigned long), but
       the kernel will only use bits up to maxnode.  A NULL value of nodemask or a
       maxnode value of zero specifies the empty set of nodes.  If the value of
       maxnode is zero, the nodemask argument is ignored.  Where a nodemask is
       required, it must contain at least one node that is on-line, allowed by the
       process's current cpuset context [unless the MPOL_F_STATIC_NODES mode flag
       is specified], and contains memory.

       The MPOL_DEFAULT mode requests that any nondefault policy be removed,
       restoring default behavior.  When applied to a range of memory via mbind(),
       this means to use the process policy, which may have been set with
       set_mempolicy(2).  If the mode of the process policy is also MPOL_DEFAULT,
       the system-wide default policy will be used.  The system-wide default
       policy allocates pages on the node of the CPU that triggers the allocation.
       For MPOL_DEFAULT, the nodemask and maxnode arguments must be specify the
       empty set of nodes.

       The MPOL_BIND mode specifies a strict policy that restricts memory
       allocation to the nodes specified in nodemask.  If nodemask specifies more
       than one node, page allocations will come from the node with the lowest
       numeric node ID first, until that node contains no free memory.
       Allocations will then come from the node with the next highest node ID
       specified in nodemask and so forth, until none of the specified nodes
       contain free memory.  Pages will not be allocated from any node not
       specified in the nodemask.

       The MPOL_INTERLEAVE mode specifies that page allocations be interleaved
       across the set of nodes specified in nodemask.  This optimizes for
       bandwidth instead of latency by spreading out pages and memory accesses to
       those pages across multiple nodes.  To be effective the memory area should
       be fairly large, at least 1MB or bigger with a fairly uniform access
       pattern.  Accesses to a single page of the area will still be limited to
       the memory bandwidth of a single node.

       MPOL_PREFERRED sets the preferred node for allocation.  The kernel will try
       to allocate pages from this node first and fall back to other nodes if the
       preferred nodes is low on free memory.  If nodemask specifies more than one
       node ID, the first node in the mask will be selected as the preferred node.
       If the nodemask and maxnode arguments specify the empty set, then the
       memory is allocated on the node of the CPU that triggered the allocation.
       This is the only way to specify "local allocation" for a range of memory
       via mbind().

       If MPOL_MF_STRICT is passed in flags and mode is not MPOL_DEFAULT, then the
       call will fail with the error EIO if the existing pages in the memory range
       don't follow the policy.

       If MPOL_MF_MOVE is specified in flags, then the kernel will attempt to move
       all the existing pages in the memory range so that they follow the policy.
       Pages that are shared with other processes will not be moved.  If
       MPOL_MF_STRICT is also specified, then the call will fail with the error
       EIO if some pages could not be moved.

       If MPOL_MF_MOVE_ALL is passed in flags, then the kernel will attempt to
       move all existing pages in the memory range regardless of whether other
       processes use the pages.  The calling process must be privileged
       (CAP_SYS_NICE) to use this flag.  If MPOL_MF_STRICT is also specified, then
       the call will fail with the error EIO if some pages could not be moved.

RETURN VALUE top

       On success, mbind() returns 0; on error, -1 is returned and errno is set to
       indicate the error.

ERRORS top

       EFAULT Part or all of the memory range specified by nodemask and maxnode
              points outside your accessible address space.  Or, there was an
              unmapped hole in the specified memory range.

       EINVAL An invalid value was specified for flags or mode; or addr + len was
              less than addr; or addr is not a multiple of the system page size.
              Or, mode is MPOL_DEFAULT and nodemask specified a nonempty set; or
              mode is MPOL_BIND or MPOL_INTERLEAVE and nodemask is empty.  Or,
              maxnode exceeds a kernel-imposed limit.  Or, nodemask specifies one
              or more node IDs that are greater than the maximum supported node
              ID.  Or, none of the node IDs specified by nodemask are on-line and
              allowed by the process's current cpuset context, or none of the
              specified nodes contain memory.  Or, the mode argument specified
              both MPOL_F_STATIC_NODES and MPOL_F_RELATIVE_NODES.

       EIO    MPOL_MF_STRICT was specified and an existing page was already on a
              node that does not follow the policy; or MPOL_MF_MOVE or
              MPOL_MF_MOVE_ALL was specified and the kernel was unable to move all
              existing pages in the range.

       ENOMEM Insufficient kernel memory was available.

       EPERM  The flags argument included the MPOL_MF_MOVE_ALL flag and the caller
              does not have the CAP_SYS_NICE privilege.

VERSIONS top

       The mbind() system call was added to the Linux kernel in version 2.6.7.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       For information on library support, see numa(7).

       NUMA policy is not supported on a memory mapped file range that was mapped
       with the MAP_SHARED flag.

       The MPOL_DEFAULT mode can have different effects for mbind() and
       set_mempolicy(2).  When MPOL_DEFAULT is specified for set_mempolicy(2), the
       process's policy reverts to system default policy or local allocation.
       When MPOL_DEFAULT is specified for a range of memory using mbind(), any
       pages subsequently allocated for that range will use the process's policy,
       as set by set_mempolicy(2).  This effectively removes the explicit policy
       from the specified range, "falling back" to a possibly nondefault policy.
       To select explicit "local allocation" for a memory range, specify a mode of
       MPOL_PREFERRED with an empty set of nodes.  This method will work for
       set_mempolicy(2), as well.

       Support for huge page policy was added with 2.6.16.  For interleave policy
       to be effective on huge page mappings the policied memory needs to be tens
       of megabytes or larger.

       MPOL_MF_STRICT is ignored on huge page mappings.

       MPOL_MF_MOVE and MPOL_MF_MOVE_ALL are only available on Linux 2.6.16 and
       later.

SEE ALSO top

       get_mempolicy(2), getcpu(2), mmap(2), set_mempolicy(2), shmat(2),
       shmget(2), numa(3), cpuset(7), numa(7), numactl(8)

COLOPHON top

       This page is part of release 3.45 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-15                            MBIND(2)


mblen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBLEN(3)                     Linux Programmer's Manual                    MBLEN(3)

NAME top

       mblen - determine number of bytes in next multibyte character

SYNOPSIS top

       #include <stdlib.h>

       int mblen(const char *s, size_t n);

DESCRIPTION top

       If s is not a NULL pointer, the mblen() function inspects at most n bytes
       of the multibyte string starting at s and extracts the next complete
       multibyte character.  It uses a static anonymous shift state only known to
       the mblen() function.  If the multibyte character is not the null wide
       character, it returns the number of bytes that were consumed from s.  If
       the multibyte character is the null wide character, it returns 0.

       If the n bytes starting at s do not contain a complete multibyte character,
       mblen() returns -1.  This can happen even if n is greater than or equal to
       MB_CUR_MAX, if the multibyte string contains redundant shift sequences.

       If the multibyte string starting at s contains an invalid multibyte
       sequence before the next complete character, mblen() also returns -1.

       If s is a NULL pointer, the mblen() function resets the shift state, only
       known to this function, to the initial state, and returns nonzero if the
       encoding has nontrivial shift state, or zero if the encoding is stateless.

RETURN VALUE top

       The mblen() function returns the number of bytes parsed from the multibyte
       sequence starting at s, if a non-null wide character was recognized.  It
       returns 0, if a null wide character was recognized.  It returns -1, if an
       invalid multibyte sequence was encountered or if it couldn't parse a
       complete multibyte character.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mblen() depends on the LC_CTYPE category of the current
       locale.

       The function mbrlen(3) provides a better interface to the same
       functionality.

SEE ALSO top

       mbrlen(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                            MBLEN(3)


mbrlen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBRLEN(3)                    Linux Programmer's Manual                   MBRLEN(3)

NAME top

       mbrlen - determine number of bytes in next multibyte character

SYNOPSIS top

       #include <wchar.h>

       size_t mbrlen(const char *s, size_t n, mbstate_t *ps);

DESCRIPTION top

       The mbrlen() function inspects at most n bytes of the multibyte string
       starting at s and extracts the next complete multibyte character.  It
       updates the shift state *ps.  If the multibyte character is not the null
       wide character, it returns the number of bytes that were consumed from s.
       If the multibyte character is the null wide character, it resets the shift
       state *ps to the initial state and returns 0.

       If the n bytes starting at s do not contain a complete multibyte character,
       mbrlen() returns (size_t) -2.  This can happen even if n >= MB_CUR_MAX, if
       the multibyte string contains redundant shift sequences.

       If the multibyte string starting at s contains an invalid multibyte
       sequence before the next complete character, mbrlen() returns (size_t) -1
       and sets errno to EILSEQ.  In this case, the effects on *ps are undefined.

       If ps is a NULL pointer, a static anonymous state only known to the
       mbrlen() function is used instead.

RETURN VALUE top

       The mbrlen() function returns the number of bytes parsed from the multibyte
       sequence starting at s, if a non-null wide character was recognized.  It
       returns 0, if a null wide character was recognized.  It returns (size_t) -1
       and sets errno to EILSEQ, if an invalid multibyte sequence was encountered.
       It returns (size_t) -2 if it couldn't parse a complete multibyte character,
       meaning that n should be increased.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mbrlen() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       mbrtowc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           MBRLEN(3)


mbrtowc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBRTOWC(3)                   Linux Programmer's Manual                  MBRTOWC(3)

NAME top

       mbrtowc - convert a multibyte sequence to a wide character

SYNOPSIS top

       #include <wchar.h>

       size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

DESCRIPTION top

       The main case for this function is when s is not NULL and pwc is not NULL.
       In this case, the mbrtowc() function inspects at most n bytes of the
       multibyte string starting at s, extracts the next complete multibyte
       character, converts it to a wide character and stores it at *pwc.  It
       updates the shift state *ps.  If the converted wide character is not L'\0'
       (the null wide character), it returns the number of bytes that were
       consumed from s.  If the converted wide character is L'\0', it resets the
       shift state *ps to the initial state and returns 0.

       If the n bytes starting at s do not contain a complete multibyte character,
       mbrtowc() returns (size_t) -2.  This can happen even if n >= MB_CUR_MAX, if
       the multibyte string contains redundant shift sequences.

       If the multibyte string starting at s contains an invalid multibyte
       sequence before the next complete character, mbrtowc() returns (size_t) -1
       and sets errno to EILSEQ.  In this case, the effects on *ps are undefined.

       A different case is when s is not NULL but pwc is NULL.  In this case the
       mbrtowc() function behaves as above, except that it does not store the
       converted wide character in memory.

       A third case is when s is NULL.  In this case, pwc and n are ignored.  If
       the conversion state represented by *ps denotes an incomplete multibyte
       character conversion, the mbrtowc() function returns (size_t) -1, sets
       errno to EILSEQ, and leaves *ps in an undefined state.  Otherwise, the
       mbrtowc() function puts *ps in the initial state and returns 0.

       In all of the above cases, if ps is a NULL pointer, a static anonymous
       state only known to the mbrtowc function is used instead.  Otherwise, *ps
       must be a valid mbstate_t object.  An mbstate_t object a can be initialized
       to the initial state by zeroing it, for example using

           memset(&a, 0, sizeof(a));

RETURN VALUE top

       The mbrtowc() function returns the number of bytes parsed from the
       multibyte sequence starting at s, if a non-L'\0' wide character was
       recognized.  It returns 0, if a L'\0' wide character was recognized.  It
       returns (size_t) -1 and sets errno to EILSEQ, if an invalid multibyte
       sequence was encountered.  It returns (size_t) -2 if it couldn't parse a
       complete multibyte character, meaning that n should be increased.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mbrtowc() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       mbsrtowcs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          MBRTOWC(3)


mbsinit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBSINIT(3)                   Linux Programmer's Manual                  MBSINIT(3)

NAME top

       mbsinit - test for initial shift state

SYNOPSIS top

       #include <wchar.h>

       int mbsinit(const mbstate_t *ps);

DESCRIPTION top

       Character conversion between the multibyte representation and the wide
       character representation uses conversion state, of type mbstate_t.
       Conversion of a string uses a finite-state machine; when it is interrupted
       after the complete conversion of a number of characters, it may need to
       save a state for processing the remaining characters.  Such a conversion
       state is needed for the sake of encodings such as ISO-2022 and UTF-7.

       The initial state is the state at the beginning of conversion of a string.
       There are two kinds of state: The one used by multibyte to wide character
       conversion functions, such as mbsrtowcs(3), and the one used by wide
       character to multibyte conversion functions, such as wcsrtombs(3), but they
       both fit in a mbstate_t, and they both have the same representation for an
       initial state.

       For 8-bit encodings, all states are equivalent to the initial state.  For
       multibyte encodings like UTF-8, EUC-*, BIG5 or SJIS, the wide character to
       multibyte conversion functions never produce non-initial states, but the
       multibyte to wide-character conversion functions like mbrtowc(3) do produce
       non-initial states when interrupted in the middle of a character.

       One possible way to create an mbstate_t in initial state is to set it to
       zero:

           mbstate_t state;
           memset(&state,0,sizeof(mbstate_t));

       On Linux, the following works as well, but might generate compiler
       warnings:

           mbstate_t state = { 0 };

       The function mbsinit() tests whether *ps corresponds to an initial state.

RETURN VALUE top

       mbsinit() returns nonzero if *ps is an initial state, or if ps is a NULL
       pointer.  Otherwise it returns 0.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mbsinit() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       mbsrtowcs(3), wcsrtombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2000-11-20                          MBSINIT(3)


mbsnrtowcs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBSNRTOWCS(3)                Linux Programmer's Manual               MBSNRTOWCS(3)

NAME top

       mbsnrtowcs - convert a multibyte string to a wide-character string

SYNOPSIS top

       #include <wchar.h>

       size_t mbsnrtowcs(wchar_t *dest, const char **src,
                         size_t nms, size_t len, mbstate_t *ps);

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

       mbsnrtowcs():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The mbsnrtowcs() function is like the mbsrtowcs(3) function, except that
       the number of bytes to be converted, starting at *src, is limited to nms.

       If dest is not a NULL pointer, the mbsnrtowcs() function converts at most
       nms bytes from the multibyte string *src to a wide-character string
       starting at dest.  At most len wide characters are written to dest.  The
       shift state *ps is updated.  The conversion is effectively performed by
       repeatedly calling mbrtowc(dest, *src, n, ps) where n is some positive
       number, as long as this call succeeds, and then incrementing dest by one
       and *src by the number of bytes consumed.  The conversion can stop for
       three reasons:

       1. An invalid multibyte sequence has been encountered.  In this case *src
          is left pointing to the invalid multibyte sequence, (size_t) -1 is
          returned, and errno is set to EILSEQ.

       2. The nms limit forces a stop, or len non-L'\0' wide characters have been
          stored at dest.  In this case *src is left pointing to the next
          multibyte sequence to be converted, and the number of wide characters
          written to dest is returned.

       3. The multibyte string has been completely converted, including the
          terminating null wide character ('\0') (which has the side effect of
          bringing back *ps to the initial state).  In this case *src is set to
          NULL, and the number of wide characters written to dest, excluding the
          terminating null wide character, is returned.

       If dest is NULL, len is ignored, and the conversion proceeds as above,
       except that the converted wide characters are not written out to memory,
       and that no destination length limit exists.

       In both of the above cases, if ps is a NULL pointer, a static anonymous
       state only known to the mbsnrtowcs function is used instead.

       The programmer must ensure that there is room for at least len wide
       characters at dest.

RETURN VALUE top

       The mbsnrtowcs() function returns the number of wide characters that make
       up the converted part of the wide-character string, not including the
       terminating null wide character.  If an invalid multibyte sequence was
       encountered, (size_t) -1 is returned, and errno set to EILSEQ.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       The behavior of mbsnrtowcs() depends on the LC_CTYPE category of the
       current locale.

       Passing NULL as ps is not multithread safe.

SEE ALSO top

       iconv(3), mbsrtowcs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-01                       MBSNRTOWCS(3)


mbsrtowcs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBSRTOWCS(3)                 Linux Programmer's Manual                MBSRTOWCS(3)

NAME top

       mbsrtowcs - convert a multibyte string to a wide-character string

SYNOPSIS top

       #include <wchar.h>

       size_t mbsrtowcs(wchar_t *dest, const char **src,
                         size_t len, mbstate_t *ps);

DESCRIPTION top

       If dest is not a NULL pointer, the mbsrtowcs() function converts the
       multibyte string *src to a wide-character string starting at dest.  At most
       len wide characters are written to dest.  The shift state *ps is updated.
       The conversion is effectively performed by repeatedly calling mbrtowc(dest,
       *src, n, ps) where n is some positive number, as long as this call
       succeeds, and then incrementing dest by one and *src by the number of bytes
       consumed.  The conversion can stop for three reasons:

       1. An invalid multibyte sequence has been encountered.  In this case *src
          is left pointing to the invalid multibyte sequence, (size_t) -1 is
          returned, and errno is set to EILSEQ.

       2. len non-L'\0' wide characters have been stored at dest.  In this case
          *src is left pointing to the next multibyte sequence to be converted,
          and the number of wide characters written to dest is returned.

       3. The multibyte string has been completely converted, including the
          terminating null wide character ('\0'), which has the side effect of
          bringing back *ps to the initial state.  In this case *src is set to
          NULL, and the number of wide characters written to dest, excluding the
          terminating null wide character, is returned.

       If dest is NULL, len is ignored, and the conversion proceeds as above,
       except that the converted wide characters are not written out to memory,
       and that no length limit exists.

       In both of the above cases, if ps is a NULL pointer, a static anonymous
       state only known to the mbsrtowcs() function is used instead.

       The programmer must ensure that there is room for at least len wide
       characters at dest.

RETURN VALUE top

       The mbsrtowcs() function returns the number of wide characters that make up
       the converted part of the wide-character string, not including the
       terminating null wide character.  If an invalid multibyte sequence was
       encountered, (size_t) -1 is returned, and errno set to EILSEQ.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mbsrtowcs() depends on the LC_CTYPE category of the current
       locale.

       Passing NULL as ps is not multithread safe.

SEE ALSO top

       iconv(3), mbsnrtowcs(3), mbstowcs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                        MBSRTOWCS(3)


mbstowcs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBSTOWCS(3)                  Linux Programmer's Manual                 MBSTOWCS(3)

NAME top

       mbstowcs - convert a multibyte string to a wide-character string

SYNOPSIS top

       #include <stdlib.h>

       size_t mbstowcs(wchar_t *dest, const char *src, size_t n);

DESCRIPTION top

       If dest is not a NULL pointer, the mbstowcs() function converts the
       multibyte string src to a wide-character string starting at dest.  At most
       n wide characters are written to dest.  The conversion starts in the
       initial state.  The conversion can stop for three reasons:

       1. An invalid multibyte sequence has been encountered.  In this case
          (size_t) -1 is returned.

       2. n non-L'\0' wide characters have been stored at dest.  In this case the
          number of wide characters written to dest is returned, but the shift
          state at this point is lost.

       3. The multibyte string has been completely converted, including the
          terminating null wide character ('\0').  In this case the number of wide
          characters written to dest, excluding the terminating null wide
          character, is returned.

       The programmer must ensure that there is room for at least n wide
       characters at dest.

       If dest is NULL, n is ignored, and the conversion proceeds as above, except
       that the converted wide characters are not written out to memory, and that
       no length limit exists.

       In order to avoid the case 2 above, the programmer should make sure n is
       greater or equal to mbstowcs(NULL,src,0)+1.

RETURN VALUE top

       The mbstowcs() function returns the number of wide characters that make up
       the converted part of the wide-character string, not including the
       terminating null wide character.  If an invalid multibyte sequence was
       encountered, (size_t) -1 is returned.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mbstowcs() depends on the LC_CTYPE category of the current
       locale.

       The function mbsrtowcs(3) provides a better interface to the same
       functionality.

SEE ALSO top

       mbsrtowcs(3), wcstombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                         MBSTOWCS(3)


mbtowc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MBTOWC(3)                    Linux Programmer's Manual                   MBTOWC(3)

NAME top

       mbtowc - convert a multibyte sequence to a wide character

SYNOPSIS top

       #include <stdlib.h>

       int mbtowc(wchar_t *pwc, const char *s, size_t n);

DESCRIPTION top

       The main case for this function is when s is not NULL and pwc is not NULL.
       In this case, the mbtowc() function inspects at most n bytes of the
       multibyte string starting at s, extracts the next complete multibyte
       character, converts it to a wide character and stores it at *pwc.  It
       updates an internal shift state only known to the mbtowc function.  If s
       does not point to a null byte ('\0'), it returns the number of bytes that
       were consumed from s, otherwise it returns 0.

       If the n bytes starting at s do not contain a complete multibyte character,
       or if they contain an invalid multibyte sequence, mbtowc() returns -1.
       This can happen even if n >= MB_CUR_MAX, if the multibyte string contains
       redundant shift sequences.

       A different case is when s is not NULL but pwc is NULL.  In this case the
       mbtowc() function behaves as above, except that it does not store the
       converted wide character in memory.

       A third case is when s is NULL.  In this case, pwc and n are ignored.  The
       mbtowc() function resets the shift state, only known to this function, to
       the initial state, and returns nonzero if the encoding has nontrivial shift
       state, or zero if the encoding is stateless.

RETURN VALUE top

       If s is not NULL, the mbtowc() function returns the number of consumed
       bytes starting at s, or 0 if s points to a null byte, or -1 upon failure.

       If s is NULL, the mbtowc() function returns nonzero if the encoding has
       nontrivial shift state, or zero if the encoding is stateless.

CONFORMING TO top

       C99.

NOTES top

       The behavior of mbtowc() depends on the LC_CTYPE category of the current
       locale.

       This function is not multithread safe.  The function mbrtowc(3) provides a
       better interface to the same functionality.

SEE ALSO top

       MB_CUR_MAX(3), mbrtowc(3), mbstowcs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           MBTOWC(3)


MB_CUR_MAX(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MB_CUR_MAX(3)                Linux Programmer's Manual               MB_CUR_MAX(3)

NAME top

       MB_CUR_MAX - maximum length of a multibyte character in the current locale

SYNOPSIS top

       #include <stdlib.h>

DESCRIPTION top

       The MB_CUR_MAX macro defines an integer expression giving the maximum
       number of bytes needed to represent a single wide character in the current
       locale.  It is locale dependent and therefore not a compile-time constant.

RETURN VALUE top

       An integer in the range [1, MB_LEN_MAX].  The value 1 denotes traditional
       8-bit encoded characters.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       MB_LEN_MAX(3), mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3), wctomb(3)

COLOPHON top

       This page is part of release 3.45 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                               1999-07-04                       MB_CUR_MAX(3)


MB_LEN_MAX(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MB_LEN_MAX(3)                Linux Programmer's Manual               MB_LEN_MAX(3)

NAME top

       MB_LEN_MAX - maximum multibyte length of a character across all locales

SYNOPSIS top

       #include <limits.h>

DESCRIPTION top

       The MB_LEN_MAX macro is the upper bound for the number of bytes needed to
       represent a single wide character, across all locales.

RETURN VALUE top

       A constant integer greater than zero.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The entities MB_LEN_MAX and sizeof(wchar_t) are totally unrelated.  In
       glibc, MB_LEN_MAX is typically 6 while sizeof(wchar_t) is 4.

SEE ALSO top

       MB_CUR_MAX(3)

COLOPHON top

       This page is part of release 3.45 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                               1999-07-04                       MB_LEN_MAX(3)


mcheck(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MCHECK(3)                    Linux Programmer's Manual                   MCHECK(3)

NAME top

       mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap consistency check-
       ing

SYNOPSIS top

       #include <mcheck.h>

       int mcheck(void (*abortfunc)(enum mcheck_status mstatus));

       int mcheck_pedantic(void (*abortfunc)(enum mcheck_status mstatus));

       void mcheck_check_all(void);

       enum mcheck_status mprobe(void *ptr);

DESCRIPTION top

       The mcheck() function installs a set of debugging hooks for the malloc(3)
       family of memory-allocation functions.  These hooks cause certain
       consistency checks to be performed on the state of the heap.  The checks
       can detect application errors such as freeing a block of memory more than
       once or corrupting the bookkeeping data structures that immediately precede
       a block of allocated memory.

       To be effective, the mcheck() function must be called before the first call
       to malloc(3) or a related function.  In cases where this is difficult to
       ensure, linking the program with -mcheck inserts an implicit call to
       mcheck() (with a NULL argument) before the first call to a memory-
       allocation function.

       The mcheck_pedantic() function is similar to mcheck(), but performs checks
       on all allocated blocks whenever one of the memory-allocation functions is
       called.  This can be very slow!

       The mcheck_check_all() function causes an immediate check on all allocated
       blocks.  This call is only effective if mcheck() is called beforehand.

       If the system detects an inconsistency in the heap, the caller-supplied
       function pointed to by abortfunc is invoked with a single argument
       argument, mstatus, that indicates what type of inconsistency was detected.
       If abortfunc is NULL, a default function prints an error message on stderr
       and calls abort(3).

       The mprobe() function performs a consistency check on the block of
       allocated memory pointed to by ptr.  The mcheck() function should be called
       beforehand (otherwise mprobe() returns MCHECK_DISABLED).

       The following list describes the values returned by mprobe() or passed as
       the mstatus argument when abortfunc is invoked:

       MCHECK_DISABLED (mprobe() only)
              mcheck() was not called before the first memory allocation function
              was called.  Consistency checking is not possible.

       MCHECK_OK (mprobe() only)
              No inconsistency detected.

       MCHECK_HEAD
              Memory preceding an allocated block was clobbered.

       MCHECK_TAIL
              Memory following an allocated block was clobbered.

       MCHECK_FREE
              A block of memory was freed twice.

RETURN VALUE top

       mcheck() and mcheck_pedantic() return 0 on success, or -1 on error.

VERSIONS top

       The mcheck_pedantic() and mcheck_check_all() functions are available since
       glibc 2.2.  The mcheck() and mprobe() functions are present since at least
       glibc 2.0

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       Linking a program with -lmcheck and using the MALLOC_CHECK_ environment
       variable (described in mallopt(3)) cause the same kinds of errors to be
       detected.  But, using MALLOC_CHECK_ does not require the application to be
       relinked.

EXAMPLE top

       The program below calls mcheck() with a NULL argument and then frees the
       same block of memory twice.  The following shell session demonstrates what
       happens when running the program:

           $ ./a.out
           About to free

           About to free a second time
           block freed twice
           Aborted (core dumped)

Program source

       #include <stdlib.h>
       #include <stdio.h>
       #include <mcheck.h>

       int
       main(int argc, char *argv[])
       {
           char *p;

           if (mcheck(NULL) != 0) {
               fprintf(stderr, "mcheck() failed\n");

               exit(EXIT_FAILURE);
           }

           p = malloc(1000);

           fprintf(stderr, "About to free\n");
           free(p);
           fprintf(stderr, "\nAbout to free a second time\n");
           free(p);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       malloc(3), mallopt(3), mtrace(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-18                           MCHECK(3)


mdoc(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | PAGE STRUCTURE DOMAIN | MANUAL AND GENERAL TEXT DOMAIN MACROS | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

MDOC(7)                BSD Miscellaneous Information Manual                MDOC(7)

NAME top

     mdoc -- quick reference guide for the -mdoc macro package

SYNOPSIS top

     groff -mdoc files ...

DESCRIPTION top

     The -mdoc package is a set of content-based and domain-based macros used to
     format the BSD man pages.  The macro names and their meanings are listed
     below for quick reference; for a detailed explanation on using the package,
     see the tutorial sampler mdoc.samples(7).

     Note that this is not the usual macro package for Linux documentation,
     although it is used for documentation of several widely used programs; see
     man(7).

     The macros are described in two groups, the first includes the structural and
     physical page layout macros.  The second contains the manual and general text
     domain macros which differentiate the -mdoc package from other troff format-
     ting packages.

PAGE STRUCTURE DOMAIN top

Title Macros

     To create a valid manual page, these three macros, in this order, are
     required:
     .Dd   Month day, year                       Document date.
     .Dt   DOCUMENT_TITLE [section] [volume]     Title, in upper case.
     .Os   OPERATING_SYSTEM [version/release]    Operating system (BSD).

Page Layout Macros

     Section headers, paragraph breaks, lists and displays.
     .Sh   Section Headers.  Valid headers, in the order of presentation:
           NAME          Name section, should include the `.Nm' or `.Fn' and the
                         `.Nd' macros.
           SYNOPSIS      Usage.
           DESCRIPTION   General description, should include options and parame-
                         ters.
           RETURN VALUE  Sections two and three function calls.
           ENVIRONMENT   Describe environment variables.
           FILES         Files associated with the subject.
           EXAMPLES      Examples and suggestions.
           DIAGNOSTICS   Normally used for section four device interface diagnos-
                         tics.
           ERRORS        Sections two and three error and signal handling.
           SEE ALSO      Cross references and citations.
           CONFORMING TO
                         Conformance to standards if applicable.
           HISTORY       If a standard is not applicable, the history of the sub-
                         ject should be given.
           BUGS          Gotchas and caveats.
           other         Customized headers may be added at the authors discre-
                         tion.
     .Ss   Subsection Headers.
     .Pp   Paragraph Break.  Vertical space (one line).
     .D1   (D-one) Display-one Indent and display one text line.
     .Dl   (D-ell) Display-one literal.  Indent and display one line of literal
           text.
     .Bd   Begin-display block.  Display options:
           -ragged          Unjustified (ragged edges).
           -filled          Justified.
           -literal         Literal text or code.
           -file name       Read in named file and display.
           -offset string   Offset display.  Acceptable string values:
                            left        Align block on left (default).
                            center      Approximate center margin.
                            indent      Six constant width spaces (a tab).
                            indent-two  Two tabs.
                            right       Left aligns block 2 inches from right.
                            xxn         Where xx is a number from 4n to 99n.
                            Aa          Where Aa is a callable macro name.
                            string      The width of string is used.
     .Ed   End-display (matches .Bd).
     .Bl   Begin-list.  Create lists or columns.  Options:
           List-types
                 -bullet    Bullet Item List
                 -item      Unlabeled List
                 -enum      Enumerated List
                 -tag       Tag Labeled List
                 -diag      Diagnostic List
                 -hang      Hanging Labeled List
                 -ohang     Overhanging Labeled List
                 -inset     Inset or Run-on Labeled List
           List-parameters
                 -offset    (All lists.) See `.Bd' begin-display above.
                 -width     (-tag and -hang lists only.)  See `.Bd'.
                 -compact   (All lists.)  Suppresses blank lines.
     .El   End-list.
     .It   List item.

MANUAL AND GENERAL TEXT DOMAIN MACROS          top
     The manual and general text domain macros are special in that most of them
     are parsed for callable macros for example:

           .Op Fl s Ar file
                       Produces [-s file]

     In this example, the option enclosure macro `.Op' is parsed, and calls the
     callable content macro `Fl' which operates on the argument `s' and then calls
     the callable content macro `Ar' which operates on the argument `file'.  Some
     macros may be callable, but are not parsed and vice versa.  These macros are
     indicated in the parsed and callable columns below.

     Unless stated, manual domain macros share a common syntax:

           .Va argument [ . , ; : ( ) [ ] argument ... ]

     Note: Opening and closing punctuation characters are only recognized as such
     if they are presented one at a time.  The string `),' is not recognized as
     punctuation and will be output with a leading white space and in what ever
     font the calling macro uses.  The argument list `] ) ,' is recognized as
     three sequential closing punctuation characters and a leading white space is
     not output between the characters and the previous argument (if any).  The
     special meaning of a punctuation character may be escaped with the string
     `\&'.  For example the following string,

           .Ar file1 , file2 , file3 ) .   Produces file1, file2, file3).

Manual Domain Macros

     Name    Parsed    Callable     Description
     Ad      Yes       Yes          Address. (This macro may be deprecated.)
     An      Yes       Yes          Author name.
     Ar      Yes       Yes          Command-line argument.
     Cd      No        No           Configuration declaration (section four only).
     Cm      Yes       Yes          Command-line argument modifier.
     Dv      Yes       Yes          Defined variable (source code).
     Er      Yes       Yes          Error number (source code).
     Ev      Yes       Yes          Environment variable.
     Fa      Yes       Yes          Function argument.
     Fd      Yes       Yes          Function declaration.
     Fn      Yes       Yes          Function call (also .Fo and .Fc).
     Ic      Yes       Yes          Interactive command.
     Li      Yes       Yes          Literal text.
     Nm      Yes       Yes          Command name.
     Op      Yes       Yes          Option (also .Oo and .Oc).
     Ot      Yes       Yes          Old style function type (Fortran only).
     Pa      Yes       Yes          Pathname or filename.
     St      Yes       Yes          Standards (-p1003.2, -p1003.1 or -ansiC)
     Va      Yes       Yes          Variable name.
     Vt      Yes       Yes          Variable type (Fortran only).
     Xr      Yes       Yes          Manual Page Cross Reference.

General Text Domain Macros

     Name    Parsed    Callable     Description
     %A      Yes       No           Reference author.
     %B      Yes       Yes          Reference book title.
     %C      No        No           Reference place of publishing (city).
     %D      No        No           Reference date.
     %J      Yes       Yes          Reference journal title.
     %N      No        No           Reference issue number.
     %O      No        No           Reference optional information.
     %P      No        No           Reference page number(s).
     %R      No        No           Reference report Name.
     %T      Yes       Yes          Reference article title.
     %V      No        No           Reference volume.
     Ac      Yes       Yes          Angle close quote.
     Ao      Yes       Yes          Angle open quote.
     Ap      Yes       Yes          Apostrophe.
     Aq      Yes       Yes          Angle quote.
     At      No        No           AT&T UNIX
     Bc      Yes       Yes          Bracket close quote.
     Bf      No        No           Begin font mode.
     Bo      Yes       Yes          Bracket open quote.
     Bq      Yes       Yes          Bracket quote.
     Bx      Yes       Yes          BSD.
     Db      No        No           Debug (default is "off")
     Dc      Yes       Yes          Double close quote.
     Do      Yes       Yes          Double open quote.
     Dq      Yes       Yes          Double quote.
     Ec      Yes       Yes          Enclose string close quote.
     Ef      No        No           End font mode.
     Em      Yes       Yes          Emphasis (traditional English).
     Eo      Yes       Yes          Enclose string open quote.
     Fx      No        No           FreeBSD operating system
     No      Yes       Yes          Normal text (no-op).
     Ns      Yes       Yes          No space.
     Pc      Yes       Yes          Parenthesis close quote.
     Pf      Yes       No           Prefix string.
     Po      Yes       Yes          Parenthesis open quote.
     Pq      Yes       Yes          Parentheses quote.
     Qc      Yes       Yes          Straight Double close quote.
     Ql      Yes       Yes          Quoted literal.
     Qo      Yes       Yes          Straight Double open quote.
     Qq      Yes       Yes          Straight Double quote.
     Re      No        No           Reference end.
     Rs      No        No           Reference start.
     Rv      No        No           Return values (sections two and three only).
     Sc      Yes       Yes          Single close quote.
     So      Yes       Yes          Single open quote.
     Sq      Yes       Yes          Single quote.
     Sm      No        No           Space mode (default is "on")
     Sx      Yes       Yes          Section Cross Reference.
     Sy      Yes       Yes          Symbolic (traditional English).
     Tn      Yes       Yes          Trade or type name (small Caps).
     Ux      Yes       Yes          UNIX
     Xc      Yes       Yes          Extend argument list close.
     Xo      Yes       Yes          Extend argument list open.

     Macro names ending in `q' quote remaining items on the argument list.  Macro
     names ending in `o' begin a quote which may span more than one line of input
     and are close quoted with the matching macro name ending in `c'.  Enclosure
     macros may be nested and are limited to eight arguments.

     Note: the extended argument list macros (`.Xo', `.Xc') and the function
     enclosure macros (`.Fo', `.Fc') are irregular.  The extended list macros are
     used when the number of macro arguments would exceed the troff limitation of
     nine arguments.

     The macros UR (starting a URI/URL hypertext reference), UE (ending one), and
     UN (identifying a target for a reference) are also available.  See man(7) for
     more information on these macros.

FILES          top
     doc.tmac          Manual and general text domain macros.
     tmac/doc-common   Common structural macros and definitions.
     tmac/doc-nroff    Site dependent nroff style file.
     tmac/doc-ditroff  Site dependent troff style file.
     tmac/doc-syms     Special defines (such as the standards macro).

SEE ALSO          top
     groff_mdoc(7), mdoc.samples(7), man(7), man-pages(7)

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

Linux                              July 11, 1999                             Linux

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


mdoc.samples(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | GETTING STARTED | TROFF IDIOSYNCRASIES | THE ANATOMY OF A MAN PAGE | TITLE MACROS | INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS | MANUAL DOMAIN | GENERAL TEXT DOMAIN | PAGE STRUCTURE DOMAIN | PREDEFINED STRINGS | DIAGNOSTICS | GROFF, TROFF AND NROFF | FILES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MDOC.SAMPLES(7)        BSD Miscellaneous Information Manual        MDOC.SAMPLES(7)

NAME top

     mdoc.samples -- tutorial sampler for writing BSD manuals with -mdoc

SYNOPSIS top

     man mdoc.samples

DESCRIPTION top

     A tutorial sampler for writing BSD manual pages with the -mdoc macro package,
     a content-based and domain-based formatting package for troff(1).  Its prede-
     cessor, the -man(7) package, addressed page layout leaving the manipulation
     of fonts and other typesetting details to the individual author.  In -mdoc,
     page layout macros make up the page structure domain which consists of macros
     for titles, section headers, displays and lists.  Essentially items which
     affect the physical position of text on a formatted page.  In addition to the
     page structure domain, there are two more domains, the manual domain and the
     general text domain.  The general text domain is defined as macros which per-
     form tasks such as quoting or emphasizing pieces of text.  The manual domain
     is defined as macros that are a subset of the day to day informal language
     used to describe commands, routines and related BSD files.  Macros in the
     manual domain handle command names, command-line arguments and options, func-
     tion names, function parameters, pathnames, variables, cross references to
     other manual pages, and so on.  These domain items have value for both the
     author and the future user of the manual page.  It is hoped the consistency
     gained across the manual set will provide easier translation to future docu-
     mentation tools.

     Throughout the UNIX manual pages, a manual entry is simply referred to as a
     man page, regardless of actual length and without sexist intention.

GETTING STARTED top

     Since a tutorial document is normally read when a person desires to use the
     material immediately, the assumption has been made that the user of this doc-
     ument may be impatient.  The material presented in the remained of this docu-
     ment is outlined as follows:

           1.   TROFF IDIOSYNCRASIES
                      Macro Usage.
                      Passing Space Characters in an Argument.
                      Trailing Blank Space Characters (a warning).
                      Escaping Special Characters.

           2.   THE ANATOMY OF A MAN PAGE
                      A manual page template.

           3.   TITLE MACROS.

           4.   INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS.
                      What's in a name....
                      General Syntax.

           5.   MANUAL DOMAIN
                      Addresses.
                      Author name.
                      Arguments.
                      Configuration Declarations (section four only).
                      Command Modifier.
                      Defined Variables.
                      Errno's (Section two only).
                      Environment Variables.
                      Function Argument.
                      Function Declaration.
                      Flags.
                      Functions (library routines).
                      Function Types.
                      Interactive Commands.
                      Names.
                      Options.
                      Pathnames.
                      Variables.
                      Cross References.

           6.   GENERAL TEXT DOMAIN
                      AT&T Macro.
                      BSD Macro.
                      FreeBSD Macro.
                      UNIX Macro.
                      Enclosure/Quoting Macros
                                  Angle Bracket Quote/Enclosure.
                                  Bracket Quotes/Enclosure.
                                  Double Quote macro/Enclosure.
                                  Parenthesis Quote/Enclosure.
                                  Single Quotes/Enclosure.
                                  Prefix Macro.
                      No-Op or Normal Text Macro.
                      No Space Macro.
                      Section Cross References.
                      References and Citations.
                      Return Values (sections two and three only)
                      Trade Names (Acronyms and Type Names).
                      Extended  Arguments.

           7.   PAGE STRUCTURE DOMAIN
                      Section Headers.
                      Paragraphs and Line Spacing.
                      Keeps.
                      Displays.
                      Font Modes (Emphasis, Literal, and Symbolic).
                      Lists and Columns.

           8.   PREDEFINED STRINGS

           9.   DIAGNOSTICS

           10.  FORMATTING WITH GROFF, TROFF AND NROFF

           11.  BUGS

TROFF IDIOSYNCRASIES top

     The -mdoc package attempts to simplify the process of writing a man page.
     Theoretically, one should not have to learn the dirty details of troff(1) to
     use -mdoc; however, there are a few limitations which are unavoidable and
     best gotten out of the way.  And, too, be forewarned, this package is not
     fast.

Macro Usage

     As in troff(1), a macro is called by placing a `.' (dot character) at the
     beginning of a line followed by the two character name for the macro.  Argu-
     ments may follow the macro separated by spaces.  It is the dot character at
     the beginning of the line which causes troff(1) to interpret the next two
     characters as a macro name.  To place a `.' (dot character) at the beginning
     of a line in some context other than a macro invocation, precede the `.'
     (dot) with the `\&' escape sequence.  The `\&' translates literally to a zero
     width space, and is never displayed in the output.

     In general, troff(1) macros accept up to nine arguments, any extra arguments
     are ignored.  Most macros in -mdoc accept nine arguments and, in limited
     cases, arguments may be continued or extended on the next line (See
     Extensions).  A few macros handle quoted arguments (see Passing Space
     Characters in an Argument below).

     Most of the -mdoc general text domain and manual domain macros are special in
     that their argument lists are parsed for callable macro names.  This means an
     argument on the argument list which matches a general text or manual domain
     macro name and is determined to be callable will be executed or called when
     it is processed.  In this case the argument, although the name of a macro, is
     not preceded by a `.' (dot).  It is in this manner that many macros are
     nested; for example the option macro, `.Op', may call the flag and argument
     macros, `Fl' and `Ar', to specify an optional flag with an argument:

           [-s bytes]         is produced by .Op Fl s Ar bytes

     To prevent a two character string from being interpreted as a macro name,
     precede the string with the escape sequence `\&':

           [Fl s Ar bytes]    is produced by .Op \&Fl s \&Ar bytes

     Here the strings `Fl' and `Ar' are not interpreted as macros.  Macros whose
     argument lists are parsed for callable arguments are referred to as parsed
     and macros which may be called from an argument list are referred to as
     callable throughout this document and in the companion quick reference manual
     mdoc(7).  This is a technical faux pas as almost all of the macros in -mdoc
     are parsed, but as it was cumbersome to constantly refer to macros as being
     callable and being able to call other macros, the term parsed has been used.

Passing Space Characters in an Argument

     Sometimes it is desirable to give as one argument a string containing one or
     more blank space characters.  This may be necessary to defeat the nine argu-
     ment limit or to specify arguments to macros which expect particular arrange-
     ment of items in the argument list.  For example, the function macro `.Fn'
     expects the first argument to be the name of a function and any remaining
     arguments to be function parameters.  As ANSI C stipulates the declaration of
     function parameters in the parenthesized parameter list, each parameter is
     guaranteed to be at minimum a two word string.  For example, int foo.

     There are two possible ways to pass an argument which contains an embedded
     space.  Implementation note: Unfortunately, the most convenient way of pass-
     ing spaces in between quotes by reassigning individual arguments before pars-
     ing was fairly expensive speed wise and space wise to implement in all the
     macros for AT&T troff.  It is not expensive for groff but for the sake of
     portability, has been limited to the following macros which need it the most:

           Cd    Configuration declaration (section 4 SYNOPSIS)
           Bl    Begin list (for the width specifier).
           Em    Emphasized text.
           Fn    Functions (sections two and four).
           It    List items.
           Li    Literal text.
           Sy    Symbolic text.
           %B    Book titles.
           %J    Journal names.
           %O    Optional notes for a reference.
           %R    Report title (in a reference).
           %T    Title of article in a book or journal.

     One way of passing a string containing blank spaces is to use the hard or
     unpaddable space character `\ ', that is, a blank space preceded by the
     escape character `\'.  This method may be used with any macro but has the
     side effect of interfering with the adjustment of text over the length of a
     line.  Troff sees the hard space as if it were any other printable character
     and cannot split the string into blank or newline separated pieces as one
     would expect.  The method is useful for strings which are not expected to
     overlap a line boundary.  For example:

           fetch(char *str)  is created by `.Fn fetch char\ *str'

           fetch(char *str)  can also be created by `.Fn fetch "char *str"'

     If the `\' or quotes were omitted, `.Fn' would see three arguments and the
     result would be:

           fetch(char, *str)

     For an example of what happens when the parameter list overlaps a newline
     boundary, see the BUGS section.

Trailing Blank Space Characters

     Troff can be confused by blank space characters at the end of a line.  It is
     a wise preventive measure to globally remove all blank spaces from <blank-
     space><end-of-line> character sequences.  Should the need arise to force a
     blank character at the end of a line, it may be forced with an unpaddable
     space and the `\&' escape character.  For example, `string\ \&'.

Escaping Special Characters

     Special characters like the newline character `\n', are handled by replacing
     the `\' with `\e' (e.g., `\en') to preserve the backslash.

THE ANATOMY OF A MAN PAGE top

     The body of a man page is easily constructed from a basic template found in
     the file /usr/share/misc/mdoc.template.  Several example man pages can also
     be found in /usr/share/examples/mdoc.

A manual page template

           .\" The following requests are required for all man pages.
           .Dd Month day, year
           .Os OPERATING_SYSTEM [version/release]
           .Dt DOCUMENT_TITLE [section number] [volume]
           .Sh NAME
           .Nm name
           .Nd one line description of name
           .Sh SYNOPSIS
           .Sh DESCRIPTION
           .\" The following requests should be uncommented and
           .\" used where appropriate.  This next request is
           .\" for sections 2 and 3 function return values only.
           .\" .Sh RETURN VALUE
           .\" This next request is for sections 1, 6, 7 & 8 only
           .\" .Sh ENVIRONMENT
           .\" .Sh FILES
           .\" .Sh EXAMPLES
           .\" This next request is for sections 1, 6, 7 & 8 only
           .\"     (command return values (to shell) and
           .\"       fprintf/stderr type diagnostics)
           .\" .Sh DIAGNOSTICS
           .\" The next request is for sections 2 and 3 error
           .\" and signal handling only.
           .\" .Sh ERRORS
           .\" .Sh SEE ALSO
           .\" .Sh CONFORMING TO
           .\" .Sh HISTORY
           .\" .Sh AUTHORS
           .\" .Sh BUGS

     The first items in the template are the macros (.Dd, .Os, .Dt); the document
     date, the operating system the man page or subject source is developed or
     modified for, and the man page title (in upper case) along with the section
     of the manual the page belongs in.  These macros identify the page, and are
     discussed below in TITLE MACROS.

     The remaining items in the template are section headers (.Sh); of which NAME,
     SYNOPSIS and DESCRIPTION are mandatory.  The headers are discussed in PAGE
     STRUCTURE DOMAIN, after presentation of MANUAL DOMAIN.  Several content
     macros are used to demonstrate page layout macros; reading about content
     macros before page layout macros is recommended.

TITLE MACROS top

     The title macros are the first portion of the page structure domain, but are
     presented first and separate for someone who wishes to start writing a man
     page yesterday.  Three header macros designate the document title or manual
     page title, the operating system, and the date of authorship.  These macros
     are one called once at the very beginning of the document and are used to
     construct the headers and footers only.

     .Dt DOCUMENT_TITLE section# [volume]
             The document title is the subject of the man page and must be in
             CAPITALS due to troff limitations.  The section number may be
             1, ..., 8, and if it is specified, the volume title may be omitted.
             A volume title may be arbitrary or one of the following:

                   AMD    UNIX Ancestral Manual Documents
                   SMM    UNIX System Manager's Manual
                   URM    UNIX Reference Manual
                   PRM    UNIX Programmer's Manual

             The default volume labeling is URM for sections 1, 6, and 7; SMM for
             section 8; PRM for sections 2, 3, 4, and 5.

     .Os operating_system release#
             The name of the operating system should be the common acronym, for
             example, BSD or FreeBSD or ATT.  The release should be the standard
             release nomenclature for the system specified, for example, 4.3,
             4.3+Tahoe, V.3, V.4.  Unrecognized arguments are displayed as given
             in the page footer.  For instance, a typical footer might be:

                   .Os 4.3BSD

             or
                   .Os FreeBSD 2.2

             or for a locally produced set

                   .Os CS Department

             The Berkeley default, `.Os' without an argument, has been defined as
             BSD in the site-specific file /usr/share/tmac/mdoc/doc-common.  It
             really should default to LOCAL.  Note, if the `.Os' macro is not
             present, the bottom left corner of the page will be ugly.

     .Dd month day, year
             The date should be written formally:

                   January 25, 1989

INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS top

What's in a name...

     The manual domain macro names are derived from the day to day informal lan-
     guage used to describe commands, subroutines and related files.  Slightly
     different variations of this language are used to describe the three differ-
     ent aspects of writing a man page.  First, there is the description of -mdoc
     macro request usage.  Second is the description of a UNIX command with -mdoc
     macros and third, the description of a command to a user in the verbal sense;
     that is, discussion of a command in the text of a man page.

     In the first case, troff(1) macros are themselves a type of command; the gen-
     eral syntax for a troff command is:

           .Va argument1 argument2 ... argument9

     The `.Va' is a macro command or request, and anything following it is an
     argument to be processed.  In the second case, the description of a UNIX com-
     mand using the content macros is a bit more involved; a typical SYNOPSIS com-
     mand line might be displayed as:

           filter [-flag] infile outfile

     Here, filter is the command name and the bracketed string -flag is a flag
     argument designated as optional by the option brackets.  In -mdoc terms,
     infile and outfile are called arguments.  The macros which formatted the
     above example:

           .Nm filter
           .Op Fl flag
           .Ar infile outfile

     In the third case, discussion of commands and command syntax includes both
     examples above, but may add more detail.  The arguments infile and outfile
     from the example above might be referred to as operands or file arguments.
     Some command-line argument lists are quite long:

           make  [-eiknqrstv] [-D variable] [-d flags] [-f makefile]
                 [-I directory] [-j max_jobs] [variable=value] [target ...]

     Here one might talk about the command make and qualify the argument makefile,
     as an argument to the flag, -f, or discuss the optional file operand target.
     In the verbal context, such detail can prevent confusion, however the -mdoc
     package does not have a macro for an argument to a flag.  Instead the `Ar'
     argument macro is used for an operand or file argument like target as well as
     an argument to a flag like variable.  The make command line was produced
     from:

           .Nm make
           .Op Fl eiknqrstv
           .Op Fl D Ar variable
           .Op Fl d Ar flags
           .Op Fl f Ar makefile
           .Op Fl I Ar directory
           .Op Fl j Ar max_jobs
           .Op Ar variable=value
           .Bk -words
           .Op Ar target ...
           .Ek

     The `.Bk' and `.Ek' macros are explained in Keeps.

General Syntax

     The manual domain and general text domain macros share a similar syntax with
     a few minor deviations: `.Ar', `.Fl', `.Nm', and `.Pa' differ only when
     called without arguments; `.Fn' and `.Xr' impose an order on their argument
     lists and the `.Op' and `.Fn' macros have nesting limitations.  All content
     macros are capable of recognizing and properly handling punctuation, provided
     each punctuation character is separated by a leading space.  If a request is
     given:

           .Li sptr, ptr),

     The result is:

           sptr, ptr),

     The punctuation is not recognized and all is output in the literal font. If
     the punctuation is separated by a leading white space:

           .Li sptr , ptr ) ,

     The result is:

           sptr, ptr),

     The punctuation is now recognized and is output in the default font distin-
     guishing it from the strings in literal font.

     To remove the special meaning from a punctuation character escape it with
     `\&'.  Troff is limited as a macro language, and has difficulty when pre-
     sented with a string containing a member of the mathematical, logical or quo-
     tation set:

                 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

     The problem is that troff may assume it is supposed to actually perform the
     operation or evaluation suggested by the characters.  To prevent the acciden-
     tal evaluation of these characters, escape them with `\&'.  Typical syntax is
     shown in the first content macro displayed below, `.Ad'.

MANUAL DOMAIN          top
Address Macro

     The address macro identifies an address construct of the form
     addr1[,addr2[,addr3]].

           Usage: .Ad address ... [.,:;()[]?!]
                   .Ad addr1           addr1
                   .Ad addr1 .         addr1.
                   .Ad addr1 , file2   addr1, file2
                   .Ad f1 , f2 , f3 :  f1, f2, f3:
                   .Ad addr ) ) ,      addr)),

     It is an error to call `.Ad' without arguments.  `.Ad' is callable by other
     macros and is parsed.

Author Name

     The `.An' macro is used to specify the name of the author of the item being
     documented, or the name of the author of the actual manual page.  Any remain-
     ing arguments after the name information are assumed to be punctuation.

           Usage: .An author_name [.,:;()[]?!]
                   .An Joe Author        Joe Author
                   .An Joe Author ,      Joe Author,
                   .An Joe Author Aq nobody@FreeBSD.ORG
                                         Joe Author <nobody@FreeBSD.ORG>
                   .An Joe Author ) ) ,  Joe Author)),

     The `.An' macro is parsed and is callable.  It is an error to call `.An'
     without any arguments.

Argument Macro

     The `.Ar' argument macro may be used whenever a command-line argument is ref-
     erenced.

           Usage: .Ar argument ... [.,:;()[]?!]
                    .Ar              file ...
                    .Ar file1        file1
                    .Ar file1 .      file1.
                    .Ar file1 file2  file1 file2
                    .Ar f1 f2 f3 :   f1 f2 f3:
                    .Ar file ) ) ,   file)),

     If `.Ar' is called without arguments `Ar' is assumed.  The `.Ar' macro is
     parsed and is callable.

Configuration Declaration (section four only)

     The `.Cd' macro is used to demonstrate a config(8) declaration for a device
     interface in a section four manual.  This macro accepts quoted arguments
     (double quotes only).

           device le0 at scode?  produced by: `.Cd device le0 at scode?'.

Command Modifier

     The command modifier is identical to the `.Fl' (flag) command with the excep-
     tion the `.Cm' macro does not assert a dash in front of every argument.  Tra-
     ditionally flags are marked by the preceding dash, some commands or subsets
     of commands do not use them.  Command modifiers may also be specified in con-
     junction with interactive commands such as editor commands.  See Flags.

Defined Variables

     A variable which is defined in an include file is specified by the macro
     `.Dv'.

           Usage: .Dv defined_variable ... [.,:;()[]?!]
                   .Dv MAXHOSTNAMELEN  MAXHOSTNAMELEN
                   .Dv TIOCGPGRP )     TIOCGPGRP)

     It is an error to call `.Dv' without arguments.  `.Dv' is parsed and is
     callable.

Errno's (Section two only)

     The `.Er' errno macro specifies the error return value for section two
     library routines.  The second example below shows `.Er' used with the `.Bq'
     general text domain macro, as it would be used in a section two manual page.

           Usage: .Er ERRNOTYPE ... [.,:;()[]?!]
                   .Er ENOENT      ENOENT
                   .Er ENOENT ) ;  ENOENT);
                   .Bq Er ENOTDIR  [ENOTDIR]

     It is an error to call `.Er' without arguments.  The `.Er' macro is parsed
     and is callable.

Environment Variables

     The `.Ev' macro specifies an environment variable.

           Usage: .Ev argument ... [.,:;()[]?!]
                   .Ev DISPLAY        DISPLAY
                   .Ev PATH .         PATH.
                   .Ev PRINTER ) ) ,  PRINTER)),

     It is an error to call `.Ev' without arguments.  The `.Ev' macro is parsed
     and is callable.

Function Argument

     The `.Fa' macro is used to refer to function arguments (parameters) outside
     of the SYNOPSIS section of the manual or inside the SYNOPSIS section should a
     parameter list be too long for the `.Fn' macro and the enclosure macros `.Fo'
     and `.Fc' must be used.  `.Fa' may also be used to refer to structure mem-
     bers.

           Usage: .Fa function_argument ... [.,:;()[]?!]
                   .Fa d_namlen ) ) ,  d_namlen)),
                   .Fa iov_len         iov_len

     It is an error to call `.Fa' without arguments.  `.Fa' is parsed and is
     callable.

Function Declaration

     The `.Fd' macro is used in the SYNOPSIS section with section two or three
     functions.  The `.Fd' macro does not call other macros and is not callable by
     other macros.

           Usage: .Fd include_file (or defined variable)

     In the SYNOPSIS section a `.Fd' request causes a line break if a function has
     already been presented and a break has not occurred.  This leaves a nice ver-
     tical space in between the previous function call and the declaration for the
     next function.

Flags

     The `.Fl' macro handles command-line flags.  It prepends a dash, `-', to the
     flag.  For interactive command flags, which are not prepended with a dash,
     the `.Cm' (command modifier) macro is identical, but without the dash.

           Usage: .Fl argument ... [.,:;()[]?!]
                   .Fl           -
                   .Fl cfv       -cfv
                   .Fl cfv .     -cfv.
                   .Fl s v t     -s -v -t
                   .Fl - ,       --,
                   .Fl xyz ) ,   -xyz),

     The `.Fl' macro without any arguments results in a dash representing
     stdin/stdout.  Note that giving `.Fl' a single dash, will result in two
     dashes.  The `.Fl' macro is parsed and is callable.

Functions (library routines)

     The .Fn macro is modeled on ANSI C conventions.

     Usage: .Fn [type] function [[type] parameters ... [ .,:;()[]?! ]]
     .Fn getchar                             getchar()
     .Fn strlen ) ,                          strlen()),
     .Fn "int align" "const * char *sptrs",  int align(const * char *sptrs),

     It is an error to call `.Fn' without any arguments.  The `.Fn' macro is
     parsed and is callable, note that any call to another macro signals the end
     of the `.Fn' call (it will close-parenthesis at that point).

     For functions that have more than eight parameters (and this is rare), the
     macros `.Fo' (function open) and `.Fc' (function close) may be used with
     `.Fa' (function argument) to get around the limitation.  For example:

           .Fo "int res_mkquery"
           .Fa "int op"
           .Fa "char *dname"
           .Fa "int class"
           .Fa "int type"
           .Fa "char *data"
           .Fa "int datalen"
           .Fa "struct rrec *newrr"
           .Fa "char *buf"
           .Fa "int buflen"
           .Fc

     Produces:

           int  res_mkquery(int op,  char *dname, int class, int type, char *data,
           int datalen, struct rrec *newrr, char *buf, int buflen)

     The `.Fo' and `.Fc' macros are parsed and are callable.  In the SYNOPSIS sec-
     tion, the function will always begin at the beginning of line.  If there is
     more than one function presented in the SYNOPSIS section and a function type
     has not been given, a line break will occur, leaving a nice vertical space
     between the current function name and the one prior.  At the moment, `.Fn'
     does not check its word boundaries against troff line lengths and may split
     across a newline ungracefully.  This will be fixed in the near future.

Function Type

     This macro is intended for the SYNOPSIS section.  It may be used anywhere
     else in the man page without problems, but its main purpose is to present the
     function type in kernel normal form for the SYNOPSIS of sections two and
     three (it causes a line break allowing the function name to appear on the
     next line).

           Usage: .Ft type ... [.,:;()[]?!]
                   .Ft struct stat  struct stat

     The `.Ft' request is not callable by other macros.

Interactive Commands

     The `.Ic' macro designates an interactive or internal command.

           Usage: .Ic argument ... [.,:;()[]?!]
                   .Ic :wq                  :wq
                   .Ic do while {...}       do while {...}
                   .Ic setenv , unsetenv    setenv, unsetenv

     It is an error to call `.Ic' without arguments.  The `.Ic' macro is parsed
     and is callable.

Name Macro

     The `.Nm' macro is used for the document title or subject name.  It has the
     peculiarity of remembering the first argument it was called with, which
     should always be the subject name of the page.  When called without argu-
     ments, `.Nm' regurgitates this initial name for the sole purpose of making
     less work for the author.  Note: a section two or three document function
     name is addressed with the `.Nm' in the NAME section, and with `.Fn' in the
     SYNOPSIS and remaining sections.  For interactive commands, such as the
     `while' command keyword in csh(1), the `.Ic' macro should be used.  While the
     `.Ic' is nearly identical to `.Nm', it can not recall the first argument it
     was invoked with.

           Usage: .Nm argument ... [.,:;()[]?!]
                   .Nm mdoc.sample  mdoc.sample
                   .Nm \-mdoc       -mdoc.
                   .Nm foo ) ) ,    foo)),
                   .Nm              mdoc.samples

     The `.Nm' macro is parsed and is callable.

Options

     The `.Op' macro places option brackets around the any remaining arguments on
     the command line, and places any trailing punctuation outside the brackets.
     The macros `.Oc' and `.Oo' may be used across one or more lines.

           Usage: .Op options ... [.,:;()[]?!]
           .Op                                []
           .Op Fl k                           [-k]
           .Op Fl k ) .                       [-k]).
           .Op Fl k Ar kookfile               [-k kookfile]
           .Op Fl k Ar kookfile ,             [-k kookfile],
           .Op Ar objfil Op Ar corfil         [objfil [corfil]]
           .Op Fl c Ar objfil Op Ar corfil ,  [-c objfil [corfil]],
           .Op word1 word2                    [word1 word2]

     The `.Oc' and `.Oo' macros:

           .Oo
           .Op Fl k Ar kilobytes
           .Op Fl i Ar interval
           .Op Fl c Ar count
           .Oc

     Produce: [[-k kilobytes] [-i interval] [-c count]]

     The macros `.Op', `.Oc' and `.Oo' are parsed and are callable.

Pathnames

     The `.Pa' macro formats pathnames or filenames.

           Usage: .Pa pathname [.,:;()[]?!]
                   .Pa /usr/share         /usr/share
                   .Pa /tmp/fooXXXXX ) .  /tmp/fooXXXXX).

     The `.Pa' macro is parsed and is callable.

Variables

     Generic variable reference:

           Usage: .Va variable ... [.,:;()[]?!]
                   .Va count           count
                   .Va settimer,       settimer,
                   .Va int *prt ) :    int *prt):
                   .Va char s ] ) ) ,  char s])),

     It is an error to call `.Va' without any arguments.  The `.Va' macro is
     parsed and is callable.

Manual Page Cross References

     The `.Xr' macro expects the first argument to be a manual page name, and the
     second argument, if it exists, to be either a section page number or punctua-
     tion.  Any remaining arguments are assumed to be punctuation.

           Usage: .Xr man_page [1,...,8] [.,:;()[]?!]
                   .Xr mdoc          mdoc
                   .Xr mdoc ,        mdoc,
                   .Xr mdoc 7        mdoc(7)
                   .Xr mdoc 7 ) ) ,  mdoc(7))),

     The `.Xr' macro is parsed and is callable.  It is an error to call `.Xr'
     without any arguments.

GENERAL TEXT DOMAIN          top
AT&T Macro

           Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... [ .,:;()[]?! ]
                   .At         AT&T UNIX
                   .At v6 .    Version 6 AT&T UNIX.

     The `.At' macro is not parsed and not callable It accepts at most two argu-
     ments.

BSD Macro

           Usage: .Bx [Version/release] ... [.,:;()[]?!]
                   .Bx          BSD
                   .Bx 4.3 .    4.3BSD.

     The `.Bx' macro is parsed and is callable.

FreeBSD Macro

           Usage: .Fx Version.release ... [ .,:;()[]?! ]
                   .Fx 2.2 .    FreeBSD 2.2.

     The `.Fx' macro is not parsed and not callable It accepts at most two argu-
     ments.

UNIX Macro

           Usage: .Ux ... [.,:;()[]?!]
                   .Ux          UNIX

     The `.Ux' macro is parsed and is callable.

Enclosure and Quoting Macros

     The concept of enclosure is similar to quoting.  The object being to enclose
     one or more strings between a pair of characters like quotes or parentheses.
     The terms quoting and enclosure are used interchangeably throughout this doc-
     ument.  Most of the one line enclosure macros end in small letter `q' to give
     a hint of quoting, but there are a few irregularities.  For each enclosure
     macro there is also a pair of open and close macros which end in small let-
     ters `o' and `c' respectively.  These can be used across one or more lines of
     text and while they have nesting limitations, the one line quote macros can
     be used inside of them.

            Quote    Close    Open   Function                  Result
           .Aq      .Ac      .Ao     Angle Bracket Enclosure   <string>
           .Bq      .Bc      .Bo     Bracket Enclosure         [string]
           .Dq      .Dc      .Do     Double Quote              ``string''
                    .Ec      .Eo     Enclose String (in XX)    XXstringXX
           .Pq      .Pc      .Po     Parenthesis Enclosure     (string)
           .Ql                       Quoted Literal            `st' or string
           .Qq      .Qc      .Qo     Straight Double Quote     "string"
           .Sq      .Sc      .So     Single Quote              `string'

     Except for the irregular macros noted below, all of the quoting macros are
     parsed and callable.  All handle punctuation properly, as long as it is pre-
     sented one character at a time and separated by spaces.  The quoting macros
     examine opening and closing punctuation to determine whether it comes before
     or after the enclosing string This makes some nesting possible.

     .Ec, .Eo  These macros expect the first argument to be the opening and clos-
               ing strings respectively.

     .Ql       The quoted literal macro behaves differently for troff than nroff.
               If formatted with nroff, a quoted literal is always quoted.  If
               formatted with troff, an item is only quoted if the width of the
               item is less than three constant width characters.  This is to make
               short strings more visible where the font change to literal (con-
               stant width) is less noticeable.

     .Pf       The prefix macro is not callable, but it is parsed:

                     .Pf ( Fa name2
                              becomes (name2.

               The `.Ns' (no space) macro performs the analogous suffix function.

     Examples of quoting:
           .Aq                         <>
           .Aq Ar ctype.h ) ,          <ctype.h>),
           .Bq                         []
           .Bq Em Greek , French .     [Greek, French].
           .Dq                         ``''
           .Dq string abc .            ``string abc''.
           .Dq '^[A-Z]'                ``'^[A-Z]'''
           .Ql man mdoc                `man mdoc'
           .Qq                         ""
           .Qq string ) ,              "string"),
           .Qq string Ns ),            "string),"
           .Sq                         `'
           .Sq string                  `string'

     For a good example of nested enclosure macros, see the `.Op' option macro.
     It was created from the same underlying enclosure macros as those presented
     in the list above.  The `.Xo' and `.Xc' extended argument list macros were
     also built from the same underlying routines and are a good example of -mdoc
     macro usage at its worst.

No-Op or Normal Text Macro

     The macro `.No' is a hack for words in a macro command line which should not
     be formatted and follows the conventional syntax for content macros.

   Space Macro
     The `.Ns' macro eliminates unwanted spaces in between macro requests.  It is
     useful for old style argument lists where there is no space between the flag
     and argument:

           .Op Fl I Ns Ar directory    produces [-Idirectory]

     Note: the `.Ns' macro always invokes the `.No' macro after eliminating the
     space unless another macro name follows it.  The macro `.Ns' is parsed and is
     callable.

Section Cross References

     The `.Sx' macro designates a reference to a section header within the same
     document.  It is parsed and is callable.

                   .Sx FILES     FILES

References and Citations

     The following macros make a modest attempt to handle references.  At best,
     the macros make it convenient to manually drop in a subset of refer style
     references.

           .Rs     Reference Start.  Causes a line break and begins collection of
                   reference information until the reference end macro is read.
           .Re     Reference End.  The reference is printed.
           .%A     Reference author name, one name per invocation.
           .%B     Book title.
           .%C     City/place.
           .%D     Date.
           .%J     Journal name.
           .%N     Issue number.
           .%O     Optional information.
           .%P     Page number.
           .%R     Report name.
           .%T     Title of article.
           .%V     Volume(s).

     The macros beginning with `%' are not callable, and are parsed only for the
     trade name macro which returns to its caller.  (And not very predictably at
     the moment either.)  The purpose is to allow trade names to be pretty printed
     in troff/ditroff output.

Return Values

     The `.Rv' macro generates text for use in the RETURN VALUE section.

           Usage: .Rv [-std function]

     `.Rv -std atexit' will generate the following text:

     The atexit() function returns the value 0 if successful; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.

     The -std option is valid only for manual page sections 2 and 3.

Trade Names (or Acronyms and Type Names)

     The trade name macro is generally a small caps macro for all upper case words
     longer than two characters.

           Usage: .Tn symbol ... [.,:;()[]?!]
                   .Tn DEC    DEC
                   .Tn ASCII  ASCII

     The `.Tn' macro is parsed and is callable by other macros.

Extended Arguments

     The `.Xo' and `.Xc' macros allow one to extend an argument list on a macro
     boundary.  Argument lists cannot be extended within a macro which expects all
     of its arguments on one line such as `.Op'.

     Here is an example of `.Xo' using the space mode macro to turn spacing off:

           .Sm off
           .It Xo Sy I Ar operation
           .No \en Ar count No \en
           .Xc
           .Sm on

     Produces

           Ioperation\ncount\n

     Another one:

           .Sm off
           .It Cm S No / Ar old_pattern Xo
           .No / Ar new_pattern
           .No / Op Cm g
           .Xc
           .Sm on

     Produces

           S/old_pattern/new_pattern/[g]

     Another example of `.Xo' and using enclosure macros: Test the value of a
     variable.

           .It Xo
           .Ic .ifndef
           .Oo \&! Oc Ns Ar variable
           .Op Ar operator variable ...
           .Xc

     Produces

           .ifndef [!]variable [operator variable ...]

     All of the above examples have used the `.Xo' macro on the argument list of
     the `.It' (list-item) macro.  The extend macros are not used very often, and
     when they are it is usually to extend the list-item argument list.  Unfortu-
     nately, this is also where the extend macros are the most finicky.  In the
     first two examples, spacing was turned off; in the third, spacing was desired
     in part of the output but not all of it.  To make these macros work in this
     situation make sure the `.Xo' and `.Xc' macros are placed as shown in the
     third example.  If the `.Xo' macro is not alone on the `.It' argument list,
     spacing will be unpredictable.  The `.Ns' (no space macro) must not occur as
     the first or last macro on a line in this situation.  Out of 900 manual pages
     (about 1500 actual pages) currently released with BSD only fifteen use the
     `.Xo' macro.

PAGE STRUCTURE DOMAIN          top
Section Headers

     The first three `.Sh' section header macros list below are required in every
     man page.  The remaining section headers are recommended at the discretion of
     the author writing the manual page.  The `.Sh' macro can take up to nine
     arguments.  It is parsed and but is not callable.

     .Sh NAME      The `.Sh NAME' macro is mandatory.  If not specified, the head-
                   ers, footers and page layout defaults will not be set and
                   things will be rather unpleasant.  The NAME section consists of
                   at least three items.  The first is the `.Nm' name macro naming
                   the subject of the man page.  The second is the Name Descrip-
                   tion macro, `.Nd', which separates the subject name from the
                   third item, which is the description.  The description should
                   be the most terse and lucid possible, as the space available is
                   small.

     .Sh SYNOPSIS  The SYNOPSIS section describes the typical usage of the subject
                   of a man page.  The macros required are either `.Nm', `.Cd',
                   `.Fn', (and possibly `.Fo', `.Fc', `.Fd', `.Ft' macros).  The
                   function name macro `.Fn' is required for manual page sections
                   2 and 3, the command and general name macro `.Nm' is required
                   for sections 1, 5, 6, 7, 8.  Section 4 manuals require a `.Nm',
                   `.Fd' or a `.Cd' configuration device usage macro.  Several
                   other macros may be necessary to produce the synopsis line as
                   shown below:

           cat [-benstuv] [-] file ...

     The following macros were used:

           .Nm cat
           .Op Fl benstuv
           .Op Fl
           .Ar

     Note: The macros `.Op', `.Fl', and `.Ar' recognize the pipe bar character
     `|', so a command line such as:

           .Op Fl a | Fl b

     will not go orbital.  Troff normally interprets a | as a special operator.
     See PREDEFINED STRINGS for a usable | character in other situations.

     .Sh DESCRIPTION
                   In most cases the first text in the DESCRIPTION section is a
                   brief paragraph on the command, function or file, followed by a
                   lexical list of options and respective explanations.  To create
                   such a list, the `.Bl' begin-list, `.It' list-item and `.El'
                   end-list macros are used (see Lists and Columns below).

     The following `.Sh' section headers are part of the preferred manual page
     layout and must be used appropriately to maintain consistency.  They are
     listed in the order in which they would be used.

     .Sh ENVIRONMENT
               The ENVIRONMENT section should reveal any related environment vari-
               ables and clues to their behavior and/or usage.

     .Sh EXAMPLES
               There are several ways to create examples.  See the EXAMPLES sec-
               tion below for details.

     .Sh FILES
               Files which are used or created by the man page subject should be
               listed via the `.Pa' macro in the FILES section.

     .Sh SEE ALSO
               References to other material on the man page topic and cross refer-
               ences to other relevant man pages should be placed in the SEE ALSO
               section.  Cross references are specified using the `.Xr' macro.
               Cross references in the SEE ALSO section should be sorted by sec-
               tion number, and then placed in alphabetical order and comma sepa-
               rated.  For example:

               ls(1), ps(1), group(5), passwd(5).

               At this time refer(1) style references are not accommodated.

     .Sh CONFORMING TO
               If the command, library function or file adheres to a specific
               implementation such as IEEE Std 1003.2 (``POSIX.2'') or ANSI
               X3.159-1989 (``ANSI C89'') this should be noted here.  If the com-
               mand does not adhere to any standard, its history should be noted
               in the HISTORY section.

     .Sh HISTORY
               Any command which does not adhere to any specific standards should
               be outlined historically in this section.

     .Sh AUTHORS
               Credits, if need be, should be placed here.

     .Sh DIAGNOSTICS
               Diagnostics from a command should be placed in this section.

     .Sh ERRORS
               Specific error handling, especially from library functions (man
               page sections 2 and 3) should go here.  The `.Er' macro is used to
               specify an errno.

     .Sh BUGS  Blatant problems with the topic go here...

     User specified `.Sh' sections may be added, for example, this section was set
     with:

                   .Sh PAGE STRUCTURE DOMAIN

Paragraphs and Line Spacing.

     .Pp     The `.Pp' paragraph command may be used to specify a line space where
             necessary.  The macro is not necessary after a `.Sh' or `.Ss' macro
             or before a `.Bl' macro.  (The `.Bl' macro asserts a vertical dis-
             tance unless the -compact flag is given).

Keeps

     The only keep that is implemented at this time is for words.  The macros are
     `.Bk' (begin-keep) and `.Ek' (end-keep).  The only option that `.Bk' accepts
     is -words and is useful for preventing line breaks in the middle of options.
     In the example for the make command-line arguments (see What's in a name),
     the keep prevented nroff from placing up the flag and the argument on sepa-
     rate lines.  (Actually, the option macro used to prevent this from occurring,
     but was dropped when the decision (religious) was made to force right justi-
     fied margins in troff as options in general look atrocious when spread across
     a sparse line.  More work needs to be done with the keep macros, a -line
     option needs to be added.)

Examples and Displays

     There are five types of displays, a quickie one line indented display `.D1',
     a quickie one line literal display `.Dl', and a block literal, block filled
     and block ragged which use the `.Bd' begin-display and `.Ed' end-display
     macros.

     .D1    (D-one) Display one line of indented text.  This macro is parsed, but
            it is not callable.

                  -ldghfstru

            The above was produced by: .Dl -ldghfstru.

     .Dl    (D-ell) Display one line of indented literal text.  The `.Dl' example
            macro has been used throughout this file.  It allows the indent (dis-
            play) of one line of text.  Its default font is set to constant width
            (literal) however it is parsed and will recognized other macros.  It
            is not callable however.

                  % ls -ldg /usr/local/bin

            The above was produced by .Dl % ls -ldg /usr/local/bin.

     .Bd    Begin-display.  The `.Bd' display must be ended with the `.Ed' macro.
            Displays may be nested within displays and lists.  `.Bd' has the fol-
            lowing syntax:

                  .Bd display-type [-offset offset_value] [-compact]

            The display-type must be one of the following four types and may have
            an offset specifier for indentation: `.Bd'.

     -ragged           Display a block of text as typed, right (and left) margin
                       edges are left ragged.
     -filled           Display a filled (formatted) block.  The block of text is
                       formatted (the edges are filled - not left unjustified).
     -literal          Display a literal block, useful for source code or simple
                       tabbed or spaced text.
     -file file_name   The filename following the -file flag is read and dis-
                       played.  Literal mode is asserted and tabs are set at 8
                       constant width character intervals, however any troff/-mdoc
                       commands in file will be processed.
     -offset string    If -offset is specified with one of the following strings,
                       the string is interpreted to indicate the level of indenta-
                       tion for the forthcoming block of text:

                       left        Align block on the current left margin, this is
                                   the default mode of `.Bd'.
                       center      Supposedly center the block.  At this time
                                   unfortunately, the block merely gets left
                                   aligned about an imaginary center margin.
                       indent      Indents by one default indent value or tab.
                                   The default indent value is also used for the
                                   `.D1' display so one is guaranteed the two
                                   types of displays will line up.  This indent is
                                   normally set to 6n or about two thirds of an
                                   inch (six constant width characters).
                       indent-two  Indents two times the default indent value.
                       right       This left aligns the block about two inches
                                   from the right side of the page.  This macro
                                   needs work and perhaps may never do the right
                                   thing by troff.
     .Ed               End-display.

Font Modes

     There are five macros for changing the appearance of the manual page text:

     .Em    Text may be stressed or emphasized with the `.Em' macro.  The usual
            font for emphasis is italic.

                  Usage: .Em argument ... [.,:;()[]?!]
                          .Em does not          does not
                          .Em exceed 1024 .     exceed 1024.
                          .Em vide infra ) ) ,  vide infra)),

            The `.Em' macro is parsed and is callable.  It is an error to call
            `.Em' without arguments.

     .Li    The `.Li' literal macro may be used for special characters, variable
            constants, anything which should be displayed as it would be typed.

                  Usage: .Li argument ... [.,:;()[]?!]
                          .Li \en          \n
                          .Li M1 M2 M3 ;   M1 M2 M3;
                          .Li cntrl-D ) ,  cntrl-D),
                          .Li 1024 ...     1024 ...

            The `.Li' macro is parsed and is callable.

     .Sy    The symbolic emphasis macro is generally a boldface macro in either
            the symbolic sense or the traditional English usage.

                  Usage: .Sy symbol ... [.,:;()[]?!]
                          .Sy Important Notice   Important Notice

                                                 The `.Sy' macro is parsed and is
                                                 callable.  Arguments to `.Sy' may
                                                 be quoted.

     .Bf    Begin font mode.  The `.Bf' font mode must be ended with the `.Ef'
            macro.  Font modes may be nested within other font modes.  `.Bf' has
            the following syntax:

                  .Bf font-mode

            The font-mode must be one of the following three types: `.Bf'.

            Em | -emphasis    Same as if the `.Em' macro was used for the entire
                              block of text.
            Li | -literal     Same as if the `.Li' macro was used for the entire
                              block of text.
            Sy | -symbolic    Same as if the `.Sy' macro was used for the entire
                              block of text.

     .Ef    End font mode.

Tagged Lists and Columns

     There are several types of lists which may be initiated with the `.Bl' begin-
     list macro.  Items within the list are specified with the `.It' item macro
     and each list must end with the `.El' macro.  Lists may be nested within
     themselves and within displays.  Columns may be used inside of lists, but
     lists are unproven inside of columns.

     In addition, several list attributes may be specified such as the width of a
     tag, the list offset, and compactness (blank lines between items allowed or
     disallowed).  Most of this document has been formatted with a tag style list
     (-tag).  For a change of pace, the list-type used to present the list-types
     is an over-hanging list (-ohang).  This type of list is quite popular with
     TeX users, but might look a bit funny after having read many pages of tagged
     lists.  The following list types are accepted by `.Bl':

     -bullet
     -item
     -enum
     These three are the simplest types of lists.  Once the `.Bl' macro has been
     given, items in the list are merely indicated by a line consisting solely of
     the `.It' macro.  For example, the source text for a simple enumerated list
     would look like:

                 .Bl -enum -compact
                 .It
                 Item one goes here.
                 .It
                 And item two here.
                 .It
                 Lastly item three goes here.
                 .El

     The results:

               1.   Item one goes here.
               2.   And item two here.
               3.   Lastly item three goes here.

     A simple bullet list construction:

                 .Bl -bullet -compact
                 .It
                 Bullet one goes here.
                 .It
                 Bullet two here.
                 .El

     Produces:
               +o   Bullet one goes here.
               +o   Bullet two here.

     -tag
     -diag
     -hang
     -ohang
     -inset
     These list-types collect arguments specified with the `.It' macro and create
     a label which may be inset into the forthcoming text, hanged from the forth-
     coming text, overhanged from above and not indented or tagged.  This list was
     constructed with the `Fl ohang' list-type.  The `.It' macro is parsed only
     for the inset, hang and tag list-types and is not callable.  Here is an exam-
     ple of inset labels:

           Tag The tagged list (also called a tagged paragraph) is the most common
           type of list used in the Berkeley manuals.

           Diag Diag lists create section four diagnostic lists and are similar to
           inset lists except callable macros are ignored.

           Hang Hanged labels are a matter of taste.

           Ohang Overhanging labels are nice when space is constrained.

           Inset Inset labels are useful for controlling blocks of paragraphs and
           are valuable for converting -mdoc manuals to other formats.

     Here is the source text which produced the above example:

           .Bl -inset -offset indent
           .It Em Tag
           The tagged list (also called a tagged paragraph) is the
           most common type of list used in the Berkeley manuals.
           .It Em Diag
           Diag lists create section four diagnostic lists
           and are similar to inset lists except callable
           macros are ignored.
           .It Em Hang
           Hanged labels are a matter of taste.
           .It Em Ohang
           Overhanging labels are nice when space is constrained.
           .It Em Inset
           Inset labels are useful for controlling blocks of
           paragraphs and are valuable for converting
           .Nm -mdoc
           manuals to other formats.
           .El

     Here is a hanged list with two items:

           Hanged  labels appear similar to tagged lists when the label is smaller
                   than the label width.

           Longer hanged list labels blend in to the paragraph unlike tagged para-
                   graph labels.

     And the unformatted text which created it:

           .Bl -hang -offset indent
           .It Em Hanged
           labels appear similar to tagged lists when the
           label is smaller than the label width.
           .It Em Longer hanged list labels
           blend in to the paragraph unlike
           tagged paragraph labels.
           .El

     The tagged list which follows uses an optional width specifier to control the
     width of the tag.

           SL      sleep time of the process (seconds blocked)
           PAGEIN  number of disk I/O's resulting from references by the process
                   to pages not loaded in core.
           UID     numerical user-id of process owner
           PPID    numerical ID of parent of process process priority (nonpositive
                   when in noninterruptible wait)

     The raw text:

           .Bl -tag -width "PAGEIN" -compact -offset indent
           .It SL
           sleep time of the process (seconds blocked)
           .It PAGEIN
           number of disk
           .Tn I/O Ns 's
           resulting from references
           by the process to pages not loaded in core.
           .It UID
           numerical user ID of process owner
           .It PPID
           numerical ID of parent of process process priority
           (nonpositive when in noninterruptible wait)
           .El

     Acceptable width specifiers:

           -width Fl     sets the width to the default width for a flag.  All
                         callable macros have a default width value.  The `.Fl',
                         value is presently set to ten constant width characters
                         or about five sixth of an inch.

           -width 24n    sets the width to 24 constant width characters or about
                         two inches.  The `n' is absolutely necessary for the
                         scaling to work correctly.

           -width [22mENAMETOOLONG[0m
                         sets width to the constant width length of the string
                         given.

           -width "int mkfifo"
                         again, the width is set to the constant width of the
                         string given.

     If a width is not specified for the tag list type, the first time `.It' is
     invoked, an attempt is made to determine an appropriate width.  If the first
     argument to `.It' is a callable macro, the default width for that macro will
     be used as if the macro name had been supplied as the width.  However, if
     another item in the list is given with a different callable macro name, a new
     and nested list is assumed.

PREDEFINED STRINGS          top
     The following strings are predefined as may be used by preceding with the
     troff string interpreting sequence `\*(xx' where xx is the name of the
     defined string or as `\*x' where x is the name of the string.  The interpret-
     ing sequence may be used any where in the text.

           String     Nroff     Troff
           <=         <=        <=
           >=         >=        >=
           Rq         ''        ''
           Lq         ``        ``
           ua         ^         ^
           aa         '         '
           ga         `         `
           q          "         "
           Pi         pi        pi
           Ne         !=        !=
           Le         <=        <=
           Ge         >=        >=
           Lt         <         >
           Gt         >         <
           Pm         +-        +-
           If         infinity  infinity
           Na         NaN       NaN
           Ba         |         |

     Note: The string named `q' should be written as `\*q' since it is only one
     char.

DIAGNOSTICS          top
     The debugging facilities for -mdoc are limited, but can help detect subtle
     errors such as the collision of an argument name with an internal register or
     macro name.  (A what?)  A register is an arithmetic storage class for troff
     with a one or two character name.  All registers internal to -mdoc for troff
     and ditroff are two characters and of the form <upper_case><lower_case> such
     as `Ar', <lower_case><upper_case> as `aR' or <upper or lower letter><digit>
     as `C1'.  And adding to the muddle, troff has its own internal registers all
     of which are either two lower case characters or a dot plus a letter or
     metacharacter character.  In one of the introduction examples, it was shown
     how to prevent the interpretation of a macro name with the escape sequence
     `\&'.  This is sufficient for the internal register names also.

     If a nonescaped register name is given in the argument list of a request
     unpredictable behavior will occur.  In general, any time huge portions of
     text do not appear where expected in the output, or small strings such as
     list tags disappear, chances are there is a misunderstanding about an argu-
     ment type in the argument list.  Your mother never intended for you to remem-
     ber this evil stuff - so here is a way to find out whether or not your argu-
     ments are valid: The `.Db' (debug) macro displays the interpretation of the
     argument list for most macros.  Macros such as the `.Pp' (paragraph) macro do
     not contain debugging information.  All of the callable macros do, and it is
     strongly advised whenever in doubt, turn on the `.Db' macro.

           Usage: .Db [on | off]

     An example of a portion of text with the debug macro placed above and below
     an artificially created problem (a flag argument `aC' which should be `\&aC'
     in order to work):

           .Db on
           .Op Fl aC Ar file )
           .Db off

     The resulting output:

           DEBUGGING ON
           DEBUG(argv) MACRO: `.Op'  Line #: 2
                   Argc: 1  Argv: `Fl'  Length: 2
                   Space: `'  Class: Executable
                   Argc: 2  Argv: `aC'  Length: 2
                   Space: `'  Class: Executable
                   Argc: 3  Argv: `Ar'  Length: 2
                   Space: `'  Class: Executable
                   Argc: 4  Argv: `file'  Length: 4
                   Space: ` '  Class: String
                   Argc: 5  Argv: `)'  Length: 1
                   Space: ` '  Class: Closing Punctuation or suffix
                   MACRO REQUEST: .Op Fl aC Ar file )
           DEBUGGING OFF

     The first line of information tells the name of the calling macro, here
     `.Op', and the line number it appears on.  If one or more files are involved
     (especially if text from another file is included) the line number may be
     bogus.  If there is only one file, it should be accurate.  The second line
     gives the argument count, the argument (`Fl') and its length.  If the length
     of an argument is two characters, the argument is tested to see if it is exe-
     cutable (unfortunately, any register which contains a nonzero value appears
     executable).  The third line gives the space allotted for a class, and the
     class type.  The problem here is the argument aC should not be executable.
     The four types of classes are string, executable, closing punctuation and
     opening punctuation.  The last line shows the entire argument list as it was
     read.  In this next example, the offending `aC' is escaped:

           .Db on
           .Em An escaped \&aC
           .Db off

           DEBUGGING ON
           DEBUG(fargv) MACRO: `.Em'  Line #: 2
                   Argc: 1  Argv: `An'  Length: 2
                   Space: ` '  Class: String
                   Argc: 2  Argv: `escaped'  Length: 7
                   Space: ` '  Class: String
                   Argc: 3  Argv: `aC'  Length: 2
                   Space: ` '  Class: String
                   MACRO REQUEST: .Em An escaped &aC
           DEBUGGING OFF

     The argument `\&aC' shows up with the same length of 2 as the `\&' sequence
     produces a zero width, but a register named `\&aC' was not found and the type
     classified as string.

     Other diagnostics consist of usage statements and are self explanatory.

GROFF, TROFF AND NROFF          top
     The -mdoc package does not need compatibility mode with groff.

     The package inhibits page breaks, and the headers and footers which normally
     occur at those breaks with nroff, to make the manual more efficient for view-
     ing on-line.  At the moment, groff with -Tascii does eject the imaginary
     remainder of the page at end of file.  The inhibiting of the page breaks
     makes nroff'd files unsuitable for hardcopy.  There is a register named `cR'
     which can be set to zero in the site dependent style file
     /usr/src/share/tmac/doc-nroff to restore the old style behavior.

FILES          top
     /usr/share/tmac/doc.tmac      manual macro package
     /usr/share/misc/mdoc.template
                                   template for writing a man page
     /usr/share/examples/mdoc/*    several example man pages

BUGS          top
     Undesirable hyphenation on the dash of a flag argument is not yet resolved,
     and causes occasional mishaps in the DESCRIPTION section.  (line break on the
     hyphen).

     Predefined strings are not declared in documentation.

     Section 3f has not been added to the header routines.

     `.Nm' font should be changed in NAME section.

     `.Fn' needs to have a check to prevent splitting up if the line length is too
     short.  Occasionally it separates the last parenthesis, and sometimes looks
     ridiculous if a line is in fill mode.

     The method used to prevent header and footer page breaks (other than the ini-
     tial header and footer) when using nroff occasionally places an unsightly
     partially filled line (blank) at the would be bottom of the page.

     The list and display macros to not do any keeps and certainly should be able
     to.

SEE ALSO          top
     man(1), troff(1), groff_mdoc(7), mdoc(7)

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

BSD                              December 30, 1993                             BSD

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


memccpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMCCPY(3)                   Linux Programmer's Manual                  MEMCCPY(3)

NAME top

       memccpy - copy memory area

SYNOPSIS top

       #include <string.h>

       void *memccpy(void *dest, const void *src, int c, size_t n);

DESCRIPTION top

       The memccpy() function copies no more than n bytes from memory area src to
       memory area dest, stopping when the character c is found.

       If the memory areas overlap, the results are undefined.

RETURN VALUE top

       The memccpy() function returns a pointer to the next character in dest
       after c, or NULL if c was not found in the first n characters of src.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

SEE ALSO top

       bcopy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-01-13                          MEMCCPY(3)


memchr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMCHR(3)                    Linux Programmer's Manual                   MEMCHR(3)

NAME top

       memchr, memrchr, rawmemchr - scan memory for a character

SYNOPSIS top

       #include <string.h>

       void *memchr(const void *s, int c, size_t n);

       void *memrchr(const void *s, int c, size_t n);

       void *rawmemchr(const void *s, int c);

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

       memrchr(), rawmemchr(): _GNU_SOURCE

DESCRIPTION top

       The memchr() function scans the initial n bytes of the memory area pointed
       to by s for the first instance of c.  Both c and the bytes of the memory
       area pointed to by s are interpreted as unsigned char.

       The memrchr() function is like the memchr() function, except that it
       searches backward from the end of the n bytes pointed to by s instead of
       forward from the beginning.

       The rawmemchr() function is similar to memchr(): it assumes (i.e., the
       programmer knows for certain) that an instance of c lies somewhere in the
       memory area starting at the location pointed to by s, and so performs an
       optimized search for c (i.e., no use of a count argument to limit the range
       of the search).  If an instance of c is not found, the results are
       unpredictable.  The following call is a fast means of locating a string's
       terminating null byte:

           char *p = rawmemchr(s, '\0');

RETURN VALUE top

       The memchr() and memrchr() functions return a pointer to the matching byte
       or NULL if the character does not occur in the given memory area.

       The rawmemchr() function returns a pointer to the matching byte, if one is
       found.  If no matching byte is found, the result is unspecified.

VERSIONS top

       rawmemchr() first appeared in glibc in version 2.1.

       memrchr() first appeared in glibc in version 2.2.

CONFORMING TO top

       The memchr() function conforms to SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

       The memrchr() function is a GNU extension, available since glibc 2.1.91.

       The rawmemchr() function is a GNU extension, available since glibc 2.1.

SEE ALSO top

       ffs(3), index(3), rindex(3), strchr(3), strpbrk(3), strrchr(3), strsep(3),
       strspn(3), strstr(3), wmemchr(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-23                           MEMCHR(3)


memcmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMCMP(3)                    Linux Programmer's Manual                   MEMCMP(3)

NAME top

       memcmp - compare memory areas

SYNOPSIS top

       #include <string.h>

       int memcmp(const void *s1, const void *s2, size_t n);

DESCRIPTION top

       The memcmp() function compares the first n bytes (each interpreted as
       unsigned char) of the memory areas s1 and s2.

RETURN VALUE top

       The memcmp() function returns an integer less than, equal to, or greater
       than zero if the first n bytes of s1 is found, respectively, to be less
       than, to match, or be greater than the first n bytes of s2.

       For a nonzero return value, the sign is determined by the sign of the
       difference between the first pair of bytes (interpreted as unsigned char)
       that differ in s1 and s2.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

SEE ALSO top

       bcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncasecmp(3), strncmp(3),
       wmemcmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-11-25                           MEMCMP(3)


memcpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMCPY(3)                    Linux Programmer's Manual                   MEMCPY(3)

NAME top

       memcpy - copy memory area

SYNOPSIS top

       #include <string.h>

       void *memcpy(void *dest, const void *src, size_t n);

DESCRIPTION top

       The memcpy() function copies n bytes from memory area src to memory area
       dest.  The memory areas must not overlap.  Use memmove(3) if the memory
       areas do overlap.

RETURN VALUE top

       The memcpy() function returns a pointer to dest.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

SEE ALSO top

       bcopy(3), memccpy(3), memmove(3), mempcpy(3), strcpy(3), strncpy(3),
       wmemcpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-11-15                           MEMCPY(3)


memfrob(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMFROB(3)                   Linux Programmer's Manual                  MEMFROB(3)

NAME top

       memfrob - frobnicate (encrypt) a memory area

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <string.h>

       void *memfrob(void *s, size_t n);

DESCRIPTION top

       The memfrob() function encrypts the first n bytes of the memory area s by
       exclusive-ORing each character with the number 42.  The effect can be
       reversed by using memfrob() on the encrypted memory area.

       Note that this function is not a proper encryption routine as the XOR
       constant is fixed, and is only suitable for hiding strings.

RETURN VALUE top

       The memfrob() function returns a pointer to the encrypted memory area.

CONFORMING TO top

       The memfrob() function is unique to the GNU C Library.

SEE ALSO top

       strfry(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                          MEMFROB(3)


memmem(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MEMMEM(3)                    Linux Programmer's Manual                   MEMMEM(3)

NAME top

       memmem - locate a substring

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <string.h>

       void *memmem(const void *haystack, size_t haystacklen,
                    const void *needle, size_t needlelen);

DESCRIPTION top

       The memmem() function finds the start of the first occurrence of the
       substring needle of length needlelen in the memory area haystack of length
       haystacklen.

RETURN VALUE top

       The memmem() function returns a pointer to the beginning of the substring,
       or NULL if the substring is not found.

CONFORMING TO top

       This function is a GNU extension.

BUGS top

       This function was broken in Linux libraries up to and including libc 5.0.9;
       there the needle and haystack arguments were interchanged, and a pointer to
       the end of the first occurrence of needle was returned.

       Both old and new libc's have the bug that if needle is empty, haystack-1
       (instead of haystack) is returned.  And glibc 2.0 makes it worse, returning
       a pointer to the last byte of haystack.  This is fixed in glibc 2.1.

SEE ALSO top

       strstr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-12-05                           MEMMEM(3)


memmove(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMMOVE(3)                   Linux Programmer's Manual                  MEMMOVE(3)

NAME top

       memmove - copy memory area

SYNOPSIS top

       #include <string.h>

       void *memmove(void *dest, const void *src, size_t n);

DESCRIPTION top

       The memmove() function copies n bytes from memory area src to memory area
       dest.  The memory areas may overlap: copying takes place as though the
       bytes in src are first copied into a temporary array that does not overlap
       src or dest, and the bytes are then copied from the temporary array to
       dest.

RETURN VALUE top

       The memmove() function returns a pointer to dest.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

SEE ALSO top

       bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3), wmemmove(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-04-10                          MEMMOVE(3)


mempcpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MEMPCPY(3)                   Linux Programmer's Manual                  MEMPCPY(3)

NAME top

       mempcpy, wmempcpy  - copy memory area

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <string.h>

       void *mempcpy(void *dest, const void *src, size_t n);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <wchar.h>

       wchar_t *wmempcpy(wchar_t *dest, const wchar_t *src, size_t n);

DESCRIPTION top

       The mempcpy() function is nearly identical to the memcpy(3) function.  It
       copies n bytes from the object beginning at src into the object pointed to
       by dest.  But instead of returning the value of dest it returns a pointer
       to the byte following the last written byte.

       This function is useful in situations where a number of objects shall be
       copied to consecutive memory positions.

       The wmempcpy() function is identical but takes wchar_t type arguments and
       copies n wide characters.

RETURN VALUE top

       dest + n.

VERSIONS top

       mempcpy() first appeared in glibc in version 2.1.

CONFORMING TO top

       This function is a GNU extension.

EXAMPLE top

       void *
       combine(void *o1, size_t s1, void *o2, size_t s2)
       {
           void *result = malloc(s1 + s2);
           if (result != NULL)
               mempcpy(mempcpy(result, o1, s1), o2, s2);
           return result;
       }

SEE ALSO top

       memccpy(3), memcpy(3), memmove(3), wmemcpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-12                          MEMPCPY(3)


memset(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MEMSET(3)                    Linux Programmer's Manual                   MEMSET(3)

NAME top

       memset - fill memory with a constant byte

SYNOPSIS top

       #include <string.h>

       void *memset(void *s, int c, size_t n);

DESCRIPTION top

       The memset() function fills the first n bytes of the memory area pointed to
       by s with the constant byte c.

RETURN VALUE top

       The memset() function returns a pointer to the memory area s.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

SEE ALSO top

       bzero(3), swab(3), wmemset(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-04-11                           MEMSET(3)


migrate_pages(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MIGRATE_PAGES(2)             Linux Programmer's Manual            MIGRATE_PAGES(2)

NAME top

       migrate_pages - move all pages in a process to another set of nodes

SYNOPSIS top

       #include <numaif.h>

       long migrate_pages(int pid, unsigned long [22mmaxnode,[0m
                          const unsigned long *[22mold_nodes,[0m
                          const unsigned long *[22mnew_nodes);[0m

       Link with -lnuma.

DESCRIPTION top

       migrate_pages() attempts to move all pages of the process pid that are in
       memory nodes old_nodes to the memory nodes in new_nodes.  Pages not located
       in any node in old_nodes will not be migrated.  As far as possible, the
       kernel maintains the relative topology relationship inside old_nodes during
       the migration to new_nodes.

       The old_nodes and new_nodes arguments are pointers to bit masks of node
       numbers, with up to maxnode bits in each mask.  These masks are maintained
       as arrays of unsigned long integers (in the last long integer, the bits
       beyond those specified by maxnode are ignored).  The maxnode argument is
       the maximum node number in the bit mask plus one (this is the same as in
       mbind(2), but different from select(2)).

       The pid argument is the ID of the process whose pages are to be moved.  To
       move pages in another process, the caller must be privileged (CAP_SYS_NICE)
       or the real or effective user ID of the calling process must match the real
       or saved-set user ID of the target process.  If pid is 0, then
       migrate_pages() moves pages of the calling process.

       Pages shared with another process will only be moved if the initiating
       process has the CAP_SYS_NICE privilege.

RETURN VALUE top

       On success migrate_pages() returns the number of pages that could not be
       moved (i.e., a return of zero means that all pages were successfully
       moved).  On error, it returns -1, and sets errno to indicate the error.

ERRORS top

       EPERM  Insufficient privilege (CAP_SYS_NICE) to move pages of the process
              specified by pid, or insufficient privilege (CAP_SYS_NICE) to access
              the specified target nodes.

       ESRCH  No process matching pid could be found.

VERSIONS top

       The migrate_pages() system call first appeared on Linux in version 2.6.16.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       For information on library support, see numa(7).

       Use get_mempolicy(2) with the MPOL_F_MEMS_ALLOWED flag to obtain the set of
       nodes that are allowed by the calling process's cpuset.  Note that this
       information is subject to change at any time by manual or automatic
       reconfiguration of the cpuset.

       Use of migrate_pages() may result in pages whose location (node) violates
       the memory policy established for the specified addresses (see mbind(2))
       and/or the specified process (see set_mempolicy(2)).  That is, memory
       policy does not constrain the destination nodes used by migrate_pages().

       The <numaif.h> header is not included with glibc, but requires installing
       libnuma-devel or a similar package.

SEE ALSO top

       get_mempolicy(2), mbind(2), set_mempolicy(2), numa(3), numa_maps(5),
       cpuset(7), numa(7), migratepages(8), numa_stat(8)

       Documentation/vm/page_migration in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2012-08-01                    MIGRATE_PAGES(2)


mincore(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MINCORE(2)                   Linux Programmer's Manual                  MINCORE(2)

NAME top

       mincore - determine whether pages are resident in memory

SYNOPSIS top

       #include <unistd.h>
       #include <sys/mman.h>

       int mincore(void *addr, size_t length, unsigned char *vec);

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

       mincore(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       mincore() returns a vector that indicates whether pages of the calling
       process's virtual memory are resident in core (RAM), and so will not cause
       a disk access (page fault) if referenced.  The kernel returns residency
       information about the pages starting at the address addr, and continuing
       for length bytes.

       The addr argument must be a multiple of the system page size.  The length
       argument need not be a multiple of the page size, but since residency
       information is returned for whole pages, length is effectively rounded up
       to the next multiple of the page size.  One may obtain the page size
       (PAGE_SIZE) using sysconf(_SC_PAGESIZE).

       The vec argument must point to an array containing at least
       (length+PAGE_SIZE-1) / PAGE_SIZE bytes.  On return, the least significant
       bit of each byte will be set if the corresponding page is currently
       resident in memory, and be clear otherwise.  (The settings of the other
       bits in each byte are undefined; these bits are reserved for possible later
       use.)  Of course the information returned in vec is only a snapshot: pages
       that are not locked in memory can come and go at any moment, and the
       contents of vec may already be stale by the time this call returns.

RETURN VALUE top

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

ERRORS top

       EAGAIN kernel is temporarily out of resources.

       EFAULT vec points to an invalid address.

       EINVAL addr is not a multiple of the page size.

       ENOMEM length is greater than (TASK_SIZE - addr).  (This could occur if a
              negative value is specified for length, since that value will be
              interpreted as a large unsigned integer.)  In Linux 2.6.11 and
              earlier, the error EINVAL was returned for this condition.

       ENOMEM addr to addr + length contained unmapped memory.

VERSIONS top

       Available since Linux 2.3.99pre1 and glibc 2.2.

CONFORMING TO top

       mincore() is not specified in POSIX.1-2001, and it is not available on all
       UNIX implementations.

BUGS top

       Before kernel 2.6.21, mincore() did not return correct information for
       MAP_PRIVATE mappings, or for nonlinear mappings (established using
       remap_file_pages(2)).

SEE ALSO top

       mlock(2), mmap(2)

COLOPHON top

       This page is part of release 3.45 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-22                          MINCORE(2)


mkdir(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MKDIR(2)                     Linux Programmer's Manual                    MKDIR(2)

NAME top

       mkdir - create a directory

SYNOPSIS top

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

       int mkdir(const char *pathname, mode_t mode);

DESCRIPTION top

       mkdir() attempts to create a directory named pathname.

       The argument mode specifies the permissions to use.  It is modified by the
       process's umask in the usual way: the permissions of the created directory
       are (mode & ~umask & 0777).  Other mode bits of the created directory
       depend on the operating system.  For Linux, see below.

       The newly created directory will be owned by the effective user ID of the
       process.  If the directory containing the file has the set-group-ID bit
       set, or if the file system is mounted with BSD group semantics (mount -o
       bsdgroups or, synonymously mount -o grpid), the new directory will inherit
       the group ownership from its parent; otherwise it will be owned by the
       effective group ID of the process.

       If the parent directory has the set-group-ID bit set then so will the newly
       created directory.

RETURN VALUE top

       mkdir() returns zero on success, or -1 if an error occurred (in which case,
       errno is set appropriately).

ERRORS top

       EACCES The parent directory does not allow write permission to the process,
              or one of the directories in pathname did not allow search
              permission.  (See also path_resolution(7).)

       EEXIST pathname already exists (not necessarily as a directory).  This
              includes the case where pathname is a symbolic link, dangling or
              not.

       EFAULT pathname points outside your accessible address space.

       ELOOP  Too many symbolic links were encountered in resolving pathname.

       EMLINK The number of links to the parent directory would exceed LINK_MAX.

       ENAMETOOLONG
              pathname was too long.

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

       ENOMEM Insufficient kernel memory was available.

       ENOSPC The device containing pathname has no room for the new directory.

       ENOSPC The new directory cannot be created because the user's disk quota is
              exhausted.

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

       EPERM  The file system containing pathname does not support the creation of
              directories.

       EROFS  pathname refers to a file on a read-only file system.

CONFORMING TO top

       SVr4, BSD, POSIX.1-2001.

NOTES top

       Under Linux apart from the permission bits, only the S_ISVTX mode bit is
       honored.  That is, under Linux the created directory actually gets mode
       (mode & ~umask & 01777).  See also stat(2).

       There are many infelicities in the protocol underlying NFS.  Some of these
       affect mkdir().

SEE ALSO top

       mkdir(1), chmod(2), chown(2), mkdirat(2), mknod(2), mount(2), rmdir(2),
       stat(2), umask(2), unlink(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-06-26                            MKDIR(2)


mkdirat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MKDIRAT(2)                   Linux Programmer's Manual                  MKDIRAT(2)

NAME top

       mkdirat - create a directory relative to a directory file descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <sys/stat.h>

       int mkdirat(int dirfd, const char *pathname, mode_t mode);

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

       mkdirat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The mkdirat() system call operates in exactly the same way as mkdir(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by mkdir(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like mkdir(2)).

       If pathname is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, mkdirat() returns 0.  On error, -1 is returned and errno is set
       to indicate the error.

ERRORS top

       The same errors that occur for mkdir(2) can also occur for mkdirat().  The
       following additional errors can occur for mkdirat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       mkdirat() was added to Linux in kernel 2.6.16; library support was added to
       glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for mkdirat().

SEE ALSO top

       mkdir(2), openat(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                          MKDIRAT(2)


mkdtemp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MKDTEMP(3)                   Linux Programmer's Manual                  MKDTEMP(3)

NAME top

       mkdtemp - create a unique temporary directory

SYNOPSIS top

       #include <stdlib.h>

       char *mkdtemp(char *template);

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

       mkdtemp():
           _BSD_SOURCE
           || /* Since glibc 2.10: */
               (_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)

DESCRIPTION top

       The mkdtemp() function generates a uniquely named temporary directory from
       template.  The last six characters of template must be XXXXXX and these are
       replaced with a string that makes the directory name unique.  The directory
       is then created with permissions 0700.  Since it will be modified, template
       must not be a string constant, but should be declared as a character array.

RETURN VALUE top

       The mkdtemp() function returns a pointer to the modified template string on
       success, and NULL on failure, in which case errno is set appropriately.

ERRORS top

       EINVAL The last six characters of template were not XXXXXX.  Now template
              is unchanged.

       Also see mkdir(2) for other possible values for errno.

VERSIONS top

       Available since glibc 2.1.91.

CONFORMING TO top

       POSIX.1-2008.  This function is present on the BSDs.

SEE ALSO top

       mkdir(2), mkstemp(3), mktemp(3), tempnam(3), tmpfile(3), tmpnam(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-26                          MKDTEMP(3)


mkfifo(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MKFIFO(3)                    Linux Programmer's Manual                   MKFIFO(3)

NAME top

       mkfifo - make a FIFO special file (a named pipe)

SYNOPSIS top

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

       int mkfifo(const char *pathname, mode_t mode);

DESCRIPTION top

       mkfifo() makes a FIFO special file with name pathname.  mode specifies the
       FIFO's permissions.  It is modified by the process's umask in the usual
       way: the permissions of the created file are (mode & ~umask).

       A FIFO special file is similar to a pipe, except that it is created in a
       different way.  Instead of being an anonymous communications channel, a
       FIFO special file is entered into the file system by calling mkfifo().

       Once you have created a FIFO special file in this way, any process can open
       it for reading or writing, in the same way as an ordinary file.  However,
       it has to be open at both ends simultaneously before you can proceed to do
       any input or output operations on it.  Opening a FIFO for reading normally
       blocks until some other process opens the same FIFO for writing, and vice
       versa.  See fifo(7) for nonblocking handling of FIFO special files.

RETURN VALUE top

       On success mkfifo() returns 0.  In the case of an error, -1 is returned (in
       which case, errno is set appropriately).

ERRORS top

       EACCES One of the directories in pathname did not allow search (execute)
              permission.

       EEXIST pathname already exists.  This includes the case where pathname is a
              symbolic link, dangling or not.

       ENAMETOOLONG
              Either the total length of pathname is greater than PATH_MAX, or an
              individual filename component has a length greater than NAME_MAX.
              In the GNU system, there is no imposed limit on overall filename
              length, but some file systems may place limits on the length of a
              component.

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

       ENOSPC The directory or file system has no room for the new file.

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

       EROFS  pathname refers to a read-only file system.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2),
       mkfifoat(3), fifo(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-06-12                           MKFIFO(3)


mkfifoat(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MKFIFOAT(3)                  Linux Programmer's Manual                 MKFIFOAT(3)

NAME top

       mkfifoat - make a FIFO (named pipe) relative to a directory file descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <sys/stat.h>

       int mkfifoat(int dirfd, const char *pathname, mode_t mode);

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

       mkfifoat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The mkfifoat() system call operates in exactly the same way as mkfifo(3),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by mkfifo(3) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like mkfifo(3)).

       If pathname is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, mkfifoat() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for mkfifo(3) can also occur for mkfifoat().
       The following additional errors can occur for mkfifoat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              pathname is a relative path and dirfd is a file descriptor referring
              to a file other than a directory.

VERSIONS top

       mkfifoat() was added to glibc in version 2.4.  It is implemented using
       mknod(2), available on Linux since kernel 2.6.16.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for mkfifoat().

SEE ALSO top

       openat(2), mkfifo(3), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-12-13                         MKFIFOAT(3)


mknod(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MKNOD(2)                     Linux Programmer's Manual                    MKNOD(2)

NAME top

       mknod - create a special or ordinary file

SYNOPSIS top

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

       int mknod(const char *pathname, mode_t mode, dev_t dev);

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

       mknod():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The system call mknod() creates a file system node (file, device special
       file or named pipe) named pathname, with attributes specified by mode and
       dev.

       The mode argument specifies both the permissions to use and the type of
       node to be created.  It should be a combination (using bitwise OR) of one
       of the file types listed below and the permissions for the new node.

       The permissions are modified by the process's umask in the usual way: the
       permissions of the created node are (mode & ~umask).

       The file type must be one of S_IFREG, S_IFCHR, S_IFBLK, S_IFIFO or S_IFSOCK
       to specify a regular file (which will be created empty), character special
       file, block special file, FIFO (named pipe), or UNIX domain socket,
       respectively.  (Zero file type is equivalent to type S_IFREG.)

       If the file type is S_IFCHR or S_IFBLK then dev specifies the major and
       minor numbers of the newly created device special file (makedev(3) may be
       useful to build the value for dev); otherwise it is ignored.

       If pathname already exists, or is a symbolic link, this call fails with an
       EEXIST error.

       The newly created node will be owned by the effective user ID of the
       process.  If the directory containing the node has the set-group-ID bit
       set, or if the file system is mounted with BSD group semantics, the new
       node will inherit the group ownership from its parent directory; otherwise
       it will be owned by the effective group ID of the process.

RETURN VALUE top

       mknod() returns zero on success, or -1 if an error occurred (in which case,
       errno is set appropriately).

ERRORS top

       EACCES The parent directory does not allow write permission to the process,
              or one of the directories in the path prefix of pathname did not
              allow search permission.  (See also path_resolution(7).)

       EEXIST pathname already exists.  This includes the case where pathname is a
              symbolic link, dangling or not.

       EFAULT pathname points outside your accessible address space.

       EINVAL mode requested creation of something other than a regular file,
              device special file, FIFO or socket.

       ELOOP  Too many symbolic links were encountered in resolving pathname.

       ENAMETOOLONG
              pathname was too long.

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

       ENOMEM Insufficient kernel memory was available.

       ENOSPC The device containing pathname has no room for the new node.

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

       EPERM  mode requested creation of something other than a regular file, FIFO
              (named pipe), or UNIX domain socket, and the caller is not
              privileged (Linux: does not have the CAP_MKNOD capability); also
              returned if the file system containing pathname does not support the
              type of node requested.

       EROFS  pathname refers to a file on a read-only file system.

CONFORMING TO top

       SVr4, 4.4BSD, POSIX.1-2001 (but see below).

NOTES top

       POSIX.1-2001 says: "The only portable use of mknod() is to create a FIFO-
       special file.  If mode is not S_IFIFO or dev is not 0, the behavior of
       mknod() is unspecified."  However, nowadays one should never use mknod()
       for this purpose; one should use mkfifo(3), a function especially defined
       for this purpose.

       Under Linux, this call cannot be used to create directories.  One should
       make directories with mkdir(2).

       There are many infelicities in the protocol underlying NFS.  Some of these
       affect mknod().

SEE ALSO top

       chmod(2), chown(2), fcntl(2), mkdir(2), mknodat(2), mount(2), socket(2),
       stat(2), umask(2), unlink(2), makedev(3), mkfifo(3), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                            MKNOD(2)


mknodat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MKNODAT(2)                   Linux Programmer's Manual                  MKNODAT(2)

NAME top

       mknodat  -  create  a special or ordinary file relative to a directory file
       descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <sys/stat.h>

       int mknodat(int dirfd, const char *pathname, mode_t mode, dev_t dev);

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

       mknodat():
           Since glibc 2.10:
                _XOPEN_SOURCE >= 700
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The mknodat() system call operates in exactly the same way as mknod(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by mknod(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like mknod(2)).

       If pathname is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, mknodat() returns 0.  On error, -1 is returned and errno is set
       to indicate the error.

ERRORS top

       The same errors that occur for mknod(2) can also occur for mknodat().  The
       following additional errors can occur for mknodat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       mknodat() was added to Linux in kernel 2.6.16; library support was added to
       glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for mknodat().

SEE ALSO top

       mknod(2), openat(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                          MKNODAT(2)


mkstemp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MKSTEMP(3)                   Linux Programmer's Manual                  MKSTEMP(3)

NAME top

       mkstemp, mkostemp, mkstemps, mkostemps - create a unique temporary file

SYNOPSIS top

       #include <stdlib.h>

       int mkstemp(char *template);

       int mkostemp(char *template, int flags);

       int mkstemps(char *template, int suffixlen);

       int mkostemps(char *template, int suffixlen, int flags);

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

       mkstemp():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200112L

       mkostemp(): _GNU_SOURCE
       mkstemps(): _BSD_SOURCE || _SVID_SOURCE
       mkostemps(): _GNU_SOURCE

DESCRIPTION top

       The mkstemp() function generates a unique temporary filename from template,
       creates and opens the file, and returns an open file descriptor for the
       file.

       The last six characters of template must be "XXXXXX" and these are replaced
       with a string that makes the filename unique.  Since it will be modified,
       template must not be a string constant, but should be declared as a
       character array.

       The file is created with permissions 0600, that is, read plus write for
       owner only.  The returned file descriptor provides both read and write
       access to the file.  The file is opened with the open(2) O_EXCL flag,
       guaranteeing that the caller is the process that creates the file.

       The mkostemp() function is like mkstemp(), with the difference that flags
       as for open(2) may be specified in flags (e.g., O_APPEND, O_SYNC).

       The mkstemps() function is like mkstemp(), except that the string in
       template contains a suffix of suffixlen characters.  Thus, template is of
       the form prefixXXXXXXsuffix, and the string XXXXXX is modified as for
       mkstemp().

       The mkostemps() function is to mkstemps() as mkostemp() is to mkstemp().

RETURN VALUE top

       On success, these functions return the file descriptor of the temporary
       file.  On error, -1 is returned, and errno is set appropriately.

ERRORS top

       EEXIST Could not create a unique temporary filename.  Now the contents of
              template are undefined.

       EINVAL For mkstemp() and mkostemp(): The last six characters of template
              were not XXXXXX; now template is unchanged.

              For mkstemps() and mkostemps(): template is less than (6 +
              suffixlen) characters long, or the last 6 characters before the
              suffix in template were not XXXXXX.

       These functions may also fail with any of the errors described for open(2).

VERSIONS top

       mkostemp() is available since glibc 2.7.  mkstemps() and mkostemps() are
       available since glibc 2.11.

CONFORMING TO top

       mkstemp(): 4.3BSD, POSIX.1-2001.

       mkstemps(): unstandardized, but appears on several other systems.

       mkostemp() and mkostemps(): are glibc extensions.

NOTES top

       In glibc versions 2.06 and earlier, the file is created with permissions
       0666, that is, read and write for all users.  This old behavior may be a
       security risk, especially since other UNIX flavors use 0600, and somebody
       might overlook this detail when porting programs.  POSIX.1-2008 adds a
       requirement that the file be created with mode 0600.

       More generally, the POSIX specification of mkstemp() does not say anything
       about file modes, so the application should make sure its file mode
       creation mask (see umask(2)) is set appropriately before calling mkstemp()
       (and mkostemp()).

       The prototype for mktemp() is in <unistd.h> for libc4, libc5, glibc1;
       glibc2 follows POSIX.1 and has the prototype in <stdlib.h>.

SEE ALSO top

       mkdtemp(3), mktemp(3), tempnam(3), tmpfile(3), tmpnam(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-12-21                          MKSTEMP(3)


mktemp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MKTEMP(3)                    Linux Programmer's Manual                   MKTEMP(3)

NAME top

       mktemp - make a unique temporary filename

SYNOPSIS top

       #include <stdlib.h>

       char *mktemp(char *template);

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

       mktemp():
           Since glibc 2.12:
               _BSD_SOURCE || _SVID_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
           Before glibc 2.12:
               _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The mktemp() function generates a unique temporary filename from template.
       The last six characters of template must be XXXXXX and these are replaced
       with a string that makes the filename unique.  Since it will be modified,
       template must not be a string constant, but should be declared as a
       character array.

RETURN VALUE top

       The mktemp() function always returns template.  If a unique name was
       created, the last six bytes of template will have been modified in such a
       way that the resulting name is unique (i.e., does not exist already) If a
       unique name could not be created, template is made an empty string.

ERRORS top

       EINVAL The last six characters of template were not XXXXXX.

CONFORMING TO top

       4.3BSD, POSIX.1-2001.  POSIX.1-2008 removes the specification of mktemp().

NOTES top

       The prototype is in <unistd.h> for libc4, libc5, glibc1; glibc2 follows the
       Single UNIX Specification and has the prototype in <stdlib.h>.

BUGS top

       Never use mktemp().  Some implementations follow 4.3BSD and replace XXXXXX
       by the current process ID and a single letter, so that at most 26 different
       names can be returned.  Since on the one hand the names are easy to guess,
       and on the other hand there is a race between testing whether the name
       exists and opening the file, every use of mktemp() is a security risk.  The
       race is avoided by mkstemp(3).

SEE ALSO top

       mkstemp(3), tempnam(3), tmpfile(3), tmpnam(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           MKTEMP(3)


mlock(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | AVAILABILITY | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MLOCK(2)                     Linux Programmer's Manual                    MLOCK(2)

NAME top

       mlock, munlock, mlockall, munlockall - lock and unlock memory

SYNOPSIS top

       #include <sys/mman.h>

       int mlock(const void *addr, size_t len);
       int munlock(const void *addr, size_t len);

       int mlockall(int flags);
       int munlockall(void);

DESCRIPTION top

       mlock() and mlockall() respectively lock part or all of the calling
       process's virtual address space into RAM, preventing that memory from being
       paged to the swap area.  munlock() and munlockall() perform the converse
       operation, respectively unlocking part or all of the calling process's
       virtual address space, so that pages in the specified virtual address range
       may once more to be swapped out if required by the kernel memory manager.
       Memory locking and unlocking are performed in units of whole pages.

mlock() and munlock()

       mlock() locks pages in the address range starting at addr and continuing
       for len bytes.  All pages that contain a part of the specified address
       range are guaranteed to be resident in RAM when the call returns
       successfully; the pages are guaranteed to stay in RAM until later unlocked.

       munlock() unlocks pages in the address range starting at addr and
       continuing for len bytes.  After this call, all pages that contain a part
       of the specified memory range can be moved to external swap space again by
       the kernel.

mlockall() and munlockall()

       mlockall() locks all pages mapped into the address space of the calling
       process.  This includes the pages of the code, data and stack segment, as
       well as shared libraries, user space kernel data, shared memory, and
       memory-mapped files.  All mapped pages are guaranteed to be resident in RAM
       when the call returns successfully; the pages are guaranteed to stay in RAM
       until later unlocked.

       The flags argument is constructed as the bitwise OR of one or more of the
       following constants:

       MCL_CURRENT Lock all pages which are currently mapped into the address
                   space of the process.

       MCL_FUTURE  Lock all pages which will become mapped into the address space
                   of the process in the future.  These could be for instance new
                   pages required by a growing heap and stack as well as new
                   memory mapped files or shared memory regions.

       If MCL_FUTURE has been specified, then a later system call (e.g., mmap(2),
       sbrk(2), malloc(3)), may fail if it would cause the number of locked bytes
       to exceed the permitted maximum (see below).  In the same circumstances,
       stack growth may likewise fail: the kernel will deny stack expansion and
       deliver a SIGSEGV signal to the process.

       munlockall() unlocks all pages mapped into the address space of the calling
       process.

RETURN VALUE top

       On success these system calls return 0.  On error, -1 is returned, errno is
       set appropriately, and no changes are made to any locks in the address
       space of the process.

ERRORS top

       ENOMEM (Linux 2.6.9 and later) the caller had a nonzero RLIMIT_MEMLOCK soft
              resource limit, but tried to lock more memory than the limit
              permitted.  This limit is not enforced if the process is privileged
              (CAP_IPC_LOCK).

       ENOMEM (Linux 2.4 and earlier) the calling process tried to lock more than
              half of RAM.

       EPERM  The caller is not privileged, but needs privilege (CAP_IPC_LOCK) to
              perform the requested operation.

       For mlock() and munlock():

       EAGAIN Some or all of the specified address range could not be locked.

       EINVAL The result of the addition start+len was less than start (e.g., the
              addition may have resulted in an overflow).

       EINVAL (Not on Linux) addr was not a multiple of the page size.

       ENOMEM Some of the specified address range does not correspond to mapped
              pages in the address space of the process.

       For mlockall():

       EINVAL Unknown flags were specified.

       For munlockall():

       EPERM  (Linux 2.6.8 and earlier) The caller was not privileged
              (CAP_IPC_LOCK).

CONFORMING TO top

       POSIX.1-2001, SVr4.

AVAILABILITY top

       On POSIX systems on which mlock() and munlock() are available,
       _POSIX_MEMLOCK_RANGE is defined in <unistd.h> and the number of bytes in a
       page can be determined from the constant PAGESIZE (if defined) in
       <limits.h> or by calling sysconf(_SC_PAGESIZE).

       On POSIX systems on which mlockall() and munlockall() are available,
       _POSIX_MEMLOCK is defined in <unistd.h> to a value greater than 0.  (See
       also sysconf(3).)

NOTES top

       Memory locking has two main applications: real-time algorithms and high-
       security data processing.  Real-time applications require deterministic
       timing, and, like scheduling, paging is one major cause of unexpected
       program execution delays.  Real-time applications will usually also switch
       to a real-time scheduler with sched_setscheduler(2).  Cryptographic
       security software often handles critical bytes like passwords or secret
       keys as data structures.  As a result of paging, these secrets could be
       transferred onto a persistent swap store medium, where they might be
       accessible to the enemy long after the security software has erased the
       secrets in RAM and terminated.  (But be aware that the suspend mode on
       laptops and some desktop computers will save a copy of the system's RAM to
       disk, regardless of memory locks.)

       Real-time processes that are using mlockall() to prevent delays on page
       faults should reserve enough locked stack pages before entering the time-
       critical section, so that no page fault can be caused by function calls.
       This can be achieved by calling a function that allocates a sufficiently
       large automatic variable (an array) and writes to the memory occupied by
       this array in order to touch these stack pages.  This way, enough pages
       will be mapped for the stack and can be locked into RAM.  The dummy writes
       ensure that not even copy-on-write page faults can occur in the critical
       section.

       Memory locks are not inherited by a child created via fork(2) and are
       automatically removed (unlocked) during an execve(2) or when the process
       terminates.

       The memory lock on an address range is automatically removed if the address
       range is unmapped via munmap(2).

       Memory locks do not stack, that is, pages which have been locked several
       times by calls to mlock() or mlockall() will be unlocked by a single call
       to munlock() for the corresponding range or by munlockall().  Pages which
       are mapped to several locations or by several processes stay locked into
       RAM as long as they are locked at least at one location or by at least one
       process.

Linux Notes

       Under Linux, mlock() and munlock() automatically round addr down to the
       nearest page boundary.  However, POSIX.1-2001 allows an implementation to
       require that addr is page aligned, so portable applications should ensure
       this.

       The VmLck field of the Linux-specific /proc/PID/status file shows how many
       kilobytes of memory the process with ID PID has locked using mlock(),
       mlockall(), and mmap(2) MAP_LOCKED.

Limits and permissions

       In Linux 2.6.8 and earlier, a process must be privileged (CAP_IPC_LOCK) in
       order to lock memory and the RLIMIT_MEMLOCK soft resource limit defines a
       limit on how much memory the process may lock.

       Since Linux 2.6.9, no limits are placed on the amount of memory that a
       privileged process can lock and the RLIMIT_MEMLOCK soft resource limit
       instead defines a limit on how much memory an unprivileged process may
       lock.

BUGS top

       In the 2.4 series Linux kernels up to and including 2.4.17, a bug caused
       the mlockall() MCL_FUTURE flag to be inherited across a fork(2).  This was
       rectified in kernel 2.4.18.

       Since kernel 2.6.9, if a privileged process calls mlockall(MCL_FUTURE) and
       later drops privileges (loses the CAP_IPC_LOCK capability by, for example,
       setting its effective UID to a nonzero value), then subsequent memory
       allocations (e.g., mmap(2), brk(2)) will fail if the RLIMIT_MEMLOCK
       resource limit is encountered.

SEE ALSO top

       mmap(2), setrlimit(2), shmctl(2), sysconf(3), proc(5), capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-14                            MLOCK(2)


mmap(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | AVAILABILITY | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MMAP(2)                      Linux Programmer's Manual                     MMAP(2)

NAME top

       mmap, munmap - map or unmap files or devices into memory

SYNOPSIS top

       #include <sys/mman.h>

       void *mmap(void *addr, size_t length, int prot, int flags,
                  int fd, off_t offset);
       int munmap(void *addr, size_t length);

DESCRIPTION top

       mmap() creates a new mapping in the virtual address space of the calling
       process.  The starting address for the new mapping is specified in addr.
       The length argument specifies the length of the mapping.

       If addr is NULL, then the kernel chooses the address at which to create the
       mapping; this is the most portable method of creating a new mapping.  If
       addr is not NULL, then the kernel takes it as a hint about where to place
       the mapping; on Linux, the mapping will be created at a nearby page
       boundary.  The address of the new mapping is returned as the result of the
       call.

       The contents of a file mapping (as opposed to an anonymous mapping; see
       MAP_ANONYMOUS below), are initialized using length bytes starting at offset
       offset in the file (or other object) referred to by the file descriptor fd.
       offset must be a multiple of the page size as returned by
       sysconf(_SC_PAGE_SIZE).

       The prot argument describes the desired memory protection of the mapping
       (and must not conflict with the open mode of the file).  It is either
       PROT_NONE or the bitwise OR of one or more of the following flags:

       PROT_EXEC  Pages may be executed.

       PROT_READ  Pages may be read.

       PROT_WRITE Pages may be written.

       PROT_NONE  Pages may not be accessed.

       The flags argument determines whether updates to the mapping are visible to
       other processes mapping the same region, and whether updates are carried
       through to the underlying file.  This behavior is determined by including
       exactly one of the following values in flags:

       MAP_SHARED Share this mapping.  Updates to the mapping are visible to other
                  processes that map this file, and are carried through to the
                  underlying file.  The file may not actually be updated until
                  msync(2) or munmap() is called.

       MAP_PRIVATE
                  Create a private copy-on-write mapping.  Updates to the mapping
                  are not visible to other processes mapping the same file, and
                  are not carried through to the underlying file.  It is
                  unspecified whether changes made to the file after the mmap()
                  call are visible in the mapped region.

       Both of these flags are described in POSIX.1-2001.

       In addition, zero or more of the following values can be ORed in flags:

       MAP_32BIT (since Linux 2.4.20, 2.6)
              Put the mapping into the first 2 Gigabytes of the process address
              space.  This flag is only supported on x86-64, for 64-bit programs.
              It was added to allow thread stacks to be allocated somewhere in the
              first 2GB of memory, so as to improve context-switch performance on
              some early 64-bit processors.  Modern x86-64 processors no longer
              have this performance problem, so use of this flag is not required
              on those systems.  The MAP_32BIT flag is ignored when MAP_FIXED is
              set.

       MAP_ANON
              Synonym for MAP_ANONYMOUS.  Deprecated.

       MAP_ANONYMOUS
              The mapping is not backed by any file; its contents are initialized
              to zero.  The fd and offset arguments are ignored; however, some
              implementations require fd to be -1 if MAP_ANONYMOUS (or MAP_ANON)
              is specified, and portable applications should ensure this.  The use
              of MAP_ANONYMOUS in conjunction with MAP_SHARED is only supported on
              Linux since kernel 2.4.

       MAP_DENYWRITE
              This flag is ignored.  (Long ago, it signaled that attempts to write
              to the underlying file should fail with ETXTBUSY.  But this was a
              source of denial-of-service attacks.)

       MAP_EXECUTABLE
              This flag is ignored.

       MAP_FILE
              Compatibility flag.  Ignored.

       MAP_FIXED
              Don't interpret addr as a hint: place the mapping at exactly that
              address.  addr must be a multiple of the page size.  If the memory
              region specified by addr and len overlaps pages of any existing
              mapping(s), then the overlapped part of the existing mapping(s) will
              be discarded.  If the specified address cannot be used, mmap() will
              fail.  Because requiring a fixed address for a mapping is less
              portable, the use of this option is discouraged.

       MAP_GROWSDOWN
              Used for stacks.  Indicates to the kernel virtual memory system that
              the mapping should extend downward in memory.

       MAP_HUGETLB (since Linux 2.6.32)
              Allocate the mapping using "huge pages."  See the Linux kernel
              source file Documentation/vm/hugetlbpage.txt for further
              information.

       MAP_LOCKED (since Linux 2.5.37)
              Lock the pages of the mapped region into memory in the manner of
              mlock(2).  This flag is ignored in older kernels.

       MAP_NONBLOCK (since Linux 2.5.46)
              Only meaningful in conjunction with MAP_POPULATE.  Don't perform
              read-ahead: only create page tables entries for pages that are
              already present in RAM.  Since Linux 2.6.23, this flag causes
              MAP_POPULATE to do nothing.  One day the combination of MAP_POPULATE
              and MAP_NONBLOCK may be reimplemented.

       MAP_NORESERVE
              Do not reserve swap space for this mapping.  When swap space is
              reserved, one has the guarantee that it is possible to modify the
              mapping.  When swap space is not reserved one might get SIGSEGV upon
              a write if no physical memory is available.  See also the discussion
              of the file /proc/sys/vm/overcommit_memory in proc(5).  In kernels
              before 2.6, this flag only had effect for private writable mappings.

       MAP_POPULATE (since Linux 2.5.46)
              Populate (prefault) page tables for a mapping.  For a file mapping,
              this causes read-ahead on the file.  Later accesses to the mapping
              will not be blocked by page faults.  MAP_POPULATE is only supported
              for private mappings since Linux 2.6.23.

       MAP_STACK (since Linux 2.6.27)
              Allocate the mapping at an address suitable for a process or thread
              stack.  This flag is currently a no-op, but is used in the glibc
              threading implementation so that if some architectures require
              special treatment for stack allocations, support can later be
              transparently implemented for glibc.

       MAP_UNINITIALIZED (since Linux 2.6.33)
              Don't clear anonymous pages.  This flag is intended to improve
              performance on embedded devices.  This flag is only honored if the
              kernel was configured with the CONFIG_MMAP_ALLOW_UNINITIALIZED
              option.  Because of the security implications, that option is
              normally enabled only on embedded devices (i.e., devices where one
              has complete control of the contents of user memory).

       Of the above flags, only MAP_FIXED is specified in POSIX.1-2001.  However,
       most systems also support MAP_ANONYMOUS (or its synonym MAP_ANON).

       Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV,
       MAP_COPY, and MAP_LOCAL.

       Memory mapped by mmap() is preserved across fork(2), with the same
       attributes.

       A file is mapped in multiples of the page size.  For a file that is not a
       multiple of the page size, the remaining memory is zeroed when mapped, and
       writes to that region are not written out to the file.  The effect of
       changing the size of the underlying file of a mapping on the pages that
       correspond to added or removed regions of the file is unspecified.

munmap()

       The munmap() system call deletes the mappings for the specified address
       range, and causes further references to addresses within the range to
       generate invalid memory references.  The region is also automatically
       unmapped when the process is terminated.  On the other hand, closing the
       file descriptor does not unmap the region.

       The address addr must be a multiple of the page size.  All pages containing
       a part of the indicated range are unmapped, and subsequent references to
       these pages will generate SIGSEGV.  It is not an error if the indicated
       range does not contain any mapped pages.

Timestamps changes for file-backed mappings

       For file-backed mappings, the st_atime field for the mapped file may be
       updated at any time between the mmap() and the corresponding unmapping; the
       first reference to a mapped page will update the field if it has not been
       already.

       The st_ctime and st_mtime field for a file mapped with PROT_WRITE and
       MAP_SHARED will be updated after a write to the mapped region, and before a
       subsequent msync(2) with the MS_SYNC or MS_ASYNC flag, if one occurs.

RETURN VALUE top

       On success, mmap() returns a pointer to the mapped area.  On error, the
       value MAP_FAILED (that is, (void *) -1) is returned, and errno is set
       appropriately.  On success, munmap() returns 0, on failure -1, and errno is
       set (probably to EINVAL).

ERRORS top

       EACCES A file descriptor refers to a non-regular file.  Or MAP_PRIVATE was
              requested, but fd is not open for reading.  Or MAP_SHARED was
              requested and PROT_WRITE is set, but fd is not open in read/write
              (O_RDWR) mode.  Or PROT_WRITE is set, but the file is append-only.

       EAGAIN The file has been locked, or too much memory has been locked (see
              setrlimit(2)).

       EBADF  fd is not a valid file descriptor (and MAP_ANONYMOUS was not set).

       EINVAL We don't like addr, length, or offset (e.g., they are too large, or
              not aligned on a page boundary).

       EINVAL (since Linux 2.6.12) length was 0.

       EINVAL flags contained neither MAP_PRIVATE or MAP_SHARED, or contained both
              of these values.

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

       ENODEV The underlying file system of the specified file does not support
              memory mapping.

       ENOMEM No memory is available, or the process's maximum number of mappings
              would have been exceeded.

       EPERM  The prot argument asks for PROT_EXEC but the mapped area belongs to
              a file on a file system that was mounted no-exec.

       ETXTBSY
              MAP_DENYWRITE was set but the object specified by fd is open for
              writing.

       Use of a mapped region can result in these signals:

       SIGSEGV
              Attempted write into a region mapped as read-only.

       SIGBUS Attempted access to a portion of the buffer that does not correspond
              to the file (for example, beyond the end of the file, including the
              case where another process has truncated the file).

CONFORMING TO top

       SVr4, 4.4BSD, POSIX.1-2001.

AVAILABILITY top

       On POSIX systems on which mmap(), msync(2) and munmap() are available,
       _POSIX_MAPPED_FILES is defined in <unistd.h> to a value greater than 0.
       (See also sysconf(3).)

NOTES top

       This page describes the interface provided by the glibc mmap() wrapper
       function.  Originally, this function invoked a system call of the same
       name.  Since kernel 2.4, that system call has been superseded by mmap2(2),
       and nowadays the glibc mmap() wrapper function invokes mmap2(2) with a
       suitably adjusted value for offset.

       On some hardware architectures (e.g., i386), PROT_WRITE implies PROT_READ.
       It is architecture dependent whether PROT_READ implies PROT_EXEC or not.
       Portable programs should always set PROT_EXEC if they intend to execute
       code in the new mapping.

       The portable way to create a mapping is to specify addr as 0 (NULL), and
       omit MAP_FIXED from flags.  In this case, the system chooses the address
       for the mapping; the address is chosen so as not to conflict with any
       existing mapping, and will not be 0.  If the MAP_FIXED flag is specified,
       and addr is 0 (NULL), then the mapped address will be 0 (NULL).

BUGS top

       On Linux there are no guarantees like those suggested above under
       MAP_NORESERVE.  By default, any process can be killed at any moment when
       the system runs out of memory.

       In kernels before 2.6.7, the MAP_POPULATE flag only has effect if prot is
       specified as PROT_NONE.

       SUSv3 specifies that mmap() should fail if length is 0.  However, in
       kernels before 2.6.12, mmap() succeeded in this case: no mapping was
       created and the call returned addr.  Since kernel 2.6.12, mmap() fails with
       the error EINVAL for this case.

EXAMPLE top

       The following program prints part of the file specified in its first
       command-line argument to standard output.  The range of bytes to be printed
       is specified via offset and length values in the second and third command-
       line arguments.  The program creates a memory mapping of the required pages
       of the file and then uses write(2) to output the desired bytes.

       #include <sys/mman.h>
       #include <sys/stat.h>
       #include <fcntl.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

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

       int
       main(int argc, char *argv[])
       {
           char *addr;
           int fd;
           struct stat sb;
           off_t offset, pa_offset;
           size_t length;
           ssize_t s;

           if (argc < 3 || argc > 4) {
               fprintf(stderr, "%s file offset [length]\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           fd = open(argv[1], O_RDONLY);
           if (fd == -1)
               handle_error("open");

           if (fstat(fd, &sb) == -1)           /* To obtain file size */
               handle_error("fstat");

           offset = atoi(argv[2]);
           pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) - 1);
               /* offset for mmap() must be page aligned */

           if (offset >= sb.st_size) {
               fprintf(stderr, "offset is past end of file\n");
               exit(EXIT_FAILURE);
           }

           if (argc == 4) {
               length = atoi(argv[3]);
               if (offset + length > sb.st_size)
                   length = sb.st_size - offset;
                       /* Can't display bytes past end of file */

           } else {    /* No length arg ==> display to end of file */
               length = sb.st_size - offset;
           }

           addr = mmap(NULL, length + offset - pa_offset, PROT_READ,
                       MAP_PRIVATE, fd, pa_offset);
           if (addr == MAP_FAILED)
               handle_error("mmap");

           s = write(STDOUT_FILENO, addr + offset - pa_offset, length);
           if (s != length) {
               if (s == -1)
                   handle_error("write");

               fprintf(stderr, "partial write");
               exit(EXIT_FAILURE);
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getpagesize(2), mincore(2), mlock(2), mmap2(2), mprotect(2), mremap(2),
       msync(2), remap_file_pages(2), setrlimit(2), shmat(2), shm_open(3),
       shm_overview(7)

       B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.

COLOPHON top

       This page is part of release 3.45 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                               2012-04-16                             MMAP(2)


mmap2(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MMAP2(2)                     Linux Programmer's Manual                    MMAP2(2)

NAME top

       mmap2 - map files or devices into memory

SYNOPSIS top

       #include <sys/mman.h>

       void *mmap2(void *addr, size_t length, int prot,
                    int flags, int fd, off_t pgoffset);

DESCRIPTION top

       This is probably not the system call you are interested; instead, see
       mmap(2), which describes the glibc wrapper function that invokes this
       system call.

       The mmap2() system call provides the same interface as mmap(2), except that
       the final argument specifies the offset into the file in 4096-byte units
       (instead of bytes, as is done by mmap(2)).  This enables applications that
       use a 32-bit off_t to map large files (up to 2^44 bytes).

RETURN VALUE top

       On success, mmap2() returns a pointer to the mapped area.  On error -1 is
       returned and errno is set appropriately.

ERRORS top

       EFAULT Problem with getting the data from user space.

       EINVAL (Various platforms where the page size is not 4096 bytes.)  offset *
              4096 is not a multiple of the system page size.

       mmap2() can also return any of the errors described in mmap(2).

VERSIONS top

       mmap2() is available since Linux 2.3.31.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       Nowadays, the glibc mmap() wrapper function invokes this system call rather
       than the mmap(2) system call.

       On ia64, the unit for offset is actually the system page size, rather than
       4096 bytes.

SEE ALSO top

       getpagesize(2), mmap(2), mremap(2), msync(2), shm_open(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-16                            MMAP2(2)


modf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MODF(3)                      Linux Programmer's Manual                     MODF(3)

NAME top

       modf,  modff,  modfl  -  extract signed integral and fractional values from
       floating-point number

SYNOPSIS top

       #include <math.h>

       double modf(double x, double *iptr);
       float modff(float x, float *iptr);
       long double modfl(long double x, long double *iptr);

       Link with -lm.

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

       modf(), modfl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The modf() function breaks the argument x into an integral part and a
       fractional part, each of which has the same sign as x.  The integral part
       is stored in the location pointed to by iptr.

RETURN VALUE top

       The modf() function returns the fractional part of x.

       If x is a NaN, a NaN is returned, and *iptr is set to a NaN.

       If x is positive infinity (negative infinity), +0 (-0) is returned, and
       *iptr is set to positive infinity (negative infinity).

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       frexp(3), ldexp(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             MODF(3)


modify_ldt(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MODIFY_LDT(2)                Linux Programmer's Manual               MODIFY_LDT(2)

NAME top

       modify_ldt - get or set ldt

SYNOPSIS top

       #include <sys/types.h>

       int modify_ldt(int func, void *ptr, unsigned long bytecount);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       modify_ldt() reads or writes the local descriptor table (ldt) for a
       process.  The ldt is a per-process memory management table used by the i386
       processor.  For more information on this table, see an Intel 386 processor
       handbook.

       When func is 0, modify_ldt() reads the ldt into the memory pointed to by
       ptr.  The number of bytes read is the smaller of bytecount and the actual
       size of the ldt.

       When func is 1, modify_ldt() modifies one ldt entry.  ptr points to a
       user_desc structure and bytecount must equal the size of this structure.

       The user_desc structure is defined in <asm/ldt.h> as:

           struct user_desc {
               unsigned int  entry_number;
               unsigned long base_addr;
               unsigned int  limit;
               unsigned int  seg_32bit:1;
               unsigned int  contents:2;
               unsigned int  read_exec_only:1;
               unsigned int  limit_in_pages:1;
               unsigned int  seg_not_present:1;
               unsigned int  useable:1;
           };

       In Linux 2.4 and earlier, this structure was named modify_ldt_ldt_s.

RETURN VALUE top

       On success, modify_ldt() returns either the actual number of bytes read
       (for reading) or 0 (for writing).  On failure, modify_ldt() returns -1 and
       sets errno to indicate the error.

ERRORS top

       EFAULT ptr points outside the address space.

       EINVAL ptr is 0, or func is 1 and bytecount is not equal to the size of the
              structure modify_ldt_ldt_s, or func is 1 and the new ldt entry has
              invalid values.

       ENOSYS func is neither 0 nor 1.

CONFORMING TO top

       This call is Linux-specific and should not be used in programs intended to
       be portable.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

SEE ALSO top

       vm86(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                       MODIFY_LDT(2)


motd(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

MOTD(5)                      Linux Programmer's Manual                     MOTD(5)

NAME top

       motd - message of the day

DESCRIPTION top

       The contents of /etc/motd are displayed by login(1) after a successful
       login but just before it executes the login shell.

       The abbreviation "motd" stands for "message of the day", and this file has
       been traditionally used for exactly that (it requires much less disk space
       than mail to all users).

FILES top

       /etc/motd

SEE ALSO top

       login(1), issue(5)

COLOPHON top

       This page is part of release 3.45 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                               1992-12-29                             MOTD(5)


mount(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MOUNT(2)                     Linux Programmer's Manual                    MOUNT(2)

NAME top

       mount - mount file system

SYNOPSIS top

       #include <sys/mount.h>

       int mount(const char *source, const char *target,
                 const char *filesystemtype, unsigned long mountflags,
                 const void *data);

DESCRIPTION top

       mount() attaches the file system specified by source (which is often a
       device name, but can also be a directory name or a dummy) to the directory
       specified by target.

       Appropriate privilege (Linux: the CAP_SYS_ADMIN capability) is required to
       mount file systems.

       Since Linux 2.4 a single file system can be visible at multiple mount
       points, and multiple mounts can be stacked on the same mount point.

       Values for the filesystemtype argument supported by the kernel are listed
       in /proc/filesystems (e.g., "minix", "ext2", "ext3", "jfs", "xfs",
       "reiserfs", "msdos", "proc", "nfs", "iso9660").  Further types may become
       available when the appropriate modules are loaded.

       The mountflags argument may have the magic number 0xC0ED (MS_MGC_VAL) in
       the top 16 bits (this was required in kernel versions prior to 2.4, but is
       no longer required and ignored if specified), and various mount flags in
       the low order 16 bits:

       MS_BIND (Linux 2.4 onward)
              Perform a bind mount, making a file or a directory subtree visible
              at another point within a file system.  Bind mounts may cross file
              system boundaries and span chroot(2) jails.  The filesystemtype and
              data arguments are ignored.  Up until Linux 2.6.26, mountflags was
              also ignored (the bind mount has the same mount options as the
              underlying mount point).

       MS_DIRSYNC (since Linux 2.5.19)
              Make directory changes on this file system synchronous.  (This
              property can be obtained for individual directories or subtrees
              using chattr(1).)

       MS_MANDLOCK
              Permit mandatory locking on files in this file system.  (Mandatory
              locking must still be enabled on a per-file basis, as described in
              fcntl(2).)

       MS_MOVE
              Move a subtree.  source specifies an existing mount point and target
              specifies the new location.  The move is atomic: at no point is the
              subtree unmounted.  The filesystemtype, mountflags, and data
              arguments are ignored.

       MS_NOATIME
              Do not update access times for (all types of) files on this file
              system.

       MS_NODEV
              Do not allow access to devices (special files) on this file system.

       MS_NODIRATIME
              Do not update access times for directories on this file system.
              This flag provides a subset of the functionality provided by
              MS_NOATIME; that is, MS_NOATIME implies MS_NODIRATIME.

       MS_NOEXEC
              Do not allow programs to be executed from this file system.

       MS_NOSUID
              Do not honor set-user-ID and set-group-ID bits when executing
              programs from this file system.

       MS_RDONLY
              Mount file system read-only.

       MS_RELATIME (Since Linux 2.6.20)
              When a file on this file system is accessed, only update the file's
              last access time (atime) if the current value of atime is less than
              or equal to the file's last modification time (mtime) or last status
              change time (ctime).  This option is useful for programs, such as
              mutt(1), that need to know when a file has been read since it was
              last modified.  Since Linux 2.6.30, the kernel defaults to the
              behavior provided by this flag (unless MS_NOATIME was specified),
              and the MS_STRICTATIME flag is required to obtain traditional
              semantics.  In addition, since Linux 2.6.30, the file's last access
              time is always updated if it is more than 1 day old.

       MS_REMOUNT
              Remount an existing mount.  This allows you to change the mountflags
              and data of an existing mount without having to unmount and remount
              the file system.  target should be the same value specified in the
              initial mount() call; source and filesystemtype are ignored.

              The following mountflags can be changed: MS_RDONLY, MS_SYNCHRONOUS,
              MS_MANDLOCK; before kernel 2.6.16, the following could also be
              changed: MS_NOATIME and MS_NODIRATIME; and, additionally, before
              kernel 2.4.10, the following could also be changed: MS_NOSUID,
              MS_NODEV, MS_NOEXEC.

       MS_SILENT (since Linux 2.6.17)
              Suppress the display of certain (printk()) warning messages in the
              kernel log.  This flag supersedes the misnamed and obsolete
              MS_VERBOSE flag (available since Linux 2.4.12), which has the same
              meaning.

       MS_STRICTATIME (Since Linux 2.6.30)
              Always update the last access time (atime) when files on this file
              system are accessed.  (This was the default behavior before Linux
              2.6.30.)  Specifying this flag overrides the effect of setting the
              MS_NOATIME and MS_RELATIME flags.

       MS_SYNCHRONOUS
              Make writes on this file system synchronous (as though the O_SYNC
              flag to open(2) was specified for all file opens to this file
              system).

       From Linux 2.4 onward, the MS_NODEV, MS_NOEXEC, and MS_NOSUID flags are
       settable on a per-mount-point basis.  From kernel 2.6.16 onward, MS_NOATIME
       and MS_NODIRATIME are also settable on a per-mount-point basis.  The
       MS_RELATIME flag is also settable on a per-mount-point basis.

       The data argument is interpreted by the different file systems.  Typically
       it is a string of comma-separated options understood by this file system.
       See mount(8) for details of the options available for each filesystem type.

RETURN VALUE top

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

ERRORS top

       The error values given below result from filesystem type independent
       errors.  Each file-system type may have its own special errors and its own
       special behavior.  See the Linux kernel source code for details.

       EACCES A component of a path was not searchable.  (See also
              path_resolution(7).)  Or, mounting a read-only file system was
              attempted without giving the MS_RDONLY flag.  Or, the block device
              source is located on a file system mounted with the MS_NODEV option.

       EBUSY  source is already mounted.  Or, it cannot be remounted read-only,
              because it still holds files open for writing.  Or, it cannot be
              mounted on target because target is still busy (it is the working
              directory of some thread, the mount point of another device, has
              open files, etc.).

       EFAULT One of the pointer arguments points outside the user address space.

       EINVAL source had an invalid superblock.  Or, a remount (MS_REMOUNT) was
              attempted, but source was not already mounted on target.  Or, a move
              (MS_MOVE) was attempted, but source was not a mount point, or was
              '/'.

       ELOOP  Too many links encountered during pathname resolution.  Or, a move
              was attempted, while target is a descendant of source.

       EMFILE (In case no block device is required:) Table of dummy devices is
              full.

       ENAMETOOLONG
              A pathname was longer than MAXPATHLEN.

       ENODEV filesystemtype not configured in the kernel.

       ENOENT A pathname was empty or had a nonexistent component.

       ENOMEM The kernel could not allocate a free page to copy filenames or data
              into.

       ENOTBLK
              source is not a block device (and a device was required).

       ENOTDIR
              target, or a prefix of source, is not a directory.

       ENXIO  The major number of the block device source is out of range.

       EPERM  The caller does not have the required privileges.

VERSIONS top

       The definitions of MS_DIRSYNC, MS_MOVE, MS_REC, MS_RELATIME, and
       MS_STRICTATIME were only added to glibc headers in version 2.12.

CONFORMING TO top

       This function is Linux-specific and should not be used in programs intended
       to be portable.

NOTES top

       The original MS_SYNC flag was renamed MS_SYNCHRONOUS in 1.1.69 when a
       different MS_SYNC was added to <mman.h>.

       Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID
       program on a file system mounted with MS_NOSUID would fail with EPERM.
       Since Linux 2.4 the set-user-ID and set-group-ID bits are just silently
       ignored in this case.

Per-process Namespaces

       Starting with kernel 2.4.19, Linux provides per-process mount namespaces.
       A mount namespace is the set of file system mounts that are visible to a
       process.  Mount-point namespaces can be (and usually are) shared between
       multiple processes, and changes to the namespace (i.e., mounts and
       unmounts) by one process are visible to all other processes sharing the
       same namespace.  (The pre-2.4.19 Linux situation can be considered as one
       in which a single namespace was shared by every process on the system.)

       A child process created by fork(2) shares its parent's mount namespace; the
       mount namespace is preserved across an execve(2).

       A process can obtain a private mount namespace if: it was created using the
       clone(2) CLONE_NEWNS flag, in which case its new namespace is initialized
       to be a copy of the namespace of the process that called clone(2); or it
       calls unshare(2) with the CLONE_NEWNS flag, which causes the caller's mount
       namespace to obtain a private copy of the namespace that it was previously
       sharing with other processes, so that future mounts and unmounts by the
       caller are invisible to other processes (except child processes that the
       caller subsequently creates) and vice versa.

       The Linux-specific /proc/PID/mounts file exposes the list of mount points
       in the mount namespace of the process with the specified ID; see proc(5)
       for details.

SEE ALSO top

       umount(2), path_resolution(7), mount(8), umount(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-05                            MOUNT(2)


mouse(4) - Linux manual page

NAME | CONFIGURATION | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

MOUSE(4)                     Linux Programmer's Manual                    MOUSE(4)

NAME top

       mouse - serial mouse interface

CONFIGURATION top

       Serial  mice  are connected to a serial RS232/V24 dialout line, see ttyS(4)
       for a description.

DESCRIPTION top

Introduction

       The pinout of the usual 9 pin plug as used for serial mice is:

                            pin   name   used for
                              2    RX    Data
                              3    TX    -12 V, Imax = 10 mA
                              4   DTR    +12 V, Imax = 10 mA
                              7   RTS    +12 V, Imax = 10 mA
                              5   GND    Ground

       This is the specification, in fact 9 V suffices with most mice.

       The mouse driver can recognize a mouse by dropping RTS to low and raising
       it again.  About 14 ms later the mouse will send 0x4D ('M') on the data
       line.  After a further 63 ms, a Microsoft-compatible 3-button mouse will
       send 0x33 ('3').

       The relative mouse movement is sent as dx (positive means right) and dy
       (positive means down).  Various mice can operate at different speeds.  To
       select speeds, cycle through the speeds 9600, 4800, 2400 and 1200 bit/s,
       each time writing the two characters from the table below and waiting 0.1
       seconds.  The following table shows available speeds and the strings that
       select them:

                                     bit/s   string
                                     9600    *q
                                     4800    *p
                                     2400    *o
                                     1200    *n

       The first byte of a data packet can be used to synchronization purposes.

Microsoft protocol

       The Microsoft protocol uses 1 start bit, 7 data bits, no parity and one
       stop bit at the speed of 1200 bits/sec.  Data is sent to RxD in 3-byte
       packets.  The dx and dy movements are sent as two's-complement, lb (rb) are
       set when the left (right) button is pressed:

                      byte   d6   d5    d4    d3    d2    d1    d0
                         1   1    lb    rb    dy7   dy6   dx7   dx6
                         2   0    dx5   dx4   dx3   dx2   dx1   dx0
                         3   0    dy5   dy4   dy3   dy2   dy1   dy0

3-button Microsoft protocol

       Original Microsoft mice only have two buttons.  However, there are some
       three button mice which also use the Microsoft protocol.  Pressing or
       releasing the middle button is reported by sending a packet with zero
       movement and no buttons pressed.  (Thus, unlike for the other two buttons,
       the status of the middle button is not reported in each packet.)

Logitech protocol

       Logitech serial 3-button mice use a different extension of the Microsoft
       protocol: when the middle button is up, the above 3-byte packet is sent.
       When the middle button is down a 4-byte packet is sent, where the 4th byte
       has value 0x20 (or at least has the 0x20 bit set).  In particular, a press
       of the middle button is reported as 0,0,0,0x20 when no other buttons are
       down.

Mousesystems protocol

       The Mousesystems protocol uses 1 start bit, 8 data bits, no parity and two
       stop bits at the speed of 1200 bits/sec.  Data is sent to RxD in 5-byte
       packets.  dx is sent as the sum of the two two's-complement values, dy is
       send as negated sum of the two two's-complement values.  lb (mb, rb) are
       cleared when the left (middle, right) button is pressed:

               byte   d7    d6     d5     d4     d3     d2     d1     d0
                  1   1     0      0      0      0      lb     mb     rb
                  2   0    dxa6   dxa5   dxa4   dxa3   dxa2   dxa1   dxa0
                  3   0    dya6   dya5   dya4   dya3   dya2   dya1   dya0
                  4   0    dxb6   dxb5   dxb4   dxb3   dxb2   dxb1   dxb0
                  5   0    dyb6   dyb5   dyb4   dyb3   dyb2   dyb1   dyb0

       Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 were
       transmitted.

Sun protocol

       The Sun protocol is the 3-byte version of the above 5-byte Mousesystems
       protocol: the last two bytes are not sent.

MM protocol

       The MM protocol uses 1 start bit, 8 data bits, odd parity and one stop bit
       at the speed of 1200 bits/sec.  Data is sent to RxD in 3-byte packets.  dx
       and dy are sent as single signed values, the sign bit indicating a negative
       value.  lb (mb, rb) are set when the left (middle, right) button is
       pressed:

                   byte   d7   d6    d5    d4    d3    d2    d1    d0
                      1   1     0     0    dxs   dys   lb    mb    rb
                      2   0    dx6   dx5   dx4   dx3   dx2   dx1   dx0
                      3   0    dy6   dy5   dy4   dy3   dy2   dy1   dy0

FILES          top
       /dev/mouse
              A commonly used symlink pointing to a mouse device.

SEE ALSO          top
       ttyS(4), gpm(8)

COLOPHON          top
       This page is part of release 3.45 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                               1996-02-10                            MOUSE(4)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


move_pages(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | Page states in the status array | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MOVE_PAGES(2)                Linux Programmer's Manual               MOVE_PAGES(2)

NAME top

       move_pages - move individual pages of a process to another node

SYNOPSIS top

       #include <numaif.h>

       long move_pages(int pid, unsigned long count, void **pages,
                       const int *nodes, int *status, int flags);

       Link with -lnuma.

DESCRIPTION top

       move_pages() moves the specified pages of the process pid to the memory
       nodes specified by nodes.  The result of the move is reflected in status.
       The flags indicate constraints on the pages to be moved.

       pid is the ID of the process in which pages are to be moved.  To move pages
       in another process, the caller must be privileged (CAP_SYS_NICE) or the
       real or effective user ID of the calling process must match the real or
       saved-set user ID of the target process.  If pid is 0, then move_pages()
       moves pages of the calling process.

       count is the number of pages to move.  It defines the size of the three
       arrays pages, nodes, and status.

       pages is an array of pointers to the pages that should be moved.  These are
       pointers that should be aligned to page boundaries.  Addresses are
       specified as seen by the process specified by pid.

       nodes is an array of integers that specify the desired location for each
       page.  Each element in the array is a node number.  nodes can also be NULL,
       in which case move_pages() does not move any pages but instead will return
       the node where each page currently resides, in the status array.  Obtaining
       the status of each page may be necessary to determine pages that need to be
       moved.

       status is an array of integers that return the status of each page.  The
       array only contains valid values if move_pages() did not return an error.

       flags specify what types of pages to move.  MPOL_MF_MOVE means that only
       pages that are in exclusive use by the process are to be moved.
       MPOL_MF_MOVE_ALL means that pages shared between multiple processes can
       also be moved.  The process must be privileged (CAP_SYS_NICE) to use
       MPOL_MF_MOVE_ALL.

Page states in the status array top

       The following values can be returned in each element of the status array.

       0..MAX_NUMNODES
              Identifies the node on which the page resides.

       -EACCES
              The page is mapped by multiple processes and can only be moved if
              MPOL_MF_MOVE_ALL is specified.

       -EBUSY The page is currently busy and cannot be moved.  Try again later.
              This occurs if a page is undergoing I/O or another kernel subsystem
              is holding a reference to the page.

       -EFAULT
              This is a zero page or the memory area is not mapped by the process.

       -EIO   Unable to write back a page.  The page has to be written back in
              order to move it since the page is dirty and the file system does
              not provide a migration function that would allow the move of dirty
              pages.

       -EINVAL
              A dirty page cannot be moved.  The file system does not provide a
              migration function and has no ability to write back pages.

       -ENOENT
              The page is not present.

       -ENOMEM
              Unable to allocate memory on target node.

RETURN VALUE top

       On success move_pages() returns zero.  On error, it returns -1, and sets
       errno to indicate the error.

ERRORS top

       E2BIG  Too many pages to move.

       EACCES One of the target nodes is not allowed by the current cpuset.

       EFAULT Parameter array could not be accessed.

       EINVAL Flags other than MPOL_MF_MOVE and MPOL_MF_MOVE_ALL was specified or
              an attempt was made to migrate pages of a kernel thread.

       ENODEV One of the target nodes is not online.

       ENOENT No pages were found that require moving.  All pages are either
              already on the target node, not present, had an invalid address or
              could not be moved because they were mapped by multiple processes.

       EPERM  The caller specified MPOL_MF_MOVE_ALL without sufficient privileges
              (CAP_SYS_NICE).  Or, the caller attempted to move pages of a process
              belonging to another user but did not have privilege to do so
              (CAP_SYS_NICE).

       ESRCH  Process does not exist.

VERSIONS top

       move_pages() first appeared on Linux in version 2.6.18.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       For information on library support, see numa(7).

       Use get_mempolicy(2) with the MPOL_F_MEMS_ALLOWED flag to obtain the set of
       nodes that are allowed by the current cpuset.  Note that this information
       is subject to change at any time by manual or automatic reconfiguration of
       the cpuset.

       Use of this function may result in pages whose location (node) violates the
       memory policy established for the specified addresses (See mbind(2)) and/or
       the specified process (See set_mempolicy(2)).  That is, memory policy does
       not constrain the destination nodes used by move_pages().

       The <numaif.h> header is not included with glibc, but requires installing
       libnuma-devel or a similar package.

SEE ALSO top

       get_mempolicy(2), mbind(2), set_mempolicy(2), numa(3), numa_maps(5),
       cpuset(7), numa(7), migratepages(8), numa_stat(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-06-11                       MOVE_PAGES(2)


mpool(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MPOOL(3)                     Linux Programmer's Manual                    MPOOL(3)

NAME top

       mpool - shared memory buffer pool

SYNOPSIS top

       #include <db.h>
       #include <mpool.h>

       MPOOL *mpool_open(DBT *key, int fd, pgno_t pagesize, pgno_t maxcache);

       void mpool_filter(MPOOL *mp, void (*pgin)(void *, pgno_t, void *),
                         void (*pgout)(void *, pgno_t, void *),
                         void *pgcookie);

       void *mpool_new(MPOOL *mp, pgno_t *pgnoaddr);

       void *mpool_get(MPOOL *mp, pgno_t pgno, unsigned int flags);

       int mpool_put(MPOOL *mp, void *pgaddr, unsigned int flags);

       int mpool_sync(MPOOL *mp);

       int mpool_close(MPOOL *mp);

DESCRIPTION top

       Note well: This page documents interfaces provided in glibc up until
       version 2.1.  Since version 2.2, glibc no longer provides these interfaces.
       Probably, you are looking for the APIs provided by the libdb library
       instead.

       Mpool is the library interface intended to provide page oriented buffer
       management of files.  The buffers may be shared between processes.

       The function mpool_open() initializes a memory pool.  The key argument is
       the byte string used to negotiate between multiple processes wishing to
       share buffers.  If the file buffers are mapped in shared memory, all
       processes using the same key will share the buffers.  If key is NULL, the
       buffers are mapped into private memory.  The fd argument is a file
       descriptor for the underlying file, which must be seekable.  If key is non-
       NULL and matches a file already being mapped, the fd argument is ignored.

       The pagesize argument is the size, in bytes, of the pages into which the
       file is broken up.  The maxcache argument is the maximum number of pages
       from the underlying file to cache at any one time.  This value is not
       relative to the number of processes which share a file's buffers, but will
       be the largest value specified by any of the processes sharing the file.

       The mpool_filter() function is intended to make transparent input and
       output processing of the pages possible.  If the pgin function is
       specified, it is called each time a buffer is read into the memory pool
       from the backing file.  If the pgout function is specified, it is called
       each time a buffer is written into the backing file.  Both functions are
       called with the pgcookie pointer, the page number and a pointer to the page
       to being read or written.

       The function mpool_new() takes an MPOOL pointer and an address as
       arguments.  If a new page can be allocated, a pointer to the page is
       returned and the page number is stored into the pgnoaddr address.
       Otherwise, NULL is returned and errno is set.

       The function mpool_get() takes an MPOOL pointer and a page number as
       arguments.  If the page exists, a pointer to the page is returned.
       Otherwise, NULL is returned and errno is set.  The flags argument is not
       currently used.

       The function mpool_put() unpins the page referenced by pgaddr.  pgaddr must
       be an address previously returned by mpool_get() or mpool_new().  The flag
       value is specified by ORing any of the following values:

       MPOOL_DIRTY
              The page has been modified and needs to be written to the backing
              file.

       mpool_put() returns 0 on success and -1 if an error occurs.

       The function mpool_sync() writes all modified pages associated with the
       MPOOL pointer to the backing file.  mpool_sync() returns 0 on success and
       -1 if an error occurs.

       The mpool_close() function free's up any allocated memory associated with
       the memory pool cookie.  Modified pages are not written to the backing
       file.  mpool_close() returns 0 on success and -1 if an error occurs.

ERRORS top

       The mpool_open() function may fail and set errno for any of the errors
       specified for the library routine malloc(3).

       The mpool_get() function may fail and set errno for the following:

       EINVAL         The requested record doesn't exist.

       The mpool_new() and mpool_get() functions may fail and set errno for any of
       the errors specified for the library routines read(2), write(2), and
       malloc(3).

       The mpool_sync() function may fail and set errno for any of the errors
       specified for the library routine write(2).

       The mpool_close() function may fail and set errno for any of the errors
       specified for the library routine free(3).

CONFORMING TO top

       Not in POSIX.1-2001.  Present on the BSDs.

SEE ALSO top

       btree(3), dbopen(3), hash(3), recno(3)

COLOPHON top

       This page is part of release 3.45 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/.

4.4 Berkeley Distribution           2012-04-26                            MPOOL(3)


mprotect(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MPROTECT(2)                  Linux Programmer's Manual                 MPROTECT(2)

NAME top

       mprotect - set protection on a region of memory

SYNOPSIS top

       #include <sys/mman.h>

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

DESCRIPTION top

       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 top

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

ERRORS top

       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-1] 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 top

       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 top

       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 top

       The program below allocates four pages of memory, makes the third of these
       pages read-only, and then executes a loop that walks upward 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_READ) == -1)
               handle_error("mprotect");

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

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

SEE ALSO top

       mmap(2), sysconf(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-14                         MPROTECT(2)


mq_close(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_CLOSE(3)                  Linux Programmer's Manual                 MQ_CLOSE(3)

NAME top

       mq_close - close a message queue descriptor

SYNOPSIS top

       #include <mqueue.h>

       int mq_close(mqd_t mqdes);

       Link with -lrt.

DESCRIPTION top

       mq_close() closes the message queue descriptor mqdes.

       If the calling process has attached a notification request to this message
       queue via mqdes, then this request is removed, and another process can now
       attach a notification request.

RETURN VALUE top

       On success mq_close() returns 0; on error, -1 is returned, with errno set
       to indicate the error.

ERRORS top

       EBADF  The descriptor specified in mqdes is invalid.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       All open message queues are automatically closed on process termination, or
       upon execve(2).

SEE ALSO top

       mq_getattr(3), mq_notify(3), mq_open(3), mq_receive(3), mq_send(3),
       mq_unlink(3), mq_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-08-29                         MQ_CLOSE(3)


mq_getattr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_GETATTR(3)                Linux Programmer's Manual               MQ_GETATTR(3)

NAME top

       mq_getattr, mq_setattr - get/set message queue attributes

SYNOPSIS top

       #include <mqueue.h>

       int mq_getattr(mqd_t mqdes, struct mq_attr *attr);

       int mq_setattr(mqd_t mqdes, struct mq_attr *newattr,
                        struct mq_attr *oldattr);

       Link with -lrt.

DESCRIPTION top

       mq_getattr() and mq_setattr() respectively retrieve and modify attributes
       of the message queue referred to by the descriptor mqdes.

       mq_getattr() returns an mq_attr structure in the buffer pointed by attr.
       This structure is defined as:

           struct mq_attr {
               long mq_flags;       /* Flags: 0 or O_NONBLOCK */
               long mq_maxmsg;      /* Max. # of messages on queue */
               long mq_msgsize;     /* Max. message size (bytes) */
               long mq_curmsgs;     /* # of messages currently in queue */
           };

       The mq_flags field contains flags associated with the open message queue
       description.  This field is initialized when the queue is created by
       mq_open(3).  The only flag that can appear in this field is O_NONBLOCK.

       The mq_maxmsg and mq_msgsize fields are set when the message queue is
       created by mq_open(3).  The mq_maxmsg field is an upper limit on the number
       of messages that may be placed on the queue using mq_send(3).  The
       mq_msgsize field is an upper limit on the size of messages that may be
       placed on the queue.  Both of these fields must have a value greater than
       zero.  Two /proc files that place ceilings on the values for these fields
       are described in mq_open(3).

       The mq_curmsgs field returns the number of messages currently held in the
       queue.

       mq_setattr() sets message queue attributes using information supplied in
       the mq_attr structure pointed to by newattr.  The only attribute that can
       be modified is the setting of the O_NONBLOCK flag in mq_flags.  The other
       fields in newattr are ignored.  If the oldattr field is not NULL, then the
       buffer that it points to is used to return an mq_attr structure that
       contains the same information that is returned by mq_getattr().

RETURN VALUE top

       On success mq_getattr() and mq_setattr() return 0; on error, -1 is
       returned, with errno set to indicate the error.

ERRORS top

       EBADF  The descriptor specified in mqdes is invalid.

       EINVAL newattr->mq_flags contained set bits other than O_NONBLOCK.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       On Linux, mq_getattr() and mq_setattr() are library functions layered on
       top of the mq_getsetattr(2) system call.

SEE ALSO top

       mq_close(3), mq_notify(3), mq_open(3), mq_receive(3), mq_send(3),
       mq_unlink(3), mq_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-08-29                       MQ_GETATTR(3)


mq_getsetattr(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_GETSETATTR(2)             Linux Programmer's Manual            MQ_GETSETATTR(2)

NAME top

       mq_getsetattr - get/set message queue attributes

SYNOPSIS top

       #include <sys/types.h>
       #include <mqueue.h>

       int mq_getsetattr(mqd_t mqdes, struct mq_attr *newattr,
                        struct mq_attr *oldattr);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       Do not use this system call.

       This is the low-level system call used to implement mq_getattr(3) and
       mq_setattr(3).  For an explanation of how this system call operates, see
       the description of mq_setattr(3).

CONFORMING TO top

       This interface is nonstandard; avoid its use.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).  (Actually, never call it unless you are writing a C library!)

SEE ALSO top

       mq_getattr(3), mq_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                    MQ_GETSETATTR(2)


mq_notify(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_NOTIFY(3)                 Linux Programmer's Manual                MQ_NOTIFY(3)

NAME top

       mq_notify - register for notification when a message is available

SYNOPSIS top

       #include <mqueue.h>

       int mq_notify(mqd_t mqdes, const struct sigevent *sevp);

       Link with -lrt.

DESCRIPTION top

       mq_notify() allows the calling process to register or unregister for
       delivery of an asynchronous notification when a new message arrives on the
       empty message queue referred to by the descriptor mqdes.

       The sevp argument is a pointer to a sigevent structure.  For the definition
       and general details of this structure, see sigevent(7).

       If sevp is a non-NULL pointer, then mq_notify() registers the calling
       process to receive message notification.  The sigev_notify field of the
       sigevent structure to which sevp points specifies how notification is to be
       performed.  This field has one of the following values:

       SIGEV_NONE
              A "null" notification: the calling process is registered as the
              target for notification, but when a message arrives, no notification
              is sent.

       SIGEV_SIGNAL
              Notify the process by sending the signal specified in sigev_signo.
              See sigevent(7) for general details.  The si_code field of the
              siginfo_t structure will be set to SI_MESGQ.  In addition, si_pid
              will be set to the PID of the process that sent the message, and
              si_uid will be set to the real user ID of the sending process.

       SIGEV_THREAD
              Upon message delivery, invoke sigev_notify_function as if it were
              the start function of a new thread.  See sigevent(7) for details.

       Only one process can be registered to receive notification from a message
       queue.

       If sevp is NULL, and the calling process is currently registered to receive
       notifications for this message queue, then the registration is removed;
       another process can then register to receive a message notification for
       this queue.

       Message notification only occurs when a new message arrives and the queue
       was previously empty.  If the queue was not empty at the time mq_notify()
       was called, then a notification will only occur after the queue is emptied
       and a new message arrives.

       If another process or thread is waiting to read a message from an empty
       queue using mq_receive(3), then any message notification registration is
       ignored: the message is delivered to the process or thread calling
       mq_receive(3), and the message notification registration remains in effect.

       Notification occurs once: after a notification is delivered, the
       notification registration is removed, and another process can register for
       message notification.  If the notified process wishes to receive the next
       notification, it can use mq_notify() to request a further notification.
       This should be done before emptying all unread messages from the queue.
       (Placing the queue in nonblocking mode is useful for emptying the queue of
       messages without blocking once it is empty.)

RETURN VALUE top

       On success mq_notify() returns 0; on error, -1 is returned, with errno set
       to indicate the error.

ERRORS top

       EBADF  The descriptor specified in mqdes is invalid.

       EBUSY  Another process has already registered to receive notification for
              this message queue.

       EINVAL sevp->sigev_notify is not one of the permitted values; or
              sevp->sigev_notify is SIGEV_SIGNAL and sevp->sigev_signo is not a
              valid signal number.

       ENOMEM Insufficient memory.

       POSIX.1-2008 says that an implementation may generate an EINVAL error if
       sevp is NULL, and the caller is not currently registered to receive
       notifications for the queue mqdes.

CONFORMING TO top

       POSIX.1-2001.

EXAMPLE top

       The following program registers a notification request for the message
       queue named in its command-line argument.  Notification is performed by
       creating a thread.  The thread executes a function which reads one message
       from the queue and then terminates the process.

       #include <pthread.h>
       #include <mqueue.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

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

       static void                     /* Thread start function */
       tfunc(union sigval sv)
       {
           struct mq_attr attr;
           ssize_t nr;
           void *buf;
           mqd_t mqdes = *((mqd_t *) sv.sival_ptr);

           /* Determine max. msg size; allocate buffer to receive msg */

           if (mq_getattr(mqdes, &attr) == -1)
               handle_error("mq_getattr");
           buf = malloc(attr.mq_msgsize);
           if (buf == NULL)
               handle_error("malloc");

           nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
           if (nr == -1)
               handle_error("mq_receive");

           printf("Read %ld bytes from MQ\n", (long) nr);
           free(buf);
           exit(EXIT_SUCCESS);         /* Terminate the process */
       }

       int
       main(int argc, char *argv[])
       {
           mqd_t mqdes;
           struct sigevent sev;

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

           mqdes = mq_open(argv[1], O_RDONLY);
           if (mqdes == (mqd_t) -1)
               handle_error("mq_open");

           sev.sigev_notify = SIGEV_THREAD;
           sev.sigev_notify_function = tfunc;
           sev.sigev_notify_attributes = NULL;
           sev.sigev_value.sival_ptr = &mqdes;   /* Arg. to thread func. */
           if (mq_notify(mqdes, &sev) == -1)
               handle_error("mq_notify");

           pause();    /* Process will be terminated by thread function */
       }

SEE ALSO top

       mq_close(3), mq_getattr(3), mq_open(3), mq_receive(3), mq_send(3),
       mq_unlink(3), mq_overview(7), sigevent(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-04                        MQ_NOTIFY(3)


mq_open(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_OPEN(3)                   Linux Programmer's Manual                  MQ_OPEN(3)

NAME top

       mq_open - open a message queue

SYNOPSIS top

       #include <fcntl.h>           /* For O_* constants */
       #include <sys/stat.h>        /* For mode constants */
       #include <mqueue.h>

       mqd_t mq_open(const char *name, int oflag);
       mqd_t mq_open(const char *name, int oflag, mode_t mode,
                     struct mq_attr *attr);

       Link with -lrt.

DESCRIPTION top

       mq_open() creates a new POSIX message queue or opens an existing queue.
       The queue is identified by name.  For details of the construction of name,
       see mq_overview(7).

       The oflag argument specifies flags that control the operation of the call.
       (Definitions of the flags values can be obtained by including <fcntl.h>.)
       Exactly one of the following must be specified in oflag:

       O_RDONLY
              Open the queue to receive messages only.

       O_WRONLY
              Open the queue to send messages only.

       O_RDWR Open the queue to both send and receive messages.

       Zero or more of the following flags can additionally be ORed in oflag:

       O_NONBLOCK
              Open the queue in nonblocking mode.  In circumstances where
              mq_receive(3) and mq_send(3) would normally block, these functions
              instead fail with the error EAGAIN.

       O_CREAT
              Create the message queue if it does not exist.  The owner (user ID)
              of the message queue is set to the effective user ID of the calling
              process.  The group ownership (group ID) is set to the effective
              group ID of the calling process.

       O_EXCL If O_CREAT was specified in oflag, and a queue with the given name
              already exists, then fail with the error EEXIST.

       If O_CREAT is specified in oflag, then two additional arguments must be
       supplied.  The mode argument specifies the permissions to be placed on the
       new queue, as for open(2).  (Symbolic definitions for the permissions bits
       can be obtained by including <sys/stat.h>.)  The permissions settings are
       masked against the process umask.  The attr argument specifies attributes
       for the queue.  See mq_getattr(3) for details.  If attr is NULL, then the
       queue is created with implementation-defined default attributes.

RETURN VALUE top

       On success, mq_open() returns a message queue descriptor for use by other
       message queue functions.  On error, mq_open() returns (mqd_t) -1, with
       errno set to indicate the error.

ERRORS top

       EACCES The queue exists, but the caller does not have permission to open it
              in the specified mode.

       EACCES name contained more than one slash.

       EEXIST Both O_CREAT and O_EXCL were specified in oflag, but a queue with
              this name already exists.

       EINVAL O_CREAT was specified in oflag, and attr was not NULL, but
              attr->mq_maxmsg or attr->mq_msqsize was invalid.  Both of these
              fields must be greater than zero.  In a process that is unprivileged
              (does not have the CAP_SYS_RESOURCE capability), attr->mq_maxmsg
              must be less than or equal to the msg_max limit, and
              attr->mq_msgsize must be less than or equal to the msgsize_max
              limit.  In addition, even in a privileged process, attr->mq_maxmsg
              cannot exceed the HARD_MAX limit.  (See mq_overview(7) for details
              of these limits.)

       EMFILE The process already has the maximum number of files and message
              queues open.

       ENAMETOOLONG
              name was too long.

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

       ENOENT The O_CREAT flag was not specified in oflag, and no queue with this
              name exists.

       ENOENT name was just "/" followed by no other characters.

       ENOMEM Insufficient memory.

       ENOSPC Insufficient space for the creation of a new message queue.  This
              probably occurred because the queues_max limit was encountered; see
              mq_overview(7).

CONFORMING TO top

       POSIX.1-2001.

BUGS top

       In kernels before 2.6.14, the process umask was not applied to the
       permissions specified in mode.

SEE ALSO top

       mq_close(3), mq_getattr(3), mq_notify(3), mq_receive(3), mq_send(3),
       mq_unlink(3), mq_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-20                          MQ_OPEN(3)


mq_overview(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_OVERVIEW(7)               Linux Programmer's Manual              MQ_OVERVIEW(7)

NAME top

       mq_overview - overview of POSIX message queues

DESCRIPTION top

       POSIX message queues allow processes to exchange data in the form of
       messages.  This API is distinct from that provided by System V message
       queues (msgget(2), msgsnd(2), msgrcv(2), etc.), but provides similar
       functionality.

       Message queues are created and opened using mq_open(3); this function
       returns a message queue descriptor (mqd_t), which is used to refer to the
       open message queue in later calls.  Each message queue is identified by a
       name of the form /somename; that is, a null-terminated string of up to
       NAME_MAX (i.e., 255) characters consisting of an initial slash, followed by
       one or more characters, none of which are slashes.  Two processes can
       operate on the same queue by passing the same name to mq_open(3).

       Messages are transferred to and from a queue using mq_send(3) and
       mq_receive(3).  When a process has finished using the queue, it closes it
       using mq_close(3), and when the queue is no longer required, it can be
       deleted using mq_unlink(3).  Queue attributes can be retrieved and (in some
       cases) modified using mq_getattr(3) and mq_setattr(3).  A process can
       request asynchronous notification of the arrival of a message on a
       previously empty queue using mq_notify(3).

       A message queue descriptor is a reference to an open message queue
       description (cf.  open(2)).  After a fork(2), a child inherits copies of
       its parent's message queue descriptors, and these descriptors refer to the
       same open message queue descriptions as the corresponding descriptors in
       the parent.  Corresponding descriptors in the two processes share the flags
       (mq_flags) that are associated with the open message queue description.

       Each message has an associated priority, and messages are always delivered
       to the receiving process highest priority first.  Message priorities range
       from 0 (low) to sysconf(_SC_MQ_PRIO_MAX) - 1 (high).  On Linux,
       sysconf(_SC_MQ_PRIO_MAX) returns 32768, but POSIX.1-2001 only requires an
       implementation to support priorities in the range 0 to 31; some
       implementations only provide this range.

       The remainder of this section describes some specific details of the Linux
       implementation of POSIX message queues.

Library interfaces and system calls

       In most cases the mq_*() library interfaces listed above are implemented on
       top of underlying system calls of the same name.  Deviations from this
       scheme are indicated in the following table:

           Library interface    System call
           mq_close(3)          close(2)
           mq_getattr(3)        mq_getsetattr(2)
           mq_notify(3)         mq_notify(2)
           mq_open(3)           mq_open(2)
           mq_receive(3)        mq_timedreceive(2)
           mq_send(3)           mq_timedsend(2)
           mq_setattr(3)        mq_getsetattr(2)
           mq_timedreceive(3)   mq_timedreceive(2)
           mq_timedsend(3)      mq_timedsend(2)
           mq_unlink(3)         mq_unlink(2)

Versions

       POSIX message queues have been supported on Linux since kernel 2.6.6.
       Glibc support has been provided since version 2.3.4.

Kernel configuration

       Support for POSIX message queues is configurable via the
       CONFIG_POSIX_MQUEUE kernel configuration option.  This option is enabled by
       default.

Persistence

       POSIX message queues have kernel persistence: if not removed by
       mq_unlink(3), a message queue will exist until the system is shut down.

Linking

       Programs using the POSIX message queue API must be compiled with cc -lrt to
       link against the real-time library, librt.

/proc interfaces

       The following interfaces can be used to limit the amount of kernel memory
       consumed by POSIX message queues:

       /proc/sys/fs/mqueue/msg_max
              This file can be used to view and change the ceiling value for the
              maximum number of messages in a queue.  This value acts as a ceiling
              on the attr->mq_maxmsg argument given to mq_open(3).  The default
              value for msg_max is 10.  The minimum value is 1 (10 in kernels
              before 2.6.28).  The upper limit is HARD_MAX:
              (131072 / sizeof(void *)) (32768 on Linux/86).  This limit is
              ignored for privileged processes (CAP_SYS_RESOURCE), but the
              HARD_MAX ceiling is nevertheless imposed.

       /proc/sys/fs/mqueue/msgsize_max
              This file can be used to view and change the ceiling on the maximum
              message size.  This value acts as a ceiling on the attr->mq_msgsize
              argument given to mq_open(3).  The default value for msgsize_max is
              8192 bytes.  The minimum value is 128 (8192 in kernels before
              2.6.28).  The upper limit for msgsize_max is 1,048,576 (in kernels
              before 2.6.28, the upper limit was INT_MAX; that is, 2,147,483,647
              on Linux/86).  This limit is ignored for privileged processes
              (CAP_SYS_RESOURCE).

       /proc/sys/fs/mqueue/queues_max
              This file can be used to view and change the system-wide limit on
              the number of message queues that can be created.  Only privileged
              processes (CAP_SYS_RESOURCE) can create new message queues once this
              limit has been reached.  The default value for queues_max is 256; it
              can be changed to any value in the range 0 to INT_MAX.

Resource limit

       The RLIMIT_MSGQUEUE resource limit, which places a limit on the amount of
       space that can be consumed by all of the message queues belonging to a
       process's real user ID, is described in getrlimit(2).

Mounting the message queue file system

       On Linux, message queues are created in a virtual file system.  (Other
       implementations may also provide such a feature, but the details are likely
       to differ.)  This file system can be mounted (by the superuser) using the
       following commands:

           # mkdir /dev/mqueue
           # mount -t mqueue none /dev/mqueue

       The sticky bit is automatically enabled on the mount directory.

       After the file system has been mounted, the message queues on the system
       can be viewed and manipulated using the commands usually used for files
       (e.g., ls(1) and rm(1)).

       The contents of each file in the directory consist of a single line
       containing information about the queue:

           $ cat /dev/mqueue/mymq
           QSIZE:129     NOTIFY:2    SIGNO:0    NOTIFY_PID:8260

       These fields are as follows:

       QSIZE  Number of bytes of data in all messages in the queue.

       NOTIFY_PID
              If this is nonzero, then the process with this PID has used
              mq_notify(3) to register for asynchronous message notification, and
              the remaining fields describe how notification occurs.

       NOTIFY Notification method: 0 is SIGEV_SIGNAL; 1 is SIGEV_NONE; and 2 is
              SIGEV_THREAD.

       SIGNO  Signal number to be used for SIGEV_SIGNAL.

Polling message queue descriptors

       On Linux, a message queue descriptor is actually a file descriptor, and can
       be monitored using select(2), poll(2), or epoll(7).  This is not portable.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       System V message queues (msgget(2), msgsnd(2), msgrcv(2), etc.) are an
       older API for exchanging messages between processes.  POSIX message queues
       provide a better designed interface than System V message queues; on the
       other hand POSIX message queues are less widely available (especially on
       older systems) than System V message queues.

       Linux does not currently (2.6.26) support the use of access control lists
       (ACLs) for POSIX message queues.

EXAMPLE top

       An example of the use of various message queue functions is shown in
       mq_notify(3).

SEE ALSO top

       getrlimit(2), mq_getsetattr(2), poll(2), select(2), mq_close(3),
       mq_getattr(3), mq_notify(3), mq_open(3), mq_receive(3), mq_send(3),
       mq_unlink(3), epoll(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-09-27                      MQ_OVERVIEW(7)


mq_receive(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_RECEIVE(3)                Linux Programmer's Manual               MQ_RECEIVE(3)

NAME top

       mq_receive, mq_timedreceive - receive a message from a message queue

SYNOPSIS top

       #include <mqueue.h>

       ssize_t mq_receive(mqd_t mqdes, char *msg_ptr,
                          size_t msg_len, unsigned *msg_prio);

       #include <time.h>
       #include <mqueue.h>

       ssize_t mq_timedreceive(mqd_t mqdes, char *msg_ptr,
                          size_t msg_len, unsigned *msg_prio,
                          const struct timespec *abs_timeout);

       Link with -lrt.

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

       mq_timedreceive():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       mq_receive() removes the oldest message with the highest priority from the
       message queue referred to by the descriptor mqdes, and places it in the
       buffer pointed to by msg_ptr.  The msg_len argument specifies the size of
       the buffer pointed to by msg_ptr; this must be greater than the mq_msgsize
       attribute of the queue (see mq_getattr(3)).  If prio is not NULL, then the
       buffer to which it points is used to return the priority associated with
       the received message.

       If the queue is empty, then, by default, mq_receive() blocks until a
       message becomes available, or the call is interrupted by a signal handler.
       If the O_NONBLOCK flag is enabled for the message queue description, then
       the call instead fails immediately with the error EAGAIN.

       mq_timedreceive() behaves just like mq_receive(), except that if the queue
       is empty and the O_NONBLOCK flag is not enabled for the message queue
       description, then abs_timeout points to a structure which specifies a
       ceiling on the time for which the call will block.  This ceiling is an
       absolute timeout in seconds and nanoseconds since the Epoch, 1970-01-01
       00:00:00 +0000 (UTC), and it is specified in the following structure:

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

       If no message is available, and the timeout has already expired by the time
       of the call, mq_timedreceive() returns immediately.

RETURN VALUE top

       On success, mq_receive() and mq_timedreceive() return the number of bytes
       in the received message; on error, -1 is returned, with errno set to
       indicate the error.

ERRORS top

       EAGAIN The queue was empty, and the O_NONBLOCK flag was set for the message
              queue description referred to by mqdes.

       EBADF  The descriptor specified in mqdes was invalid.

       EINTR  The call was interrupted by a signal handler; see signal(7).

       EINVAL The call would have blocked, and abs_timeout was invalid, either
              because tv_sec was less than zero, or because tv_nsec was less than
              zero or greater than 1000 million.

       EMSGSIZE
              msg_len was less than the mq_msgsize attribute of the message queue.

       ETIMEDOUT
              The call timed out before a message could be transferred.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       On Linux, mq_timedreceive() is a system call, and mq_receive() is a library
       function layered on top of that system call.

SEE ALSO top

       mq_close(3), mq_getattr(3), mq_notify(3), mq_open(3), mq_send(3),
       mq_unlink(3), mq_overview(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                       MQ_RECEIVE(3)


mq_send(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_SEND(3)                   Linux Programmer's Manual                  MQ_SEND(3)

NAME top

       mq_send, mq_timedsend - send a message to a message queue

SYNOPSIS top

       #include <mqueue.h>

       int mq_send(mqd_t mqdes, const char *msg_ptr,
                     size_t msg_len, unsigned msg_prio);

       #include <time.h>
       #include <mqueue.h>

       int mq_timedsend(mqd_t mqdes, const char *msg_ptr,
                     size_t msg_len, unsigned msg_prio,
                     const struct timespec *abs_timeout);

       Link with -lrt.

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

       mq_timedsend():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       mq_send() adds the message pointed to by msg_ptr to the message queue
       referred to by the descriptor mqdes.  The msg_len argument specifies the
       length of the message pointed to by msg_ptr; this length must be less than
       or equal to the queue's mq_msgsize attribute.  Zero-length messages are
       allowed.

       The msg_prio argument is a nonnegative integer that specifies the priority
       of this message.  Messages are placed on the queue in decreasing order of
       priority, with newer messages of the same priority being placed after older
       messages with the same priority.

       If the message queue is already full (i.e., the number of messages on the
       queue equals the queue's mq_maxmsg attribute), then, by default, mq_send()
       blocks until sufficient space becomes available to allow the message to be
       queued, or until the call is interrupted by a signal handler.  If the
       O_NONBLOCK flag is enabled for the message queue description, then the call
       instead fails immediately with the error EAGAIN.

       mq_timedsend() behaves just like mq_send(), except that if the queue is
       full and the O_NONBLOCK flag is not enabled for the message queue
       description, then abs_timeout points to a structure which specifies a
       ceiling on the time for which the call will block.  This ceiling is an
       absolute timeout in seconds and nanoseconds since the Epoch, 1970-01-01
       00:00:00 +0000 (UTC), and it is specified in the following structure:

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

       If the message queue is full, and the timeout has already expired by the
       time of the call, mq_timedsend() returns immediately.

RETURN VALUE top

       On success, mq_send() and mq_timedsend() return zero; on error, -1 is
       returned, with errno set to indicate the error.

ERRORS top

       EAGAIN The queue was full, and the O_NONBLOCK flag was set for the message
              queue description referred to by mqdes.

       EBADF  The descriptor specified in mqdes was invalid.

       EINTR  The call was interrupted by a signal handler; see signal(7).

       EINVAL The call would have blocked, and abs_timeout was invalid, either
              because tv_sec was less than zero, or because tv_nsec was less than
              zero or greater than 1000 million.

       EMSGSIZE
              msg_len was greater than the mq_msgsize attribute of the message
              queue.

       ETIMEDOUT
              The call timed out before a message could be transferred.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       On Linux, mq_timedsend() is a system call, and mq_send() is a library
       function layered on top of that system call.

SEE ALSO top

       mq_close(3), mq_getattr(3), mq_notify(3), mq_open(3), mq_receive(3),
       mq_unlink(3), mq_overview(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                          MQ_SEND(3)


mq_unlink(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

MQ_UNLINK(3)                 Linux Programmer's Manual                MQ_UNLINK(3)

NAME top

       mq_unlink - remove a message queue

SYNOPSIS top

       #include <mqueue.h>

       int mq_unlink(const char *name);

       Link with -lrt.

DESCRIPTION top

       mq_unlink() removes the specified message queue name.  The message queue
       name is removed immediately.  The queue itself is destroyed once any other
       processes that have the queue open close their descriptors referring to the
       queue.

RETURN VALUE top

       On success mq_unlink() returns 0; on error, -1 is returned, with errno set
       to indicate the error.

ERRORS top

       EACCES The caller does not have permission to unlink this message queue.

       ENAMETOOLONG
              name was too long.

       ENOENT There is no message queue with the given name.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       mq_close(3), mq_getattr(3), mq_notify(3), mq_open(3), mq_receive(3),
       mq_send(3), mq_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-08-29                        MQ_UNLINK(3)


mremap(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MREMAP(2)                    Linux Programmer's Manual                   MREMAP(2)

NAME top

       mremap - remap a virtual memory address

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <sys/mman.h>

       void *mremap(void *old_address, size_t old_size,
                    size_t new_size, int flags, ... /* void *new_address */);

DESCRIPTION top

       mremap() expands (or shrinks) an existing memory mapping, potentially
       moving it at the same time (controlled by the flags argument and the
       available virtual address space).

       old_address is the old address of the virtual memory block that you want to
       expand (or shrink).  Note that old_address has to be page aligned.
       old_size is the old size of the virtual memory block.  new_size is the
       requested size of the virtual memory block after the resize.  An optional
       fifth argument, new_address, may be provided; see the description of
       MREMAP_FIXED below.

       In Linux the memory is divided into pages.  A user process has (one or)
       several linear virtual memory segments.  Each virtual memory segment has
       one or more mappings to real memory pages (in the page table).  Each
       virtual memory segment has its own protection (access rights), which may
       cause a segmentation violation if the memory is accessed incorrectly (e.g.,
       writing to a read-only segment).  Accessing virtual memory outside of the
       segments will also cause a segmentation violation.

       mremap() uses the Linux page table scheme.  mremap() changes the mapping
       between virtual addresses and memory pages.  This can be used to implement
       a very efficient realloc(3).

       The flags bit-mask argument may be 0, or include the following flag:

       MREMAP_MAYMOVE
              By default, if there is not sufficient space to expand a mapping at
              its current location, then mremap() fails.  If this flag is
              specified, then the kernel is permitted to relocate the mapping to a
              new virtual address, if necessary.  If the mapping is relocated,
              then absolute pointers into the old mapping location become invalid
              (offsets relative to the starting address of the mapping should be
              employed).

       MREMAP_FIXED (since Linux 2.3.31)
              This flag serves a similar purpose to the MAP_FIXED flag of mmap(2).
              If this flag is specified, then mremap() accepts a fifth argument,
              void *new_address, which specifies a page-aligned address to which
              the mapping must be moved.  Any previous mapping at the address
              range specified by new_address and new_size is unmapped.  If
              MREMAP_FIXED is specified, then MREMAP_MAYMOVE must also be
              specified.

       If the memory segment specified by old_address and old_size is locked
       (using mlock(2) or similar), then this lock is maintained when the segment
       is resized and/or relocated.  As a consequence, the amount of memory locked
       by the process may change.

RETURN VALUE top

       On success mremap() returns a pointer to the new virtual memory area.  On
       error, the value MAP_FAILED (that is, (void *) -1) is returned, and errno
       is set appropriately.

ERRORS top

       EAGAIN The caller tried to expand a memory segment that is locked, but this
              was not possible without exceeding the RLIMIT_MEMLOCK resource
              limit.

       EFAULT "Segmentation fault." Some address in the range old_address to
              old_address+old_size is an invalid virtual memory address for this
              process.  You can also get EFAULT even if there exist mappings that
              cover the whole address space requested, but those mappings are of
              different types.

       EINVAL An invalid argument was given.  Possible causes are: old_address was
              not page aligned; a value other than MREMAP_MAYMOVE or MREMAP_FIXED
              was specified in flags; new_size was zero; new_size or new_address
              was invalid; or the new address range specified by new_address and
              new_size overlapped the old address range specified by old_address
              and old_size; or MREMAP_FIXED was specified without also specifying
              MREMAP_MAYMOVE.

       ENOMEM The memory area cannot be expanded at the current virtual address,
              and the MREMAP_MAYMOVE flag is not set in flags.  Or, there is not
              enough (virtual) memory available.

CONFORMING TO top

       This call is Linux-specific, and should not be used in programs intended to
       be portable.

NOTES top

       Prior to version 2.4, glibc did not expose the definition of MREMAP_FIXED,
       and the prototype for mremap() did not allow for the new_address argument.

SEE ALSO top

       brk(2), getpagesize(2), getrlimit(2), mlock(2), mmap(2), sbrk(2),
       malloc(3), realloc(3)

       Your favorite text book on operating systems for more information on paged
       memory (e.g., Modern Operating Systems by Andrew S. Tanenbaum, Inside Linux
       by Randolf Bentson, The Design of the UNIX Operating System by Maurice J.
       Bach)

COLOPHON top

       This page is part of release 3.45 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                               2010-06-10                           MREMAP(2)


msgctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MSGCTL(2)                    Linux Programmer's Manual                   MSGCTL(2)

NAME top

       msgctl - message control operations

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/msg.h>

       int msgctl(int msqid, int cmd, struct msqid_ds *buf);

DESCRIPTION top

       msgctl() performs the control operation specified by cmd on the message
       queue with identifier msqid.

       The msqid_ds data structure is defined in <sys/msg.h> as follows:

           struct msqid_ds {
               struct ipc_perm msg_perm;     /* Ownership and permissions */
               time_t          msg_stime;    /* Time of last msgsnd(2) */
               time_t          msg_rtime;    /* Time of last msgrcv(2) */
               time_t          msg_ctime;    /* Time of last change */
               unsigned long   __msg_cbytes; /* Current number of bytes in
                                                queue (nonstandard) */
               msgqnum_t       msg_qnum;     /* Current number of messages
                                                in queue */
               msglen_t        msg_qbytes;   /* Maximum number of bytes
                                                allowed in queue */
               pid_t           msg_lspid;    /* PID of last msgsnd(2) */
               pid_t           msg_lrpid;    /* PID of last msgrcv(2) */
           };

       The ipc_perm structure is defined as follows (the highlighted fields are
       settable using IPC_SET):

           struct ipc_perm {
               key_t          __key;       /* Key supplied to msgget(2) */
               uid_t          uid;         /* Effective UID of owner */
               gid_t          gid;         /* Effective GID of owner */
               uid_t          cuid;        /* Effective UID of creator */
               gid_t          cgid;        /* Effective GID of creator */
               unsigned short mode;        /* Permissions */
               unsigned short __seq;       /* Sequence number */
           };

       Valid values for cmd are:

       IPC_STAT
              Copy information from the kernel data structure associated with
              msqid into the msqid_ds structure pointed to by buf.  The caller
              must have read permission on the message queue.

       IPC_SET
              Write the values of some members of the msqid_ds structure pointed
              to by buf to the kernel data structure associated with this message
              queue, updating also its msg_ctime member.  The following members of
              the structure are updated: msg_qbytes, msg_perm.uid, msg_perm.gid,
              and (the least significant 9 bits of) msg_perm.mode.  The effective
              UID of the calling process must match the owner (msg_perm.uid) or
              creator (msg_perm.cuid) of the message queue, or the caller must be
              privileged.  Appropriate privilege (Linux: the CAP_IPC_RESOURCE
              capability) is required to raise the msg_qbytes value beyond the
              system parameter MSGMNB.

       IPC_RMID
              Immediately remove the message queue, awakening all waiting reader
              and writer processes (with an error return and errno set to EIDRM).
              The calling process must have appropriate privileges or its
              effective user ID must be either that of the creator or owner of the
              message queue.

       IPC_INFO (Linux-specific)
              Returns information about system-wide message queue limits and
              parameters in the structure pointed to by buf.  This structure is of
              type msginfo (thus, a cast is required), defined in <sys/msg.h> if
              the _GNU_SOURCE feature test macro is defined:

                  struct msginfo {
                      int msgpool; /* Size in kibibytes of buffer pool
                                      used to hold message data;
                                      unused within kernel */
                      int msgmap;  /* Maximum number of entries in message
                                      map; unused within kernel */
                      int msgmax;  /* Maximum number of bytes that can be
                                      written in a single message */
                      int msgmnb;  /* Maximum number of bytes that can be
                                      written to queue; used to initialize
                                      msg_qbytes during queue creation
                                      (msgget(2)) */
                      int msgmni;  /* Maximum number of message queues */
                      int msgssz;  /* Message segment size;
                                      unused within kernel */
                      int msgtql;  /* Maximum number of messages on all queues
                                      in system; unused within kernel */
                      unsigned short int msgseg;
                                   /* Maximum number of segments;
                                      unused within kernel */
                  };

              The msgmni, msgmax, and msgmnb settings can be changed via /proc
              files of the same name; see proc(5) for details.

       MSG_INFO (Linux-specific)
              Returns a msginfo structure containing the same information as for
              IPC_INFO, except that the following fields are returned with
              information about system resources consumed by message queues: the
              msgpool field returns the number of message queues that currently
              exist on the system; the msgmap field returns the total number of
              messages in all queues on the system; and the msgtql field returns
              the total number of bytes in all messages in all queues on the
              system.

       MSG_STAT (Linux-specific)
              Returns a msqid_ds structure as for IPC_STAT.  However, the msqid
              argument is not a queue identifier, but instead an index into the
              kernel's internal array that maintains information about all message
              queues on the system.

RETURN VALUE top

       On success, IPC_STAT, IPC_SET, and IPC_RMID return 0.  A successful
       IPC_INFO or MSG_INFO operation returns the index of the highest used entry
       in the kernel's internal array recording information about all message
       queues.  (This information can be used with repeated MSG_STAT operations to
       obtain information about all queues on the system.)  A successful MSG_STAT
       operation returns the identifier of the queue whose index was given in
       msqid.

       On error, -1 is returned with errno indicating the error.

ERRORS top

       On failure, errno is set to one of the following:

       EACCES The argument cmd is equal to IPC_STAT or MSG_STAT, but the calling
              process does not have read permission on the message queue msqid,
              and does not have the CAP_IPC_OWNER capability.

       EFAULT The argument cmd has the value IPC_SET or IPC_STAT, but the address
              pointed to by buf isn't accessible.

       EIDRM  The message queue was removed.

       EINVAL Invalid value for cmd or msqid.  Or: for a MSG_STAT operation, the
              index value specified in msqid referred to an array slot that is
              currently unused.

       EPERM  The argument cmd has the value IPC_SET or IPC_RMID, but the
              effective user ID of the calling process is not the creator (as
              found in msg_perm.cuid) or the owner (as found in msg_perm.uid) of
              the message queue, and the process is not privileged (Linux: it does
              not have the CAP_SYS_ADMIN capability).

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       The IPC_INFO, MSG_STAT and MSG_INFO operations are used by the ipcs(1)
       program to provide information on allocated resources.  In the future these
       may modified or moved to a /proc file system interface.

       Various fields in the struct msqid_ds were typed as short under Linux 2.2
       and have become long under Linux 2.4.  To take advantage of this, a
       recompilation under glibc-2.1.91 or later should suffice.  (The kernel
       distinguishes old and new calls by an IPC_64 flag in cmd.)

SEE ALSO top

       msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                           MSGCTL(2)


msgget(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

MSGGET(2)                    Linux Programmer's Manual                   MSGGET(2)

NAME top

       msgget - get a message queue identifier

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/msg.h>

       int msgget(key_t key, int msgflg);

DESCRIPTION top

       The msgget() system call returns the message queue identifier associated
       with the value of the key argument.  A new message queue is created if key
       has the value IPC_PRIVATE or key isn't IPC_PRIVATE, no message queue with
       the given key key exists, and IPC_CREAT is specified in msgflg.

       If msgflg specifies both IPC_CREAT and IPC_EXCL and a message queue already
       exists for key, then msgget() fails with errno set to EEXIST.  (This is
       analogous to the effect of the combination O_CREAT | O_EXCL for open(2).)

       Upon creation, the least significant bits of the argument msgflg define the
       permissions of the message queue.  These permission bits have the same
       format and semantics as the permissions specified for the mode argument of
       open(2).  (The execute permissions are not used.)

       If a new message queue is created, then its associated data structure
       msqid_ds (see msgctl(2)) is initialized as follows:

              msg_perm.cuid and msg_perm.uid are set to the effective user ID of
              the calling process.

              msg_perm.cgid and msg_perm.gid are set to the effective group ID of
              the calling process.

              The least significant 9 bits of msg_perm.mode are set to the least
              significant 9 bits of msgflg.

              msg_qnum, msg_lspid, msg_lrpid, msg_stime and msg_rtime are set to
              0.

              msg_ctime is set to the current time.

              msg_qbytes is set to the system limit MSGMNB.

       If the message queue already exists the permissions are verified, and a
       check is made to see if it is marked for destruction.

RETURN VALUE top

       If successful, the return value will be the message queue identifier (a
       nonnegative integer), otherwise -1 with errno indicating the error.

ERRORS top

       On failure, errno is set to one of the following values:

       EACCES A message queue exists for key, but the calling process does not
              have permission to access the queue, and does not have the
              CAP_IPC_OWNER capability.

       EEXIST A message queue exists for key and msgflg specified both IPC_CREAT
              and IPC_EXCL.

       ENOENT No message queue exists for key and msgflg did not specify
              IPC_CREAT.

       ENOMEM A message queue has to be created but the system does not have
              enough memory for the new data structure.

       ENOSPC A message queue has to be created but the system limit for the
              maximum number of message queues (MSGMNI) would be exceeded.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       IPC_PRIVATE isn't a flag field but a key_t type.  If this special value is
       used for key, the system call ignores everything but the least significant
       9 bits of msgflg and creates a new message queue (on success).

       The following is a system limit on message queue resources affecting a
       msgget() call:

       MSGMNI System wide maximum number of message queues: policy dependent (on
              Linux, this limit can be read and modified via
              /proc/sys/kernel/msgmni).

Linux Notes

       Until version 2.3.20 Linux would return EIDRM for a msgget() on a message
       queue scheduled for deletion.

BUGS top

       The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more
       clearly show its function.

SEE ALSO top

       msgctl(2), msgrcv(2), msgsnd(2), ftok(3), capabilities(7), mq_overview(7),
       svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                           MSGGET(2)


msgop(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MSGOP(2)                     Linux Programmer's Manual                    MSGOP(2)

NAME top

       msgrcv, msgsnd - message operations

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/msg.h>

       int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);

       ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp,
                      int msgflg);

DESCRIPTION top

       The msgsnd() and msgrcv() system calls are used, respectively, to send
       messages to, and receive messages from, a message queue.  The calling
       process must have write permission on the message queue in order to send a
       message, and read permission to receive a message.

       The msgp argument is a pointer to caller-defined structure of the following
       general form:

           struct msgbuf {
               long mtype;       /* message type, must be > 0 */
               char mtext[1];    /* message data */
           };

       The mtext field is an array (or other structure) whose size is specified by
       msgsz, a nonnegative integer value.  Messages of zero length (i.e., no
       mtext field) are permitted.  The mtype field must have a strictly positive
       integer value.  This value can be used by the receiving process for message
       selection (see the description of msgrcv() below).

msgsnd()

       The msgsnd() system call appends a copy of the message pointed to by msgp
       to the message queue whose identifier is specified by msqid.

       If sufficient space is available in the queue, msgsnd() succeeds
       immediately.  (The queue capacity is defined by the msg_qbytes field in the
       associated data structure for the message queue.  During queue creation
       this field is initialized to MSGMNB bytes, but this limit can be modified
       using msgctl(2).)  If insufficient space is available in the queue, then
       the default behavior of msgsnd() is to block until space becomes available.
       If IPC_NOWAIT is specified in msgflg, then the call instead fails with the
       error EAGAIN.

       A blocked msgsnd() call may also fail if:

       * the queue is removed, in which case the system call fails with errno set
         to EIDRM; or

       * a signal is caught, in which case the system call fails with errno set to
         EINTR;see signal(7).  (msgsnd() is never automatically restarted after
         being interrupted by a signal handler, regardless of the setting of the
         SA_RESTART flag when establishing a signal handler.)

       Upon successful completion the message queue data structure is updated as
       follows:

              msg_lspid is set to the process ID of the calling process.

              msg_qnum is incremented by 1.

              msg_stime is set to the current time.

msgrcv()

       The msgrcv() system call removes a message from the queue specified by
       msqid and places it in the buffer pointed to by msgp.

       The argument msgsz specifies the maximum size in bytes for the member mtext
       of the structure pointed to by the msgp argument.  If the message text has
       length greater than msgsz, then the behavior depends on whether MSG_NOERROR
       is specified in msgflg.  If MSG_NOERROR is specified, then the message text
       will be truncated (and the truncated part will be lost); if MSG_NOERROR is
       not specified, then the message isn't removed from the queue and the system
       call fails returning -1 with errno set to E2BIG.

       The argument msgtyp specifies the type of message requested as follows:

       * If msgtyp is 0, then the first message in the queue is read.

       * If msgtyp is greater than 0, then the first message in the queue of type
         msgtyp is read, unless MSG_EXCEPT was specified in msgflg, in which case
         the first message in the queue of type not equal to msgtyp will be read.

       * If msgtyp is less than 0, then the first message in the queue with the
         lowest type less than or equal to the absolute value of msgtyp will be
         read.

       The msgflg argument is a bit mask constructed by ORing together zero or
       more of the following flags:

       IPC_NOWAIT
              Return immediately if no message of the requested type is in the
              queue.  The system call fails with errno set to ENOMSG.

       MSG_EXCEPT
              Used with msgtyp greater than 0 to read the first message in the
              queue with message type that differs from msgtyp.

       MSG_NOERROR
              To truncate the message text if longer than msgsz bytes.

       If no message of the requested type is available and IPC_NOWAIT isn't
       specified in msgflg, the calling process is blocked until one of the
       following conditions occurs:

       * A message of the desired type is placed in the queue.

       * The message queue is removed from the system.  In this case the system
         call fails with errno set to EIDRM.

       * The calling process catches a signal.  In this case the system call fails
         with errno set to EINTR.  (msgrcv() is never automatically restarted
         after being interrupted by a signal handler, regardless of the setting of
         the SA_RESTART flag when establishing a signal handler.)

       Upon successful completion the message queue data structure is updated as
       follows:

              msg_lrpid is set to the process ID of the calling process.

              msg_qnum is decremented by 1.

              msg_rtime is set to the current time.

RETURN VALUE top

       On failure both functions return -1 with errno indicating the error,
       otherwise msgsnd() returns 0 and msgrcv() returns the number of bytes
       actually copied into the mtext array.

ERRORS top

       When msgsnd() fails, errno will be set to one among the following values:

       EACCES The calling process does not have write permission on the message
              queue, and does not have the CAP_IPC_OWNER capability.

       EAGAIN The message can't be sent due to the msg_qbytes limit for the queue
              and IPC_NOWAIT was specified in msgflg.

       EFAULT The address pointed to by msgp isn't accessible.

       EIDRM  The message queue was removed.

       EINTR  Sleeping on a full message queue condition, the process caught a
              signal.

       EINVAL Invalid msqid value, or nonpositive mtype value, or invalid msgsz
              value (less than 0 or greater than the system value MSGMAX).

       ENOMEM The system does not have enough memory to make a copy of the message
              pointed to by msgp.

       When msgrcv() fails, errno will be set to one among the following values:

       E2BIG  The message text length is greater than msgsz and MSG_NOERROR isn't
              specified in msgflg.

       EACCES The calling process does not have read permission on the message
              queue, and does not have the CAP_IPC_OWNER capability.

       EAGAIN No message was available in the queue and IPC_NOWAIT was specified
              in msgflg.

       EFAULT The address pointed to by msgp isn't accessible.

       EIDRM  While the process was sleeping to receive a message, the message
              queue was removed.

       EINTR  While the process was sleeping to receive a message, the process
              caught a signal; see signal(7).

       EINVAL msgqid was invalid, or msgsz was less than 0.

       ENOMSG IPC_NOWAIT was specified in msgflg and no message of the requested
              type existed on the message queue.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       The msgp argument is declared as struct msgbuf * with libc4, libc5, glibc
       2.0, glibc 2.1.  It is declared as void * with glibc 2.2 and later, as
       required by SUSv2 and SUSv3.

       The following limits on message queue resources affect the msgsnd() call:

       MSGMAX Maximum size for a message text: 8192 bytes (on Linux, this limit
              can be read and modified via /proc/sys/kernel/msgmax).

       MSGMNB Default maximum size in bytes of a message queue: 16384 bytes (on
              Linux, this limit can be read and modified via
              /proc/sys/kernel/msgmnb).  The superuser can increase the size of a
              message queue beyond MSGMNB by a msgctl(2) system call.

       The implementation has no intrinsic limits for the system wide maximum
       number of message headers (MSGTQL) and for the system wide maximum size in
       bytes of the message pool (MSGPOOL).

SEE ALSO top

       msgctl(2), msgget(2), capabilities(7), mq_overview(7), svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                            MSGOP(2)


msr(4) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

MSR(4)                       Linux Programmer's Manual                      MSR(4)

NAME top

       msr - x86 CPU MSR access device

DESCRIPTION top

       /dev/cpu/CPUNUM/msr provides an interface to read and write the model-
       specific registers (MSRs) of an x86 CPU.  CPUNUM is the number of the CPU
       to access as listed in /proc/cpuinfo.

       The register access is done by opening the file and seeking to the MSR
       number as offset in the file, and then reading or writing in chunks of 8
       bytes.  An I/O transfer of more than 8 bytes means multiple reads or writes
       of the same register.

       This file is protected so that it can only be read and written by the user
       root, or members of the group root.

NOTES top

       The msr driver is not auto-loaded.  On modular kernels you might need to
       use the following command to load it explicitly before use:

           $ modprobe msr

SEE ALSO top

       Intel Corporation Intel 64 and IA-32 Architectures Software Developer's
       Manual Volume 3B Appendix B, for an overview of the Intel CPU MSRs.

COLOPHON top

       This page is part of release 3.45 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                               2009-03-31                              MSR(4)


msync(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | AVAILABILITY | SEE ALSO | COLOPHON The Linux Programming Interface

MSYNC(2)                     Linux Programmer's Manual                    MSYNC(2)

NAME top

       msync - synchronize a file with a memory map

SYNOPSIS top

       #include <sys/mman.h>

       int msync(void *addr, size_t length, int flags);

DESCRIPTION top

       msync() flushes changes made to the in-core copy of a file that was mapped
       into memory using mmap(2) back to disk.  Without use of this call there is
       no guarantee that changes are written back before munmap(2) is called.  To
       be more precise, the part of the file that corresponds to the memory area
       starting at addr and having length length is updated.

       The flags argument may have the bits MS_ASYNC, MS_SYNC, and MS_INVALIDATE
       set, but not both MS_ASYNC and MS_SYNC.  MS_ASYNC specifies that an update
       be scheduled, but the call returns immediately.  MS_SYNC asks for an update
       and waits for it to complete.  MS_INVALIDATE asks to invalidate other
       mappings of the same file (so that they can be updated with the fresh
       values just written).

RETURN VALUE top

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

ERRORS top

       EBUSY  MS_INVALIDATE was specified in flags, and a memory lock exists for
              the specified address range.

       EINVAL addr is not a multiple of PAGESIZE; or any bit other than MS_ASYNC |
              MS_INVALIDATE | MS_SYNC is set in flags; or both MS_SYNC and
              MS_ASYNC are set in flags.

       ENOMEM The indicated memory (or part of it) was not mapped.

CONFORMING TO top

       POSIX.1-2001.

       This call was introduced in Linux 1.3.21, and then used EFAULT instead of
       ENOMEM.  In Linux 2.4.19 this was changed to the POSIX value ENOMEM.

AVAILABILITY top

       On POSIX systems on which msync() is available, both _POSIX_MAPPED_FILES
       and _POSIX_SYNCHRONIZED_IO are defined in <unistd.h> to a value greater
       than 0.  (See also sysconf(3).)

SEE ALSO top

       mmap(2)

       B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.

COLOPHON top

       This page is part of release 3.45 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-22                            MSYNC(2)


mtrace(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

MTRACE(3)                    Linux Programmer's Manual                   MTRACE(3)

NAME top

       mtrace, muntrace - malloc tracing

SYNOPSIS top

       #include <mcheck.h>

       void mtrace(void);

       void muntrace(void);

DESCRIPTION top

       The mtrace() function installs hook functions for the memory-allocation
       functions (malloc(3), realloc(3) memalign(3), free(3)).  These hook
       functions record tracing information about memory allocation and
       deallocation.  The tracing information can be used to discover memory leaks
       and attempts to free nonallocated memory in a program.

       The muntrace() function disables the hook functions installed by mtrace(),
       so that tracing information is no longer recorded for the memory-allocation
       functions.  If no hook functions were successfully installed by mtrace(),
       muntrace() does nothing.

       When mtrace(3) is called, it checks the value of the environment variable
       MALLOC_TRACE, which should contain the pathname of a file in which the
       tracing information is to be recorded.  If the pathname is successfully
       opened, it is truncated to zero length.

       If MALLOC_TRACE is not set, or the pathname it specifies is invalid or not
       writable, then no hook functions are installed, and mtrace() has no effect.
       In set-user-ID and set-group-ID programs, MALLOC_TRACE is ignored, and
       mtrace() has no effect.

CONFORMING TO top

       These functions are GNU extensions.

NOTES top

       In normal usage, mtrace() is called once at the start of execution of a
       program, and muntrace() is never called.

       The tracing output produced after a call to mtrace() is textual, but not
       designed to be human readable.  The GNU C library provides a Perl script,
       mtrace(1), that interprets the trace log and produces human-readable
       output.  For best results, the traced program should be compiled with
       debugging enabled, so that line-number information is recorded in the
       executable.

       The tracing performed by mtrace() incurs a performance penalty (if
       MALLOC_TRACE points to a valid, writable pathname).

BUGS top

       The line-number information produced by mtrace(1) is not always precise:
       the line number references may refer to the previous or following (non-
       blank) line of the source code.

EXAMPLE top

       The shell session below demonstrates the use of the mtrace() function and
       the mtrace(1) command in a program that has memory leaks at two different
       locations.  The demonstration uses the following program:

           $ cat t_mtrace.c
           #include <mcheck.h>
           #include <stdlib.h>
           #include <stdio.h>

           int
           main(int argc, char *argv[])
           {
               int j;

               mtrace();

               for (j = 0; j < 2; j++)
                   malloc(100);            /* Never freed--a memory leak */

               calloc(16, 16);             /* Never freed--a memory leak */
               exit(EXIT_SUCCESS);
           }

       When we run the program as follows, we see that mtrace() diagnosed memory
       leaks at two different locations in the program:

           $ cc -g t_mtrace.c -o t_mtrace
           $ export MALLOC_TRACE=/tmp/t
           $ ./t_mtrace
           $ mtrace ./t_mtrace $MALLOC_TRACE
           Memory not freed:
           -----------------
              Address     Size     Caller
           0x084c9378     0x64  at /home/cecilia/t_mtrace.c:12
           0x084c93e0     0x64  at /home/cecilia/t_mtrace.c:12
           0x084c9448    0x100  at /home/cecilia/t_mtrace.c:16

       The first two messages about unfreed memory correspond to the two malloc(3)
       calls inside the for loop.  The final message corresponds to the call to
       calloc(3) (which in turn calls malloc(3)).

SEE ALSO top

       mtrace(1), malloc(3), malloc_hook(3), mcheck(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-18                           MTRACE(3)


nan(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

NAN(3)                       Linux Programmer's Manual                      NAN(3)

NAME top

       nan, nanf, nanl - return 'Not a Number'

SYNOPSIS top

       #include <math.h>

       double nan(const char *tagp);
       float nanf(const char *tagp);
       long double nanl(const char *tagp);

       Link with -lm.

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

       nan(), nanf(), nanl():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions return a representation (determined by tagp) of a quiet
       NaN.  If the implementation does not support quiet NaNs, these functions
       return zero.

       The call nan("char-sequence") is equivalent to:

           strtod("NAN(char-sequence)", NULL);

       Similarly, calls to nanf() and nanl() are equivalent to analogous calls to
       strtof(3) and strtold(3).

       The argument tagp is used in an unspecified manner.  On IEEE 754 systems,
       there are many representations of NaN, and tagp selects one.  On other
       systems it may do nothing.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.  See also IEC 559 and the appendix with recommended
       functions in IEEE 754/IEEE 854.

SEE ALSO top

       isnan(3), strtod(3), math_error(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                              NAN(3)


nanosleep(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

NANOSLEEP(2)                 Linux Programmer's Manual                NANOSLEEP(2)

NAME top

       nanosleep - high-resolution sleep

SYNOPSIS top

       #include <time.h>

       int nanosleep(const struct timespec *req, struct timespec *rem);

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

       nanosleep(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       nanosleep() suspends the execution of the calling thread until either at
       least the time specified in *req has elapsed, or the delivery of a signal
       that triggers the invocation of a handler in the calling thread or that
       terminates the process.

       If the call is interrupted by a signal handler, nanosleep() returns -1,
       sets errno to EINTR, and writes the remaining time into the structure
       pointed to by rem unless rem is NULL.  The value of *rem can then be used
       to call nanosleep() again and complete the specified pause (but see NOTES).

       The structure timespec is used to specify intervals of time with nanosecond
       precision.  It is defined as follows:

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

       The value of the nanoseconds field must be in the range 0 to 999999999.

       Compared to sleep(3) and usleep(3), nanosleep() has the following
       advantages: it provides a higher resolution for specifying the sleep
       interval; POSIX.1 explicitly specifies that it does not interact with
       signals; and it makes the task of resuming a sleep that has been
       interrupted by a signal handler easier.

RETURN VALUE top

       On successfully sleeping for the requested interval, nanosleep() returns 0.
       If the call is interrupted by a signal handler or encounters an error, then
       it returns -1, with errno set to indicate the error.

ERRORS top

       EFAULT Problem with copying information from user space.

       EINTR  The pause has been interrupted by a signal that was delivered to the
              thread.  The remaining sleep time has been written into *rem so that
              the thread can easily call nanosleep() again and continue with the
              pause.

       EINVAL The value in the tv_nsec field was not in the range 0 to 999999999
              or tv_sec was negative.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       If the interval specified in req is not an exact multiple of the
       granularity underlying clock (see time(7)), then the interval will be
       rounded up to the next multiple.  Furthermore, after the sleep completes,
       there may still be a delay before the CPU becomes free to once again
       execute the calling thread.

       The fact that nanosleep() sleeps for a relative interval can be problematic
       if the call is repeatedly restarted after being interrupted by signals,
       since the time between the interruptions and restarts of the call will lead
       to drift in the time when the sleep finally completes.  This problem can be
       avoided by using clock_nanosleep(2) with an absolute time value.

       POSIX.1 specifies that nanosleep() should measure time against the
       CLOCK_REALTIME clock.  However, Linux measures the time using the
       CLOCK_MONOTONIC clock.  This probably does not matter, since the POSIX.1
       specification for clock_settime(2) says that discontinuous changes in
       CLOCK_REALTIME should not affect nanosleep():

              Setting the value of the CLOCK_REALTIME clock via clock_settime(2)
              shall have no effect on threads that are blocked waiting for a
              relative time service based upon this clock, including the
              nanosleep() function; ...  Consequently, these time services shall
              expire when the requested relative interval elapses, independently
              of the new or old value of the clock.

Old behavior

       In order to support applications requiring much more precise pauses (e.g.,
       in order to control some time-critical hardware), nanosleep() would handle
       pauses of up to 2 ms by busy waiting with microsecond precision when called
       from a thread scheduled under a real-time policy like SCHED_FIFO or
       SCHED_RR.  This special extension was removed in kernel 2.5.39, hence is
       still present in current 2.4 kernels, but not in 2.6 kernels.

BUGS top

       In Linux 2.4, if nanosleep() is stopped by a signal (e.g., SIGTSTP), then
       the call fails with the error EINTR after the thread is resumed by a
       SIGCONT signal.  If the system call is subsequently restarted, then the
       time that the thread spent in the stopped state is not counted against the
       sleep interval.

SEE ALSO top

       clock_nanosleep(2), sched_setscheduler(2), timer_create(2), sleep(3),
       usleep(3), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-01-19                        NANOSLEEP(2)


rint(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RINT(3)                      Linux Programmer's Manual                     RINT(3)

NAME top

       nearbyint,  nearbyintf,  nearbyintl,  rint, rintf, rintl - round to nearest
       integer

SYNOPSIS top

       #include <math.h>

       double nearbyint(double x);
       float nearbyintf(float x);
       long double nearbyintl(long double x);

       double rint(double x);
       float rintf(float x);
       long double rintl(long double x);

       Link with -lm.

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

       nearbyint(), nearbyintf(), nearbyintl():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L || _ISOC99_SOURCE;
           or cc -std=c99
       rint():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       rintf(), rintl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The nearbyint() functions round their argument to an integer value in
       floating-point format, using the current rounding direction (see
       fesetround(3)) and without raising the inexact exception.

       The rint() functions do the same, but will raise the inexact exception
       (FE_INEXACT, checkable via fetestexcept(3)) when the result differs in
       value from the argument.

RETURN VALUE top

       These functions return the rounded integer value.

       If x is integral, +0, -0, NaN, or infinite, x itself is returned.

ERRORS top

       No errors occur.  POSIX.1-2001 documents a range error for overflows, but
       see NOTES.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       SUSv2 and POSIX.1-2001 contain text about overflow (which might set errno
       to ERANGE, or raise an FE_OVERFLOW exception).  In practice, the result
       cannot overflow on any current machine, so this error-handling stuff is
       just nonsense.  (More precisely, overflow can happen only when the maximum
       value of the exponent is smaller than the number of mantissa bits.  For the
       IEEE-754 standard 32-bit and 64-bit floating-point numbers the maximum
       value of the exponent is 128 (respectively, 1024), and the number of
       mantissa bits is 24 (respectively, 53).)

       If you want to store the rounded value in an integer type, you probably
       want to use one of the functions described in lrint(3) instead.

SEE ALSO top

       ceil(3), floor(3), lrint(3), round(3), trunc(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             RINT(3)


netdevice(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

NETDEVICE(7)                 Linux Programmer's Manual                NETDEVICE(7)

NAME top

       netdevice - low-level access to Linux network devices

SYNOPSIS top

       #include <sys/ioctl.h>
       #include <net/if.h>

DESCRIPTION top

       This man page describes the sockets interface which is used to configure
       network devices.

       Linux supports some standard ioctls to configure network devices.  They can
       be used on any socket's file descriptor regardless of the family or type.
       They pass an ifreq structure:

           struct ifreq {
               char ifr_name[IFNAMSIZ]; /* Interface name */
               union {
                   struct sockaddr ifr_addr;
                   struct sockaddr ifr_dstaddr;
                   struct sockaddr ifr_broadaddr;
                   struct sockaddr ifr_netmask;
                   struct sockaddr ifr_hwaddr;
                   short           ifr_flags;
                   int             ifr_ifindex;
                   int             ifr_metric;
                   int             ifr_mtu;
                   struct ifmap    ifr_map;
                   char            ifr_slave[IFNAMSIZ];
                   char            ifr_newname[IFNAMSIZ];
                   char           *ifr_data;
               };
           };

           struct ifconf {
               int                 ifc_len; /* size of buffer */
               union {
                   char           *ifc_buf; /* buffer address */
                   struct ifreq   *ifc_req; /* array of structures */
               };
           };

       Normally, the user specifies which device to affect by setting ifr_name to
       the name of the interface.  All other members of the structure may share
       memory.

Ioctls

       If an ioctl is marked as privileged then using it requires an effective
       user ID of 0 or the CAP_NET_ADMIN capability.  If this is not the case
       EPERM will be returned.

       SIOCGIFNAME
              Given the ifr_ifindex, return the name of the interface in ifr_name.
              This is the only ioctl which returns its result in ifr_name.

       SIOCGIFINDEX
              Retrieve the interface index of the interface into ifr_ifindex.

       SIOCGIFFLAGS, SIOCSIFFLAGS
              Get or set the active flag word of the device.  ifr_flags contains a
              bit mask of the following values:

                                      Device flags
              IFF_UP            Interface is running.
              IFF_BROADCAST     Valid broadcast address set.
              IFF_DEBUG         Internal debugging flag.
              IFF_LOOPBACK      Interface is a loopback interface.
              IFF_POINTOPOINT   Interface is a point-to-point link.
              IFF_RUNNING       Resources allocated.
              IFF_NOARP         No arp protocol, L2 destination address not
                                set.
              IFF_PROMISC       Interface is in promiscuous mode.
              IFF_NOTRAILERS    Avoid use of trailers.
              IFF_ALLMULTI      Receive all multicast packets.
              IFF_MASTER        Master of a load balancing bundle.
              IFF_SLAVE         Slave of a load balancing bundle.
              IFF_MULTICAST     Supports multicast
              IFF_PORTSEL       Is able to select media type via ifmap.
              IFF_AUTOMEDIA     Auto media selection active.
              IFF_DYNAMIC       The addresses are lost when the interface
                                goes down.
              IFF_LOWER_UP      Driver signals L1 up (since Linux 2.6.17)
              IFF_DORMANT       Driver signals dormant (since Linux 2.6.17)
              IFF_ECHO          Echo sent packets (since Linux 2.6.25)

              Setting the active flag word is  a  privileged  operation,  but  any
              process may read it.

       SIOCGIFPFLAGS, SIOCSIFPFLAGS
              Get  or  set  extended  (private)  flags  for the device.  ifr_flags
              contains a bit mask of the following values:

                                      Private flags
              IFF_802_1Q_VLAN      Interface is 802.1Q VLAN device.
              IFF_EBRIDGE          Interface is Ethernet bridging device.
              IFF_SLAVE_INACTIVE   Interface is inactive bonding slave.
              IFF_MASTER_8023AD    Interface is 802.3ad bonding master.
              IFF_MASTER_ALB       Interface is balanced-alb bonding master.
              IFF_BONDING          Interface is a bonding master or slave.
              IFF_SLAVE_NEEDARP    Interface needs ARPs for validation.
              IFF_ISATAP           Interface is RFC4214 ISATAP interface.

              Setting the extended  (private)  interface  flags  is  a  privileged
              operation.

       SIOCGIFADDR, SIOCSIFADDR
              Get  or  set  the address of the device using ifr_addr.  Setting the
              interface address is a  privileged  operation.   For  compatibility,
              only AF_INET addresses are accepted or returned.

       SIOCGIFDSTADDR, SIOCSIFDSTADDR
              Get  or set the destination address of a point-to-point device using
              ifr_dstaddr.  For compatibility, only AF_INET addresses are accepted
              or  returned.   Setting  the  destination  address  is  a privileged
              operation.

       SIOCGIFBRDADDR, SIOCSIFBRDADDR
              Get or set the broadcast address for  a  device  using  ifr_brdaddr.
              For  compatibility, only AF_INET addresses are accepted or returned.
              Setting the broadcast address is a privileged operation.

       SIOCGIFNETMASK, SIOCSIFNETMASK
              Get or set the network mask for a  device  using  ifr_netmask.   For
              compatibility,  only  AF_INET  addresses  are  accepted or returned.
              Setting the network mask is a privileged operation.

       SIOCGIFMETRIC, SIOCSIFMETRIC
              Get or set the metric of  the  device  using  ifr_metric.   This  is
              currently not implemented; it sets ifr_metric to 0 if you attempt to
              read it and returns EOPNOTSUPP if you attempt to set it.

       SIOCGIFMTU, SIOCSIFMTU
              Get or set the  MTU  (Maximum  Transfer  Unit)  of  a  device  using
              ifr_mtu.   Setting  the  MTU is a privileged operation.  Setting the
              MTU to too small values may cause kernel crashes.

       SIOCGIFHWADDR, SIOCSIFHWADDR
              Get or set the hardware address of a device using  ifr_hwaddr.   The
              hardware  address  is  specified  in  a  struct sockaddr.  sa_family
              contains the ARPHRD_* device type, sa_data the L2  hardware  address
              starting  from byte 0.  Setting the hardware address is a privileged
              operation.

       SIOCSIFHWBROADCAST
              Set the hardware broadcast address  of  a  device  from  ifr_hwaddr.
              This is a privileged operation.

       SIOCGIFMAP, SIOCSIFMAP
              Get  or  set  the  interface's  hardware  parameters  using ifr_map.
              Setting the parameters is a privileged operation.

                  struct ifmap {
                      unsigned long   mem_start;
                      unsigned long   mem_end;
                      unsigned short  base_addr;
                      unsigned char   irq;
                      unsigned char   dma;
                      unsigned char   port;
                  };

              The interpretation of the ifmap  structure  depends  on  the  device
              driver and the architecture.

       SIOCADDMULTI, SIOCDELMULTI
              Add  an address to or delete an address from the device's link layer
              multicast  filters   using   ifr_hwaddr.    These   are   privileged
              operations.  See also packet(7) for an alternative.

       SIOCGIFTXQLEN, SIOCSIFTXQLEN
              Get  or  set  the  transmit queue length of a device using ifr_qlen.
              Setting the transmit queue length is a privileged operation.

       SIOCSIFNAME
              Changes  the  name  of  the  interface  specified  in  ifr_name   to
              ifr_newname.   This  is  a privileged operation.  It is only allowed
              when the interface is not up.

       SIOCGIFCONF
              Return a  list  of  interface  (transport  layer)  addresses.   This
              currently  means  only  addresses  of  the AF_INET (IPv4) family for
              compatibility.  The user passes a ifconf structure  as  argument  to
              the ioctl.  It contains a pointer to an array of ifreq structures in
              ifc_req and its length in bytes in ifc_len.  The  kernel  fills  the
              ifreqs  with  all  current  L3 interface addresses that are running:
              ifr_name contains the interface name  (eth0:1  etc.),  ifr_addr  the
              address.   The kernel returns with the actual length in ifc_len.  If
              ifc_len is equal to the original  length  the  buffer  probably  has
              overflowed  and  you  should  retry  with a bigger buffer to get all
              addresses.  When no error occurs the ioctl returns 0; otherwise  -1.
              Overflow is not an error.

       Most  protocols  support  their  own  ioctls to configure protocol-specific
       interface options.  See the protocol man  pages  for  a  description.   For
       configuring IP addresses see ip(7).

       In  addition  some devices support private ioctls.  These are not described
       here.

NOTES top

       Strictly speaking, SIOCGIFCONF and the other ioctls  that  only  accept  or
       return AF_INET socket addresses, are IP specific and belong in ip(7).

       The  names  of  interfaces  with  no  addresses  or  that  don't  have  the
       IFF_RUNNING flag set can be found via /proc/net/dev.

       Local IPv6 IP addresses can be found via /proc/net or via rtnetlink(7).

BUGS top

       glibc 2.1  is  missing  the  ifr_newname  macro  in  <net/if.h>.   Add  the
       following to your program as a workaround:

           #ifndef ifr_newname
           #define ifr_newname     ifr_ifru.ifru_slave
           #endif

SEE ALSO top

       proc(5), capabilities(7), ip(7), rtnetlink(7)

COLOPHON top

       This  page  is  part  of  release  3.45  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                               2012-04-26                        NETDEVICE(7)


netlink(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

NETLINK(3)                   Linux Programmer's Manual                  NETLINK(3)

NAME top

       netlink - Netlink macros

SYNOPSIS top

       #include <asm/types.h>
       #include <linux/netlink.h>

       int NLMSG_ALIGN(size_t len);
       int NLMSG_LENGTH(size_t len);
       int NLMSG_SPACE(size_t len);
       void *NLMSG_DATA(struct nlmsghdr *nlh);
       struct nlmsghdr *NLMSG_NEXT(struct nlmsghdr *nlh, int len);
       int NLMSG_OK(struct nlmsghdr *nlh, int len);
       int NLMSG_PAYLOAD(struct nlmsghdr *nlh, int len);

DESCRIPTION top

       <linux/netlink.h> defines several standard macros to access or create a
       netlink datagram.  They are similar in spirit to the macros defined in
       cmsg(3) for auxiliary data.  The buffer passed to and from a netlink socket
       should only be accessed using these macros.

       NLMSG_ALIGN()
              Round the length of a netlink message up to align it properly.

       NLMSG_LENGTH()
              Given the payload length, len, this macro returns the aligned length
              to store in the nlmsg_len field of the nlmsghdr.

       NLMSG_SPACE()
              Return the number of bytes that a netlink message with payload of
              len would occupy.

       NLMSG_DATA()
              Return a pointer to the payload associated with the passed nlmsghdr.

       NLMSG_NEXT()
              Get the next nlmsghdr in a multipart message.  The caller must check
              if the current nlmsghdr didn't have the NLMSG_DONE set--this
              function doesn't return NULL on end.  The len argument is an lvalue
              containing the remaining length of the message buffer.  This macro
              decrements it by the length of the message header.

       NLMSG_OK()
              Return true if the netlink message is not truncated and is in a form
              suitable for parsing.

       NLMSG_PAYLOAD()
              Return the length of the payload associated with the nlmsghdr.

CONFORMING TO top

       These macros are nonstandard Linux extensions.

NOTES top

       It is often better to use netlink via libnetlink than via the low-level
       kernel interface.

SEE ALSO top

       netlink(7)

       <ftp://ftp.inr.ac.ru/ip-routing/iproute2*> for libnetlink

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-05                          NETLINK(3)


netlink(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

NETLINK(7)                   Linux Programmer's Manual                  NETLINK(7)

NAME top

       netlink - communication between kernel and user space (AF_NETLINK)

SYNOPSIS top

       #include <asm/types.h>
       #include <sys/socket.h>
       #include <linux/netlink.h>

       netlink_socket = socket(AF_NETLINK, socket_type, netlink_family);

DESCRIPTION top

       Netlink is used to transfer information between kernel and user-space
       processes.  It consists of a standard sockets-based interface for user
       space processes and an internal kernel API for kernel modules.  The
       internal kernel interface is not documented in this manual page.  There is
       also an obsolete netlink interface via netlink character devices; this
       interface is not documented here and is only provided for backward
       compatibility.

       Netlink is a datagram-oriented service.  Both SOCK_RAW and SOCK_DGRAM are
       valid values for socket_type.  However, the netlink protocol does not
       distinguish between datagram and raw sockets.

       netlink_family selects the kernel module or netlink group to communicate
       with.  The currently assigned netlink families are:

       NETLINK_ROUTE
              Receives routing and link updates and may be used to modify the
              routing tables (both IPv4 and IPv6), IP addresses, link parameters,
              neighbor setups, queueing disciplines, traffic classes and packet
              classifiers (see rtnetlink(7)).

       NETLINK_W1
              Messages from 1-wire subsystem.

       NETLINK_USERSOCK
              Reserved for user-mode socket protocols.

       NETLINK_FIREWALL
              Transport IPv4 packets from netfilter to user space.  Used by
              ip_queue kernel module.

       NETLINK_INET_DIAG
              INET socket monitoring.

       NETLINK_NFLOG
              Netfilter/iptables ULOG.

       NETLINK_XFRM
              IPsec.

       NETLINK_SELINUX
              SELinux event notifications.

       NETLINK_ISCSI
              Open-iSCSI.

       NETLINK_AUDIT
              Auditing.

       NETLINK_FIB_LOOKUP
              Access to FIB lookup from user space.

       NETLINK_CONNECTOR
              Kernel connector.  See Documentation/connector/* in the Linux kernel
              source tree for further information.

       NETLINK_NETFILTER
              Netfilter subsystem.

       NETLINK_IP6_FW
              Transport IPv6 packets from netfilter to user space.  Used by
              ip6_queue kernel module.

       NETLINK_DNRTMSG
              DECnet routing messages.

       NETLINK_KOBJECT_UEVENT
              Kernel messages to user space.

       NETLINK_GENERIC
              Generic netlink family for simplified netlink usage.

       Netlink messages consist of a byte stream with one or multiple nlmsghdr
       headers and associated payload.  The byte stream should only be accessed
       with the standard NLMSG_* macros.  See netlink(3) for further information.

       In multipart messages (multiple nlmsghdr headers with associated payload in
       one byte stream) the first and all following headers have the NLM_F_MULTI
       flag set, except for the last header which has the type NLMSG_DONE.

       After each nlmsghdr the payload follows.

           struct nlmsghdr {
               __u32 nlmsg_len;    /* Length of message including header. */
               __u16 nlmsg_type;   /* Type of message content. */
               __u16 nlmsg_flags;  /* Additional flags. */
               __u32 nlmsg_seq;    /* Sequence number. */
               __u32 nlmsg_pid;    /* Sender port ID. */
           };

       nlmsg_type can be one of the standard message types: NLMSG_NOOP message is
       to be ignored, NLMSG_ERROR message signals an error and the payload
       contains an nlmsgerr structure, NLMSG_DONE message terminates a multipart
       message.

           struct nlmsgerr {
               int error;        /* Negative errno or 0 for acknowledgements */
               struct nlmsghdr msg;  /* Message header that caused the error */
           };

       A netlink family usually specifies more message types, see the appropriate
       manual pages for that, for example, rtnetlink(7) for NETLINK_ROUTE.

       Standard flag bits in nlmsg_flags
       ----------------------------------------------------------
       NLM_F_REQUEST   Must be set on all request messages.
       NLM_F_MULTI     The message is part of a multipart
                       message terminated by NLMSG_DONE.
       NLM_F_ACK       Request for an acknowledgment on success.
       NLM_F_ECHO      Echo this request.

       Additional flag bits for GET requests
       --------------------------------------------------------------------
       NLM_F_ROOT     Return the complete table instead of a single entry.
       NLM_F_MATCH    Return all entries matching criteria passed in
                      message content.  Not implemented yet.
       NLM_F_ATOMIC   Return an atomic snapshot of the table.

       NLM_F_DUMP     Convenience macro; equivalent to
                      (NLM_F_ROOT|NLM_F_MATCH).

       Note   that  NLM_F_ATOMIC  requires  the  CAP_NET_ADMIN  capability  or  an
       effective UID of 0.

       Additional flag bits for NEW requests
       ------------------------------------------------------------
       NLM_F_REPLACE   Replace existing matching object.
       NLM_F_EXCL      Don't replace if the object already exists.
       NLM_F_CREATE    Create object if it doesn't already exist.
       NLM_F_APPEND    Add to the end of the object list.

       nlmsg_seq and nlmsg_pid are used to track messages.   nlmsg_pid  shows  the
       origin  of  the  message.  Note that there isn't a 1:1 relationship between
       nlmsg_pid and the PID of the process  if  the  message  originated  from  a
       netlink socket.  See the ADDRESS FORMATS section for further information.

       Both nlmsg_seq and nlmsg_pid are opaque to netlink core.

       Netlink is not a reliable protocol.  It tries its best to deliver a message
       to  its  destination(s),  but  may  drop  messages  when  an  out-of-memory
       condition  or  other  error  occurs.   For reliable transfer the sender can
       request an acknowledgement from the receiver by setting the NLM_F_ACK flag.
       An  acknowledgment  is an NLMSG_ERROR packet with the error field set to 0.
       The  application  must  generate  acknowledgements  for  received  messages
       itself.   The  kernel tries to send an NLMSG_ERROR message for every failed
       packet.  A user process should follow this convention too.

       However, reliable transmissions from kernel to user are impossible  in  any
       case.   The  kernel  can't  send  a netlink message if the socket buffer is
       full: the message will be dropped and the kernel and the user-space process
       will  no  longer  have  the  same  view  of  kernel state.  It is up to the
       application to detect when this happens (via the ENOBUFS error returned  by
       recvmsg(2)) and resynchronize.

Address Formats

       The  sockaddr_nl  structure  describes a netlink client in user space or in
       the kernel.  A sockaddr_nl can be either unicast (only sent to one peer) or
       sent to netlink multicast groups (nl_groups not equal 0).

           struct sockaddr_nl {
               sa_family_t     nl_family;  /* AF_NETLINK */
               unsigned short  nl_pad;     /* Zero. */
               pid_t           nl_pid;     /* Port ID. */
               __u32           nl_groups;  /* Multicast groups mask. */
           };

       nl_pid  is  the  unicast  address  of netlink socket.  It's always 0 if the
       destination is in the kernel.  For a user-space process, nl_pid is  usually
       the  PID  of  the  process  owning the destination socket.  However, nl_pid
       identifies a netlink socket, not a process.   If  a  process  owns  several
       netlink  sockets,  then  nl_pid  can only be equal to the process ID for at
       most one socket.  There are two ways to assign nl_pid to a netlink  socket.
       If the application sets nl_pid before calling bind(2), then it is up to the
       application to make sure that nl_pid is unique.  If the application sets it
       to  0,  the  kernel  takes  care  of  assigning it.  The kernel assigns the
       process ID to the first netlink socket the  process  opens  and  assigns  a
       unique  nl_pid  to  every  netlink  socket  that  the  process subsequently
       creates.

       nl_groups is a bit mask with every bit representing a netlink group number.
       Each  netlink  family  has  a  set of 32 multicast groups.  When bind(2) is
       called on the socket, the nl_groups field in the sockaddr_nl should be  set
       to  a  bit  mask  of  the groups which it wishes to listen to.  The default
       value for this field is  zero  which  means  that  no  multicasts  will  be
       received.   A  socket may multicast messages to any of the multicast groups
       by setting nl_groups to a bit mask of the groups it wishes to send to  when
       it calls sendmsg(2) or does a connect(2).  Only processes with an effective
       UID of 0 or the CAP_NET_ADMIN capability may send or listen  to  a  netlink
       multicast  group.   Any replies to a message received for a multicast group
       should be sent back to the sending PID and the multicast group.  Some Linux
       kernel subsystems may additionally allow other users to send and/or receive
       messages.  As at Linux 3.0,  the  NETLINK_KOBJECT_UEVENT,  NETLINK_GENERIC,
       NETLINK_ROUTE,  and  NETLINK_SELINUX  groups  allow  other users to receive
       messages.  No groups allow other users to send messages.

VERSIONS top

       The socket interface to netlink is a new feature of Linux 2.2.

       Linux 2.0 supported a more primitive device-based netlink interface  (which
       is  still available as a compatibility option).  This obsolete interface is
       not described here.

       NETLINK_SELINUX appeared in Linux 2.6.4.

       NETLINK_AUDIT appeared in Linux 2.6.6.

       NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10.

       NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13.

       NETLINK_INET_DIAG,  NETLINK_CONNECTOR  and  NETLINK_NETFILTER  appeared  in
       Linux 2.6.14.

       NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15.

NOTES top

       It is often better to use netlink via libnetlink or libnl than via the low-
       level kernel interface.

BUGS top

       This manual page is not complete.

EXAMPLE top

       The following example creates a NETLINK_ROUTE  netlink  socket  which  will
       listen  to the RTMGRP_LINK (network interface create/delete/up/down events)
       and RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) multicast groups.

           struct sockaddr_nl sa;

           memset(&sa, 0, sizeof(sa));
           sa.nl_family = AF_NETLINK;
           sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;

           fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
           bind(fd, (struct sockaddr *) &sa, sizeof(sa));

       The next example demonstrates how to send a netlink message to  the  kernel
       (pid  0).  Note that application must take care of message sequence numbers
       in order to reliably track acknowledgements.

           struct nlmsghdr *nh;    /* The nlmsghdr with payload to send. */
           struct sockaddr_nl sa;
           struct iovec iov = { nh, nh->nlmsg_len };
           struct msghdr msg;

           msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
           memset(&sa, 0, sizeof(sa));
           sa.nl_family = AF_NETLINK;
           nh->nlmsg_pid = 0;
           nh->nlmsg_seq = ++sequence_number;
           /* Request an ack from kernel by setting NLM_F_ACK. */
           nh->nlmsg_flags |= NLM_F_ACK;

           sendmsg(fd, &msg, 0);

       And the last example is about reading netlink message.

           int len;
           char buf[4096];
           struct iovec iov = { buf, sizeof(buf) };
           struct sockaddr_nl sa;
           struct msghdr msg;
           struct nlmsghdr *nh;

           msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
           len = recvmsg(fd, &msg, 0);

           for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
                nh = NLMSG_NEXT (nh, len)) {
               /* The end of multipart message. */
               if (nh->nlmsg_type == NLMSG_DONE)
                   return;

               if (nh->nlmsg_type == NLMSG_ERROR)
                   /* Do some error handling. */
               ...

               /* Continue with parsing payload. */
               ...
           }

SEE ALSO top

       cmsg(3), netlink(3), capabilities(7), rtnetlink(7)

       information about libnetlink <ftp://ftp.inr.ac.ru/ip-routing/iproute2*>

       information about libnl <http://people.suug.ch/~tgr/libnl/>

       RFC 3549 "Linux Netlink as an IP Services Protocol"

COLOPHON top

       This page is part of release  3.45  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                               2012-08-05                          NETLINK(7)


networks(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

NETWORKS(5)                 Linux System Administration                NETWORKS(5)

NAME top

       networks - network name information

DESCRIPTION top

       The file /etc/networks is a plain ASCII file that describes known DARPA
       networks and symbolic names for these networks.  Each line represents a
       network and has the following structure:

              name number aliases ...

       where the fields are delimited by spaces or tabs.  Empty lines are ignored.
       The hash character (#) indicates the start of a comment: this character,
       and the remaining characters up to the end of the current line, are ignored
       by library functions that process the file.

       The field descriptions are:

       name   The symbolic name for the network.  Network names can contain any
              printable characters execept white-space characters or the comment
              character.

       number The official number for this network in numbers-and-dots notation
              (see inet(3)).  The trailing ".0" (for the host component of the
              network address) may be omitted.

       aliases
              Optional aliases for the network.

       This file is read by the route(8) and netstat(8) utilities.  Only Class A,
       B or C networks are supported, partitioned networks (i.e., network/26 or
       network/28) are not supported by this facility.

FILES top

       /etc/networks
              The networks definition file.

SEE ALSO top

       getnetbyaddr(3), getnetbyname(3), getnetent(3), netstat(8), route(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU/Linux                           2008-09-04                         NETWORKS(5)


nextafter(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

NEXTAFTER(3)                 Linux Programmer's Manual                NEXTAFTER(3)

NAME top

       nextafter,  nextafterf,  nextafterl, nexttoward, nexttowardf, nexttowardl -
       floating-point number manipulation

SYNOPSIS top

       #include <math.h>

       double nextafter(double x, double y);
       float nextafterf(float x, float y);
       long double nextafterl(long double x, long double y);

       double nexttoward(double x, long double y);
       float nexttowardf(float x, long double y);
       long double nexttowardl(long double x, long double y);

       Link with -lm.

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

       nextafter():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       nextafterf(), nextafterl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99
       nexttoward(), nexttowardf(), nexttowardl():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The nextafter() functions return the next representable floating-point
       value following x in the direction of y.  If y is less than x, these
       functions will return the largest representable number less than x.

       If x equals y, the functions return y.

       The nexttoward() functions do the same as the nextafter() functions, except
       that they have a long double second argument.

RETURN VALUE top

       On success, these functions return the next representable floating-point
       value after x in the direction of y.

       If x equals y, then y (cast to the same type as x) is returned.

       If x or y is a NaN, a NaN is returned.

       If x is finite, and the result would overflow, a range error occurs, and
       the functions return HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with
       the correct mathematical sign.

       If x is not equal to y, and the correct function result would be subnormal,
       zero, or underflow, a range error occurs, and either the correct value (if
       it can be represented), or 0.0, is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result overflow
              An overflow floating-point exception (FE_OVERFLOW) is raised.

       Range error: result is subnormal or underflows
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

       These functions do not set errno.

CONFORMING TO top

       C99, POSIX.1-2001.  This function is defined in IEC 559 (and the appendix
       with recommended functions in IEEE 754/IEEE 854).

BUGS top

       In glibc version 2.5 and earlier, these functions do not raise an underflow
       floating-point (FE_UNDERFLOW) exception when an underflow occurs.

SEE ALSO top

       nearbyint(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                        NEXTAFTER(3)


nfsservctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | COLOPHON The Linux Programming Interface

NFSSERVCTL(2)                Linux Programmer's Manual               NFSSERVCTL(2)

NAME top

       nfsservctl - syscall interface to kernel nfs daemon

SYNOPSIS top

       #include <linux/nfsd/syscall.h>

       long nfsservctl(int cmd, struct nfsctl_arg *argp,
                       union nfsctl_res *resp);

DESCRIPTION top

       Note: Since Linux 3.1, this system call no longer exists.

       /*
        * These are the commands understood by nfsctl().
        */
       #define NFSCTL_SVC          0    /* This is a server process. */
       #define NFSCTL_ADDCLIENT    1    /* Add an NFS client. */
       #define NFSCTL_DELCLIENT    2    /* Remove an NFS client. */
       #define NFSCTL_EXPORT       3    /* export a file system. */
       #define NFSCTL_UNEXPORT     4    /* unexport a file system. */
       #define NFSCTL_UGIDUPDATE   5    /* update a client's UID/GID map. */
       #define NFSCTL_GETFH        6    /* get an fh (used by mountd) */

       struct nfsctl_arg {
           int                       ca_version;     /* safeguard */
           union {
               struct nfsctl_svc     u_svc;
               struct nfsctl_client  u_client;
               struct nfsctl_export  u_export;
               struct nfsctl_uidmap  u_umap;
               struct nfsctl_fhparm  u_getfh;
               unsigned int          u_debug;
           } u;
       }

       union nfsctl_res {
               struct knfs_fh          cr_getfh;
               unsigned int            cr_debug;
       };

RETURN VALUE top

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

CONFORMING TO top

       This call is Linux-specific.

COLOPHON top

       This page is part of release 3.45 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                               2012-03-05                       NFSSERVCTL(2)


nice(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

NICE(2)                      Linux Programmer's Manual                     NICE(2)

NAME top

       nice - change process priority

SYNOPSIS top

       #include <unistd.h>

       int nice(int inc);

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

       nice(): _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       nice() adds inc to the nice value for the calling process.  (A higher nice
       value means a low priority.)  Only the superuser may specify a negative
       increment, or priority increase.  The range for nice values is described in
       getpriority(2).

RETURN VALUE top

       On success, the new nice value is returned (but see NOTES below).  On
       error, -1 is returned, and errno is set appropriately.

ERRORS top

       EPERM  The calling process attempted to increase its priority by supplying
              a negative inc but has insufficient privileges.  Under Linux the
              CAP_SYS_NICE capability is required.  (But see the discussion of the
              RLIMIT_NICE resource limit in setrlimit(2).)

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  However, the Linux and (g)libc (earlier than
       glibc 2.2.4) return value is nonstandard, see below.  SVr4 documents an
       additional EINVAL error code.

NOTES top

       SUSv2 and POSIX.1-2001 specify that nice() should return the new nice
       value.  However, the Linux syscall and the nice() library function provided
       in older versions of (g)libc (earlier than glibc 2.2.4) return 0 on
       success.  The new nice value can be found using getpriority(2).

       Since glibc 2.2.4, nice() is implemented as a library function that calls
       getpriority(2) to obtain the new nice value to be returned to the caller.
       With this implementation, a successful call can legitimately return -1.  To
       reliably detect an error, set errno to 0 before the call, and check its
       value when nice() returns -1.

SEE ALSO top

       nice(1), renice(1), fork(2), getpriority(2), setpriority(2),
       capabilities(7)

COLOPHON top

       This page is part of release 3.45 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-26                             NICE(2)


nl_langinfo(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

NL_LANGINFO(3)               Linux Programmer's Manual              NL_LANGINFO(3)

NAME top

       nl_langinfo - query language and locale information

SYNOPSIS top

       #include <langinfo.h>

       char *nl_langinfo(nl_item item);

DESCRIPTION top

       The nl_langinfo() function provides access to locale information in a more
       flexible way than localeconv(3) does.  Individual and additional elements
       of the locale categories can be queried.

       Examples for the locale elements that can be specified in item using the
       constants defined in <langinfo.h> are:

       CODESET (LC_CTYPE)
              Return a string with the name of the character encoding used in the
              selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968"
              (better known as US-ASCII).  This is the same string that you get
              with "locale charmap".  For a list of character encoding names, try
              "locale -m", cf. locale(1).

       D_T_FMT (LC_TIME)
              Return a string that can be used as a format string for strftime(3)
              to represent time and date in a locale-specific way.

       D_FMT (LC_TIME)
              Return a string that can be used as a format string for strftime(3)
              to represent a date in a locale-specific way.

       T_FMT (LC_TIME)
              Return a string that can be used as a format string for strftime(3)
              to represent a time in a locale-specific way.

       DAY_{1-7} (LC_TIME)
              Return name of the n-th day of the week. [Warning: this follows the
              US convention DAY_1 = Sunday, not the international convention (ISO
              8601) that Monday is the first day of the week.]

       ABDAY_{1-7} (LC_TIME)
              Return abbreviated name of the n-th day of the week.

       MON_{1-12} (LC_TIME)
              Return name of the n-th month.

       ABMON_{1-12} (LC_TIME)
              Return abbreviated name of the n-th month.

       RADIXCHAR (LC_NUMERIC)
              Return radix character (decimal dot, decimal comma, etc.).

       THOUSEP (LC_NUMERIC)
              Return separator character for thousands (groups of three digits).

       YESEXPR (LC_MESSAGES)
              Return a regular expression that can be used with the regex(3)
              function to recognize a positive response to a yes/no question.

       NOEXPR (LC_MESSAGES)
              Return a regular expression that can be used with the regex(3)
              function to recognize a negative response to a yes/no question.

       CRNCYSTR (LC_MONETARY)
              Return the currency symbol, preceded by "-" if the symbol should
              appear before the value, "+" if the symbol should appear after the
              value, or "." if the symbol should replace the radix character.

       The above list covers just some examples of items that can be requested.
       For a more detailed list, consult The GNU C Library Reference Manual.

RETURN VALUE top

       If no locale has been selected by setlocale(3) for the appropriate
       category, nl_langinfo() returns a pointer to the corresponding string in
       the "C" locale.

       If item is not valid, a pointer to an empty string is returned.

       This pointer may point to static data that may be overwritten on the next
       call to nl_langinfo() or setlocale(3).

CONFORMING TO top

       SUSv2, POSIX.1-2001.

EXAMPLE top

       The following program sets the character type locale according to the
       environment and queries the terminal character set.

       #include <langinfo.h>
       #include <locale.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           setlocale(LC_CTYPE,"");
           printf("%s\n",nl_langinfo(CODESET));
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       locale(1), localeconv(3), setlocale(3), charsets(7), locale(7)
       The GNU C Library Reference Manual

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-03                      NL_LANGINFO(3)


nologin(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

NOLOGIN(5)                   Linux Programmer's Manual                  NOLOGIN(5)

NAME top

       nologin - prevent unprivileged users from logging into the system

DESCRIPTION top

       If the file /etc/nologin exists and is readable, login(1) will allow access
       only to root.  Other users will be shown the contents of this file and
       their logins will be refused.

FILES top

       /etc/nologin

SEE ALSO top

       login(1), shutdown(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-16                          NOLOGIN(5)


nscd(8) - Linux manual page

NAME | DESCRIPTION | OPTIONS | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

NSCD(8)                      Linux Programmer's Manual                     NSCD(8)

NAME top

       nscd - name service cache daemon

DESCRIPTION top

       Nscd is a daemon that provides a cache for the most common name service
       requests.  The default configuration file, /etc/nscd.conf, determines the
       behavior of the cache daemon.  See nscd.conf(5).

       Nscd provides caching for accesses of the passwd(5), group(5), and hosts(5)
       databases through standard libc interfaces, such as getpwnam(3),
       getpwuid(3), getgrnam(3), getgrgid(3), gethostbyname(3), and others.

       There are two caches for each database: a positive one for items found, and
       a negative one for items not found.  Each cache has a separate TTL (time-
       to-live) period for its data.  Note that the shadow file is specifically
       not cached.  getspnam(3) calls remain uncached as a result.

OPTIONS top

       --help will give you a list with all options and what they do.

NOTES top

       The daemon will try to watch for changes in configuration files appropriate
       for each database (e.g., /etc/passwd for the passwd database or /etc/hosts
       and /etc/resolv.conf for the hosts database), and flush the cache when
       these are changed.  However, this will happen only after a short delay
       (unless the inotify(7) mechanism is available and glibc 2.9 or later is
       available), and this auto-detection does not cover configuration files
       required by nonstandard NSS modules, if any are specified in
       /etc/nsswitch.conf.  In that case, you need to run the following command
       after changing the configuration file of the database so that nscd
       invalidates its cache:

           $ nscd -i [22m<database>[0m

SEE ALSO top

       nscd.conf(5), nsswitch.conf(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                             NSCD(8)


nscd.conf(5) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

NSCD.CONF(5)                 Linux Programmer's Manual                NSCD.CONF(5)

NAME top

       /etc/nscd.conf - name service cache daemon configuration file

DESCRIPTION top

       The file /etc/nscd.conf is read from nscd(8) at startup.  Each line
       specifies either an attribute and a value, or an attribute, service, and a
       value.  Fields are separated either by SPACE or TAB characters.  A '#'
       (number sign) indicates the beginning of a comment; following characters,
       up to the end of the line, are not interpreted by nscd.

       Valid services are passwd, group, or hosts.

       logfile [22mdebug-file-name[0m
              Specifies name of the file to which debug info should be written.

       debug-level [22mvalue[0m
              Sets the desired debug level.

       threads [22mnumber[0m
              This is the number of threads that are started to wait for requests.
              At least five threads will always be created.

       server-user [22muser[0m
              If this option is set, nscd will run as this user and not as root.
              If a separate cache for every user is used (-S parameter), this
              option is ignored.

       enable-cache service <yes|no>
              Enables or disables the specified service cache.

       positive-time-to-live service value
              Sets the TTL (time-to-live) for positive entries (successful
              queries) in the specified cache for service.  Value is in seconds.
              Larger values increase cache hit rates and reduce mean response
              times, but increase problems with cache coherence.

       negative-time-to-live service value
              Sets the TTL (time-to-live) for negative entries (unsuccessful
              queries) in the specified cache for service.  Value is in seconds.
              Can result in significant performance improvements if there are
              several files owned by UIDs (user IDs) not in system databases (for
              example untarring the Linux kernel sources as root); should be kept
              small to reduce cache coherency problems.

       suggested-size service value
              This is the internal hash table size, value should remain a prime
              number for optimum efficiency.

       check-files service <yes|no>
              Enables or disables checking the file belonging to the specified
              service for changes.  The files are /etc/passwd, /etc/group, and
              /etc/hosts.

       max-threads [22mthreads[0m
              Specifies the maximum number of threads to be started.

       stat-user [22musername[0m
              Specifies the user who is allowed to request statistics.

       reload-count unlimited | number
              Limit on the number of times a cached entry gets reloaded without
              being used before it gets removed.  The default is 5.

       paranoia [22m<yes|no>[0m
              Enabling paranoia mode causes nscd to restart itself periodically.

       restart-interval [22mtime[0m
              Sets the restart interval to time seconds if periodic restart is
              enabled by enabling paranoia mode.

       persistent service <yes|no>
              Keep the content of the cache for service over server restarts;
              useful when paranoia mode is set.

       shared service <yes|no>
              The memory mapping of the nscd databases for service is shared with
              the clients so that they can directly search in them instead of
              having to ask the daemon over the socket each time a lookup is
              performed.

SEE ALSO top

       nscd(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-10-01                        NSCD.CONF(5)


nsswitch.conf(5) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

NSSWITCH.CONF(5)             Linux Programmer's Manual            NSSWITCH.CONF(5)

NAME top

       nsswitch.conf - Name Service Switch configuration file

DESCRIPTION top

       The Name Service Switch (NSS) configuration file, /etc/nsswitch.conf, is
       used by the GNU C Library to determine the sources from which to obtain
       name-service information in a range of categories, and in what order.  Each
       category of information is identified by a database name.

       The file is plain ASCII text, with columns separated by spaces or tab
       characters.  The first column specifies the database name.  The remaining
       columns describe the order of sources to query and a limited set of actions
       that can be performed by lookup result.

       The following databases are understood by the GNU C Library:

       aliases     Mail aliases, used by getaliasent(3) and related functions.

       ethers      Ethernet numbers.

       group       Groups of users, used by getgrent(3) and related functions.

       hosts       Host names and numbers, used by gethostbyname(3) and related
                   functions.

       netgroup    Network-wide list of hosts and users, used for access rules.  C
                   libraries before glibc 2.1 supported netgroups only over NIS.

       networks    Network names and numbers, used by getnetent(3) and related
                   functions.

       passwd      User passwords, used by getpwent(3) and related functions.

       protocols   Network protocols, used by getprotoent(3) and related
                   functions.

       publickey   Public and secret keys for Secure_RPC used by NFS and NIS+.

       rpc         Remote procedure call names and numbers, used by
                   getrpcbyname(3) and related functions.

       services    Network services, used by getservent(3) and related functions.

       shadow      Shadow user passwords, used by getspnam(3) and related
                   functions.

       Here is an example /etc/nsswitch.conf file:

           passwd:         compat
           group:          compat
           shadow:         compat

           hosts:          dns [!UNAVAIL=return] files
           networks:       nis [NOTFOUND=return] files
           ethers:         nis [NOTFOUND=return] files
           protocols:      nis [NOTFOUND=return] files
           rpc:            nis [NOTFOUND=return] files
           services:       nis [NOTFOUND=return] files

       The first column is the database name.  The remaining columns specify:

       *  One or more service specifications e.g., "files", "db", or "nis".  The
          order of the services on the line determines the order in which those
          services will be queried, in turn, until a result is found.

       *  Optional actions to perform if a particular result is obtained from the
          preceding service, e.g., "[NOTFOUND=return]".

       The service specifications supported on your system depend on the presence
       of shared libraries, and are therefore extensible.  Libraries called
       /lib/libnss_SERVICE.so.X will provide the named SERVICE.  On a standard
       installation, you can use "files", "db", "nis", and "nisplus".  For the
       hosts database, you can additionally specify "dns".  For the passwd, group,
       and shadow databases, you can additionally specify "compat" (see
       Compatibility mode below).  The version number X may be 1 for glibc 2.0, or
       2 for glibc 2.1 and later.  On systems with additional libraries installed,
       you may have access to further services such as "hesiod", "ldap", "winbind"
       and "wins".

       An action may also be specified following a service specification.  The
       action modifies the behavior following a result obtained from the preceding
       data source.  Action items take the general form:

           [STATUS=ACTION]
           [!STATUS=ACTION]

       where

           STATUS => success | notfound | unavail | tryagain
           ACTION => return | continue

       The ! negates the test, matching all possible results except the one
       specified.  The case of the keywords is not significant.

       The STATUS value is matched against the result of the lookup function
       called by the preceding service specification, and can be one of:

           success     No error occurred and the requested entry is returned.  The
                       default action for this condition is "return".

           notfound    The lookup succeeded, but the requested entry was not
                       found.  The default action for this condition is
                       "continue".

           unavail     The service is permanently unavailable.  This can mean
                       either that the required file cannot be read, or, for
                       network services, that the server is not available or does
                       not allow queries.  The default action for this condition
                       is "continue".

           tryagain    The service is temporarily unavailable.  This could mean a
                       file is locked or a server currently cannot accept more
                       connections.  The default action for this condition is
                       "continue".

       The ACTION value can be one of:

           return      Return a result now.  Do not call any further lookup
                       functions.

           continue    Call the next lookup function.

Compatibility mode (compat)

       The NSS "compat" service is similar to "files" except that it additionally
       permits special entries in /etc/passwd for granting users or members of
       netgroups access to the system.  The following entries are valid in this
       mode:

           +user       Include the specified user from the NIS passwd map.

           +@netgroup  Include all users in the given netgroup.

           -user       Exclude the specified user from the NIS passwd map.

           -@netgroup  Exclude all users in the given netgroup.

           +           Include every user, except previously excluded ones, from
                       the NIS passwd map.

       By default the source is "nis", but this may be overridden by specifying
       "nisplus" as the source for the pseudo-databases passwd_compat,
       group_compat, and shadow_compat.

FILES top

       A service named SERVICE is implemented by a shared object library named
       libnss_SERVICE.so.X that resides in /lib.

           /etc/nsswitch.conf       NSS configuration file.
           /lib/libnss_compat.so.X  implements "compat" source.
           /lib/libnss_db.so.X      implements "db" source.
           /lib/libnss_dns.so.X     implements "dns" source.
           /lib/libnss_files.so.X   implements "files" source.
           /lib/libnss_hesiod.so.X  implements "hesiod" source.
           /lib/libnss_nis.so.X     implements "nis" source.
           /lib/libnss_nisplus.so.X implements "nisplus" source.

NOTES top

       Within each process that uses nsswitch.conf, the entire file is read only
       once.  If the file is later changed, the process will continue using the
       old configuration.

       Traditionally, there was only a single source for service information,
       often in the form of a single configuration file (e.g., /etc/passwd).
       However, as other name services, such as the Network Information Service
       (NIS) and the Domain Name Service (DNS), became popular, a method was
       needed that would be more flexible than fixed search orders coded into the
       C library.  The Name Service Switch mechanism, which was based on the
       mechanism used by Sun Microsystems in the Solaris 2 C library, introduced a
       cleaner solution to the problem.

SEE ALSO top

       getent(1), nss(5)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-14                    NSSWITCH.CONF(5)


null(4) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

NULL(4)                      Linux Programmer's Manual                     NULL(4)

NAME top

       null, zero - data sink

DESCRIPTION top

       Data written to a null or zero special file is discarded.

       Reads from the null special file always return end of file (i.e., read(2)
       returns 0), whereas reads from zero always return bytes containing zero (\0
       characters).

       null and zero are typically created by:

              mknod -m 666 /dev/null c 1 3
              mknod -m 666 /dev/zero c 1 5
              chown root:root /dev/null /dev/zero

FILES top

       /dev/null
       /dev/zero

NOTES top

       If these devices are not writable and readable for all users, many programs
       will act strangely.

SEE ALSO top

       chown(1), mknod(1), full(4)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-23                             NULL(4)


numa(7) - Linux manual page

NAME | DESCRIPTION | NOTES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

NUMA(7)                      Linux Programmer's Manual                     NUMA(7)

NAME top

       numa - overview of Non-Uniform Memory Architecture

DESCRIPTION top

       Non-Uniform Memory Access (NUMA) refers to multiprocessor systems whose
       memory is divided into multiple memory nodes.  The access time of a memory
       node depends on the relative locations of the accessing CPU and the
       accessed node.  (This contrasts with a symmetric multiprocessor system,
       where the access time for all of the memory is the same for all CPUs.)
       Normally, each CPU on a NUMA system has a local memory node whose contents
       can be accessed faster than the memory in the node local to another CPU or
       the memory on a bus shared by all CPUs.

NUMA system calls

       The Linux kernel implements the following NUMA-related system calls:
       get_mempolicy(2), mbind(2), migrate_pages(2), move_pages(2), and
       set_mempolicy(2).  However, applications should normally use the interface
       provided by libnuma; see "Library Support" below.

/proc/[number]/numa_maps (since Linux 2.6.14)

       This file displays information about a process's NUMA memory policy and
       allocation.

       Each line contains information about a memory range used by the process,
       displaying--among other information--the effective memory policy for that
       memory range and on which nodes the pages have been allocated.

       numa_maps is a read-only file.  When /proc/<pid>/numa_maps is read, the
       kernel will scan the virtual address space of the process and report how
       memory is used.  One line is displayed for each unique memory range of the
       process.

       The first field of each line shows the starting address of the memory
       range.  This field allows a correlation with the contents of the
       /proc/<pid>/maps file, which contains the end address of the range and
       other information, such as the access permissions and sharing.

       The second field shows the memory policy currently in effect for the memory
       range.  Note that the effective policy is not necessarily the policy
       installed by the process for that memory range.  Specifically, if the
       process installed a "default" policy for that range, the effective policy
       for that range will be the process policy, which may or may not be
       "default".

       The rest of the line contains information about the pages allocated in the
       memory range, as follows:

       N<node>=<nr_pages>
              The number of pages allocated on <node>.  <nr_pages> includes only
              pages currently mapped by the process.  Page migration and memory
              reclaim may have temporarily unmapped pages associated with this
              memory range.  These pages may only show up again after the process
              has attempted to reference them.  If the memory range represents a
              shared memory area or file mapping, other processes may currently
              have additional pages mapped in a corresponding memory range.

       file=<filename>
              The file backing the memory range.  If the file is mapped as
              private, write accesses may have generated COW (Copy-On-Write) pages
              in this memory range.  These pages are displayed as anonymous pages.

       heap   Memory range is used for the heap.

       stack  Memory range is used for the stack.

       huge   Huge memory range.  The page counts shown are huge pages and not
              regular sized pages.

       anon=<pages>
              The number of anonymous page in the range.

       dirty=<pages>
              Number of dirty pages.

       mapped=<pages>
              Total number of mapped pages, if different from dirty and anon
              pages.

       mapmax=<count>
              Maximum mapcount (number of processes mapping a single page)
              encountered during the scan.  This may be used as an indicator of
              the degree of sharing occurring in a given memory range.

       swapcache=<count>
              Number of pages that have an associated entry on a swap device.

       active=<pages>
              The number of pages on the active list.  This field is only shown if
              different from the number of pages in this range.  This means that
              some inactive pages exist in the memory range that may be removed
              from memory by the swapper soon.

       writeback=<pages>
              Number of pages that are currently being written out to disk.

NOTES top

       The Linux NUMA system calls and /proc interface are only available if the
       kernel was configured and built with the CONFIG_NUMA option.

Library Support

       Link with -lnuma to get the system call definitions.  libnuma and the
       required <numaif.h> header are available in the numactl package.

       However, applications should not use these system calls directly.  Instead,
       the higher level interface provided by the numa(3) functions in the numactl
       package is recommended.  The numactl package is available at
       <ftp://oss.sgi.com/www/projects/libnuma/download/>.  The package is also
       included in some Linux distributions.  Some distributions include the
       development library and header in the separate numactl-devel package.

CONFORMING TO top

       No standards govern NUMA interfaces.

SEE ALSO top

       get_mempolicy(2), mbind(2), move_pages(2), set_mempolicy(2), numa(3),
       cpuset(7), numactl(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                             NUMA(7)


offsetof(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | COLOPHON The Linux Programming Interface

OFFSETOF(3)                  Linux Programmer's Manual                 OFFSETOF(3)

NAME top

       offsetof - offset of a structure member

SYNOPSIS top

       #include <stddef.h>

       size_t offsetof(type, member);

DESCRIPTION top

       The macro offsetof() returns the offset of the field member from the start
       of the structure type.

       This macro is useful because the sizes of the fields that compose a
       structure can vary across implementations, and compilers may insert
       different numbers of padding bytes between fields.  Consequently, an
       element's offset is not necessarily given by the sum of the sizes of the
       previous elements.

       A compiler error will result if member is not aligned to a byte boundary
       (i.e., it is a bit field).

RETURN VALUE top

       offsetof() returns the offset of the given member within the given type, in
       units of bytes.

CONFORMING TO top

       C89, C99, POSIX.1-2001.

EXAMPLE top

       On a Linux/i386 system, when compiled using the default gcc(1) options, the
       program below produces the following output:

           $ ./a.out
           offsets: i=0; c=4; d=8 a=16
           sizeof(struct s)=16

Program source

       #include <stddef.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(void)
       {
           struct s {
               int i;
               char c;
               double d;
               char a[];
           };

           /* Output is compiler dependent */

           printf("offsets: i=%ld; c=%ld; d=%ld a=%ld\n",
                   (long) offsetof(struct s, i),
                   (long) offsetof(struct s, c),
                   (long) offsetof(struct s, d),
                   (long) offsetof(struct s, a));
           printf("sizeof(struct s)=%ld\n", (long) sizeof(struct s));

           exit(EXIT_SUCCESS);
       }

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-07-12                         OFFSETOF(3)


uname(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UNAME(2)                     Linux Programmer's Manual                    UNAME(2)

NAME top

       uname - get name and information about current kernel

SYNOPSIS top

       #include <sys/utsname.h>

       int uname(struct utsname *buf);

DESCRIPTION top

       uname() returns system information in the structure pointed to by buf.  The
       utsname struct is defined in <sys/utsname.h>:

           struct utsname {
               char sysname[];    /* Operating system name (e.g., "Linux") */
               char nodename[];   /* Name within "some implementation-defined
                                     network" */
               char release[];    /* Operating system release (e.g., "2.6.28") */
               char version[];    /* Operating system version */
               char machine[];    /* Hardware identifier */
           #ifdef _GNU_SOURCE
               char domainname[]; /* NIS or YP domain name */
           #endif
           };

       The length of the arrays in a struct utsname is unspecified (see NOTES);
       the fields are terminated by a null byte ('\0').

RETURN VALUE top

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

ERRORS top

       EFAULT buf is not valid.

CONFORMING TO top

       SVr4, POSIX.1-2001.  There is no uname() call in 4.3BSD.

       The domainname member (the NIS or YP domain name) is a GNU extension.

NOTES top

       This is a system call, and the operating system presumably knows its name,
       release and version.  It also knows what hardware it runs on.  So, four of
       the fields of the struct are meaningful.  On the other hand, the field
       nodename is meaningless: it gives the name of the present machine in some
       undefined network, but typically machines are in more than one network and
       have several names.  Moreover, the kernel has no way of knowing about such
       things, so it has to be told what to answer here.  The same holds for the
       additional domainname field.

       To this end Linux uses the system calls sethostname(2) and
       setdomainname(2).  Note that there is no standard that says that the
       hostname set by sethostname(2) is the same string as the nodename field of
       the struct returned by uname() (indeed, some systems allow a 256-byte
       hostname and an 8-byte nodename), but this is true on Linux.  The same
       holds for setdomainname(2) and the domainname field.

       The length of the fields in the struct varies.  Some operating systems or
       libraries use a hardcoded 9 or 33 or 65 or 257.  Other systems use SYS_NMLN
       or _SYS_NMLN or UTSLEN or _UTSNAME_LENGTH.  Clearly, it is a bad idea to
       use any of these constants; just use sizeof(...).  Often 257 is chosen in
       order to have room for an internet hostname.

       Part of the utsname information is also accessible via
       /proc/sys/kernel/{ostype, hostname, osrelease, version, domainname}.

Underlying kernel interface

       Over time, increases in the size of the utsname structure have led to three
       successive versions of uname(): sys_olduname() (slot __NR_oldolduname),
       sys_uname() (slot __NR_olduname), and sys_newuname() (slot __NR_uname).
       The first one used length 9 for all fields; the second used 65; the third
       also uses 65 but adds the domainname field.  The glibc uname() wrapper
       function hides these details from applications, invoking the most recent
       version of the system call provided by the kernel.

SEE ALSO top

       uname(1), getdomainname(2), gethostname(2)

COLOPHON top

       This page is part of release 3.45 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-03                            UNAME(2)


on_exit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ON_EXIT(3)                   Linux Programmer's Manual                  ON_EXIT(3)

NAME top

       on_exit - register a function to be called at normal process termination

SYNOPSIS top

       #include <stdlib.h>

       int on_exit(void (*function)(int , void *), void *arg);

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

       on_exit(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The on_exit() function registers the given function to be called at normal
       process termination, whether via exit(3) or via return from the program's
       main().  The function is passed the status argument given to the last call
       to exit(3) and the arg argument from on_exit().

       The same function may be registered multiple times: it is called once for
       each registration.

       When a child process is created via fork(2), it inherits copies of its
       parent's registrations.  Upon a successful call to one of the exec(3)
       functions, all registrations are removed.

RETURN VALUE top

       The on_exit() function returns the value 0 if successful; otherwise it
       returns a nonzero value.

CONFORMING TO top

       This function comes from SunOS 4, but is also present in libc4, libc5 and
       glibc.  It no longer occurs in Solaris (SunOS 5).  Avoid this function, and
       use the standard atexit(3) instead.

SEE ALSO top

       _exit(2), atexit(3), exit(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-12-05                          ON_EXIT(3)


openat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

OPENAT(2)                    Linux Programmer's Manual                   OPENAT(2)

NAME top

       openat - open a file relative to a directory file descriptor

SYNOPSIS top

       #include <fcntl.h>

       int openat(int dirfd, const char *pathname, int flags);
       int openat(int dirfd, const char *pathname, int flags, mode_t mode);

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

       openat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The openat() system call operates in exactly the same way as open(2),
       except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by open(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like open(2)).

       If pathname is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, openat() returns a new file descriptor.  On error, -1 is
       returned and errno is set to indicate the error.

ERRORS top

       The same errors that occur for open(2) can also occur for openat().  The
       following additional errors can occur for openat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       openat() was added to Linux in kernel 2.6.16; library support was added to
       glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.  A similar system call exists on Solaris.

NOTES top

       openat() and other similar system calls suffixed "at" are supported for two
       reasons.

       First, openat() allows an application to avoid race conditions that could
       occur when using open(2) to open files in directories other than the
       current working directory.  These race conditions result from the fact that
       some component of the directory prefix given to open(2) could be changed in
       parallel with the call to open(2).  Such races can be avoided by opening a
       file descriptor for the target directory, and then specifying that file
       descriptor as the dirfd argument of openat().

       Second, openat() allows the implementation of a per-thread "current working
       directory", via file descriptor(s) maintained by the application.  (This
       functionality can also be obtained by tricks based on the use of
       /proc/self/fd/dirfd, but less efficiently.)

SEE ALSO top

       faccessat(2), fchmodat(2), fchownat(2), fstatat(2), futimesat(2),
       linkat(2), mkdirat(2), mknodat(2), open(2), readlinkat(2), renameat(2),
       symlinkat(2), unlinkat(2), utimensat(2), mkfifoat(3), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                           OPENAT(2)


operator(7) - Linux manual page

NAME | DESCRIPTION | COLOPHON The Linux Programming Interface

OPERATOR(7)                  Linux Programmer's Manual                 OPERATOR(7)

NAME top

       operator - C operator precedence and order of evaluation

DESCRIPTION top

       This manual page lists C operators and their precedence in evaluation.

       Operator                             Associativity
       () [] -> .                           left to right
       ! ~ ++ -- + - (type) * & sizeof      right to left
       * / %                                left to right
       + -                                  left to right
       << >>                                left to right
       < <= > >=                            left to right
       == !=                                left to right
       &                                    left to right
       ^                                    left to right
       |                                    left to right
       &&                                   left to right
       ||                                   left to right
       ?:                                   right to left
       = += -= *= /= %= <<= >>= &= ^= |=    right to left
       ,                                    left to right

COLOPHON top

       This page is part of release 3.45 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                               2011-09-09                         OPERATOR(7)


packet(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PACKET(7)                    Linux Programmer's Manual                   PACKET(7)

NAME top

       packet - packet interface on device level.

SYNOPSIS top

       #include <sys/socket.h>
       #include <netpacket/packet.h>
       #include <net/ethernet.h> /* the L2 protocols */

       packet_socket = socket(AF_PACKET, int socket_type, int protocol);

DESCRIPTION top

       Packet sockets are used to receive or send raw packets at the device driver
       (OSI Layer 2) level.  They allow the user to implement protocol modules in
       user space on top of the physical layer.

       The socket_type is either SOCK_RAW for raw packets including the link level
       header or SOCK_DGRAM for cooked packets with the link level header removed.
       The link level header information is available in a common format in a
       sockaddr_ll.  protocol is the IEEE 802.3 protocol number in network order.
       See the <linux/if_ether.h> include file for a list of allowed protocols.
       When protocol is set to htons(ETH_P_ALL) then all protocols are received.
       All incoming packets of that protocol type will be passed to the packet
       socket before they are passed to the protocols implemented in the kernel.

       Only processes with effective UID 0 or the CAP_NET_RAW capability may open
       packet sockets.

       SOCK_RAW packets are passed to and from the device driver without any
       changes in the packet data.  When receiving a packet, the address is still
       parsed and passed in a standard sockaddr_ll address structure.  When
       transmitting a packet, the user supplied buffer should contain the physical
       layer header.  That packet is then queued unmodified to the network driver
       of the interface defined by the destination address.  Some device drivers
       always add other headers.  SOCK_RAW is similar to but not compatible with
       the obsolete AF_INET/SOCK_PACKET of Linux 2.0.

       SOCK_DGRAM operates on a slightly higher level.  The physical header is
       removed before the packet is passed to the user.  Packets sent through a
       SOCK_DGRAM packet socket get a suitable physical layer header based on the
       information in the sockaddr_ll destination address before they are queued.

       By default all packets of the specified protocol type are passed to a
       packet socket.  To only get packets from a specific interface use bind(2)
       specifying an address in a struct sockaddr_ll to bind the packet socket to
       an interface.  Only the sll_protocol and the sll_ifindex address fields are
       used for purposes of binding.

       The connect(2) operation is not supported on packet sockets.

       When the MSG_TRUNC flag is passed to recvmsg(2), recv(2), recvfrom(2) the
       real length of the packet on the wire is always returned, even when it is
       longer than the buffer.

Address Types

       The sockaddr_ll is a device independent physical layer address.

           struct sockaddr_ll {
               unsigned short sll_family;   /* Always AF_PACKET */
               unsigned short sll_protocol; /* Physical layer protocol */
               int            sll_ifindex;  /* Interface number */
               unsigned short sll_hatype;   /* ARP hardware type */
               unsigned char  sll_pkttype;  /* Packet type */
               unsigned char  sll_halen;    /* Length of address */
               unsigned char  sll_addr[8];  /* Physical layer address */
           };

       sll_protocol is the standard ethernet protocol type in network order as
       defined in the <linux/if_ether.h> include file.  It defaults to the
       socket's protocol.  sll_ifindex is the interface index of the interface
       (see netdevice(7)); 0 matches any interface (only permitted for binding).
       sll_hatype is an ARP type as defined in the <linux/if_arp.h> include file.
       sll_pkttype contains the packet type.  Valid types are PACKET_HOST for a
       packet addressed to the local host, PACKET_BROADCAST for a physical layer
       broadcast packet, PACKET_MULTICAST for a packet sent to a physical layer
       multicast address, PACKET_OTHERHOST for a packet to some other host that
       has been caught by a device driver in promiscuous mode, and PACKET_OUTGOING
       for a packet originated from the local host that is looped back to a packet
       socket.  These types make only sense for receiving.  sll_addr and sll_halen
       contain the physical layer (e.g., IEEE 802.3) address and its length.  The
       exact interpretation depends on the device.

       When you send packets it is enough to specify sll_family, sll_addr,
       sll_halen, sll_ifindex.  The other fields should be 0.  sll_hatype and
       sll_pkttype are set on received packets for your information.  For bind
       only sll_protocol and sll_ifindex are used.

Socket Options

       Packet sockets can be used to configure physical layer multicasting and
       promiscuous mode.  It works by calling setsockopt(2) on a packet socket for
       SOL_PACKET and one of the options PACKET_ADD_MEMBERSHIP to add a binding or
       PACKET_DROP_MEMBERSHIP to drop it.  They both expect a packet_mreq
       structure as argument:

           struct packet_mreq {
               int            mr_ifindex;    /* interface index */
               unsigned short mr_type;       /* action */
               unsigned short mr_alen;       /* address length */
               unsigned char  mr_address[8]; /* physical layer address */
           };

       mr_ifindex contains the interface index for the interface whose status
       should be changed.  The mr_type parameter specifies which action to
       perform.  PACKET_MR_PROMISC enables receiving all packets on a shared
       medium (often known as "promiscuous mode"), PACKET_MR_MULTICAST binds the
       socket to the physical layer multicast group specified in mr_address and
       mr_alen, and PACKET_MR_ALLMULTI sets the socket up to receive all multicast
       packets arriving at the interface.

       In addition the traditional ioctls SIOCSIFFLAGS, SIOCADDMULTI, SIOCDELMULTI
       can be used for the same purpose.

Ioctls

       SIOCGSTAMP can be used to receive the timestamp of the last received
       packet.  Argument is a struct timeval.

       In addition all standard ioctls defined in netdevice(7) and socket(7) are
       valid on packet sockets.

Error Handling

       Packet sockets do no error handling other than errors occurred while
       passing the packet to the device driver.  They don't have the concept of a
       pending error.

ERRORS top

       EADDRNOTAVAIL
              Unknown multicast group address passed.

       EFAULT User passed invalid memory address.

       EINVAL Invalid argument.

       EMSGSIZE
              Packet is bigger than interface MTU.

       ENETDOWN
              Interface is not up.

       ENOBUFS
              Not enough memory to allocate the packet.

       ENODEV Unknown device name or interface index specified in interface
              address.

       ENOENT No packet received.

       ENOTCONN
              No interface address passed.

       ENXIO  Interface address contained an invalid interface index.

       EPERM  User has insufficient privileges to carry out this operation.

              In addition other errors may be generated by the low-level driver.

VERSIONS top

       AF_PACKET is a new feature in Linux 2.2.  Earlier Linux versions supported
       only SOCK_PACKET.

       The include file <netpacket/packet.h> is present since glibc 2.1.  Older
       systems need:

           #include <asm/types.h>
           #include <linux/if_packet.h>
           #include <linux/if_ether.h>  /* The L2 protocols */

NOTES top

       For portable programs it is suggested to use AF_PACKET via pcap(3);
       although this only covers a subset of the AF_PACKET features.

       The SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE
       802.2 LLC header for a IEEE 802.3 frame.  When ETH_P_802_3 is specified as
       protocol for sending the kernel creates the 802.3 frame and fills out the
       length field; the user has to supply the LLC header to get a fully
       conforming packet.  Incoming 802.3 packets are not multiplexed on the
       DSAP/SSAP protocol fields; instead they are supplied to the user as
       protocol ETH_P_802_2 with the LLC header prepended.  It is thus not
       possible to bind to ETH_P_802_3; bind to ETH_P_802_2 instead and do the
       protocol multiplex yourself.  The default for sending is the standard
       Ethernet DIX encapsulation with the protocol filled in.

       Packet sockets are not subject to the input or output firewall chains.

Compatibility

       In Linux 2.0, the only way to get a packet socket was by calling
       socket(AF_INET, SOCK_PACKET, protocol).  This is still supported but
       strongly deprecated.  The main difference between the two methods is that
       SOCK_PACKET uses the old struct sockaddr_pkt to specify an interface, which
       doesn't provide physical layer independence.

           struct sockaddr_pkt {
               unsigned short spkt_family;
               unsigned char  spkt_device[14];
               unsigned short spkt_protocol;
           };

       spkt_family contains the device type, spkt_protocol is the IEEE 802.3
       protocol type as defined in <sys/if_ether.h> and spkt_device is the device
       name as a null-terminated string, for example, eth0.

       This structure is obsolete and should not be used in new code.

BUGS top

       glibc 2.1 does not have a define for SOL_PACKET.  The suggested workaround
       is to use:

           #ifndef SOL_PACKET
           #define SOL_PACKET 263
           #endif

       This is fixed in later glibc versions and also does not occur on libc5
       systems.

       The IEEE 802.2/803.3 LLC handling could be considered as a bug.

       Socket filters are not documented.

       The MSG_TRUNC recvmsg(2) extension is an ugly hack and should be replaced
       by a control message.  There is currently no way to get the original
       destination address of packets via SOCK_DGRAM.

SEE ALSO top

       socket(2), pcap(3), capabilities(7), ip(7), raw(7), socket(7)

       RFC 894 for the standard IP Ethernet encapsulation.  RFC 1700 for the IEEE
       802.3 IP encapsulation.

       The <linux/if_ether.h> include file for physical layer protocols.

COLOPHON top

       This page is part of release 3.45 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                               2012-05-10                           PACKET(7)


passwd(5) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PASSWD(5)                    Linux Programmer's Manual                   PASSWD(5)

NAME top

       passwd - password file

DESCRIPTION top

       The /etc/passwd file is a text file that describes user login accounts for
       the system.  It should have read permission allowed for all users (many
       utilities, like ls(1) use it to map user IDs to usernames), but write
       access only for the superuser.

       In the good old days there was no great problem with this general read
       permission.  Everybody could read the encrypted passwords, but the hardware
       was too slow to crack a well-chosen password, and moreover the basic
       assumption used to be that of a friendly user-community.  These days many
       people run some version of the shadow password suite, where /etc/passwd has
       an 'x' character in the password field, and the encrypted passwords are in
       /etc/shadow, which is readable by the superuser only.

       If the encrypted password, whether in /etc/passwd or in /etc/shadow, is an
       empty string, login is allowed without even asking for a password.  Note
       that this functionality may be intentionally disabled in applications, or
       configurable (for example using the "nullok" or "nonull" arguments to
       pam_unix.so).

       If the encrypted password in /etc/passwd is "*NP*" (without the quotes),
       the shadow record should be obtained from an NIS+ server.

       Regardless of whether shadow passwords are used, many system administrators
       use an asterisk (*) in the encrypted password field to make sure that this
       user can not authenticate him- or herself using a password.  (But see NOTES
       below.)

       If you create a new login, first put an asterisk (*) in the password field,
       then use passwd(1) to set it.

       Each line of the file describes a single user, and contains seven colon-
       separated fields:

              name:password:UID:GID:GECOS:directory:shell

       The field are as follows:

       name        This is the user's login name.  It should not contain capital
                   letters.

       password    This is either the encrypted user password, an asterisk (*), or
                   the letter 'x'.  (See pwconv(8) for an explanation of 'x'.)

       UID         The privileged root login account (superuser) has the user ID
                   0.

       GID         This is the numeric primary group ID for this user.
                   (Additional groups for the user are defined in the system group
                   file; see group(5)).

       GECOS       This field (sometimes called the "comment field") is optional
                   and used only for informational purposes.  Usually, it contains
                   the full username.  Some programs (for example, finger(1))
                   display information from this field.

                   GECOS stands for "General Electric Comprehensive Operating
                   System", which was renamed to GCOS when GE's large systems
                   division was sold to Honeywell.  Dennis Ritchie has reported:
                   "Sometimes we sent printer output or batch jobs to the GCOS
                   machine.  The gcos field in the password file was a place to
                   stash the information for the $IDENTcard.  Not elegant."

       directory   This is the user's home directory: the initial directory where
                   the user is placed after logging in.  The value in this field
                   is used to set the HOME environment variable.

       shell       This is the program to run at login (if empty, use /bin/sh).
                   If set to a nonexistent executable, the user will be unable to
                   login through login(1).  The value in this field is used to set
                   the SHELL environment variable.

FILES top

       /etc/passwd

NOTES top

       If you want to create user groups, there must be an entry in /etc/group, or
       no group will exist.

       If the encrypted password is set to an asterisk (*), the user will be
       unable to login using login(1), but may still login using rlogin(1), run
       existing processes and initiate new ones through rsh(1), cron(8), at(1), or
       mail filters, etc.  Trying to lock an account by simply changing the shell
       field yields the same result and additionally allows the use of su(1).

SEE ALSO top

       login(1), passwd(1), su(1), getpwent(3), getpwnam(3), crypt(3), group(5),
       shadow(5)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-03                           PASSWD(5)


xcrypt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

XCRYPT(3)                    Linux Programmer's Manual                   XCRYPT(3)

NAME top

       xencrypt, xdecrypt, passwd2des - RFS password encryption

SYNOPSIS top

       #include <rpc/des_crypt.h>

       void passwd2des(char *passwd, char *key);

       int xencrypt(char *secret, char *passwd);

       int xdecrypt(char *secret, char *passwd);

DESCRIPTION top

       The function passwd2des() takes a character string passwd of arbitrary
       length and fills a character array key of length 8.  The array key is
       suitable for use as DES key.  It has odd parity set in bit 0 of each byte.
       Both other functions described here use this function to turn their
       argument passwd into a DES key.

       The xencrypt() function takes the ASCII character string secret given in
       hex, which must have a length that is a multiple of 16, encrypts it using
       the DES key derived from passwd by passwd2des(), and outputs the result
       again in secret as a hex string of the same length.

       The xdecrypt() function performs the converse operation.

RETURN VALUE top

       The functions xencrypt() and xdecrypt() return 1 on success and 0 on error.

VERSIONS top

       These routines are present in libc 4.6.27 and later, and in glibc 2.1 and
       later.

BUGS top

       The prototypes are missing from the abovementioned include file.

SEE ALSO top

       cbc_crypt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2003-04-04                           XCRYPT(3)


path_resolution(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

PATH_RESOLUTION(7)           Linux Programmer's Manual          PATH_RESOLUTION(7)

NAME top

       path_resolution - how a pathname is resolved to a file

DESCRIPTION top

       Some UNIX/Linux system calls have as parameter one or more filenames.  A
       filename (or pathname) is resolved as follows.

Step 1: Start of the resolution process

       If the pathname starts with the '/' character, the starting lookup
       directory is the root directory of the calling process.  (A process
       inherits its root directory from its parent.  Usually this will be the root
       directory of the file hierarchy.  A process may get a different root
       directory by use of the chroot(2) system call.  A process may get an
       entirely private mount namespace in case it--or one of its ancestors--was
       started by an invocation of the clone(2) system call that had the
       CLONE_NEWNS flag set.)  This handles the '/' part of the pathname.

       If the pathname does not start with the '/' character, the starting lookup
       directory of the resolution process is the current working directory of the
       process.  (This is also inherited from the parent.  It can be changed by
       use of the chdir(2) system call.)

       Pathnames starting with a '/' character are called absolute pathnames.
       Pathnames not starting with a '/' are called relative pathnames.

Step 2: Walk along the path

       Set the current lookup directory to the starting lookup directory.  Now,
       for each nonfinal component of the pathname, where a component is a
       substring delimited by '/' characters, this component is looked up in the
       current lookup directory.

       If the process does not have search permission on the current lookup
       directory, an EACCES error is returned ("Permission denied").

       If the component is not found, an ENOENT error is returned ("No such file
       or directory").

       If the component is found, but is neither a directory nor a symbolic link,
       an ENOTDIR error is returned ("Not a directory").

       If the component is found and is a directory, we set the current lookup
       directory to that directory, and go to the next component.

       If the component is found and is a symbolic link (symlink), we first
       resolve this symbolic link (with the current lookup directory as starting
       lookup directory).  Upon error, that error is returned.  If the result is
       not a directory, an ENOTDIR error is returned.  If the resolution of the
       symlink is successful and returns a directory, we set the current lookup
       directory to that directory, and go to the next component.  Note that the
       resolution process here involves recursion.  In order to protect the kernel
       against stack overflow, and also to protect against denial of service,
       there are limits on the maximum recursion depth, and on the maximum number
       of symbolic links followed.  An ELOOP error is returned when the maximum is
       exceeded ("Too many levels of symbolic links").

Step 3: Find the final entry

       The lookup of the final component of the pathname goes just like that of
       all other components, as described in the previous step, with two
       differences: (i) the final component need not be a directory (at least as
       far as the path resolution process is concerned--it may have to be a
       directory, or a nondirectory, because of the requirements of the specific
       system call), and (ii) it is not necessarily an error if the component is
       not found--maybe we are just creating it.  The details on the treatment of
       the final entry are described in the manual pages of the specific system
       calls.

. and ..

       By convention, every directory has the entries "." and "..", which refer to
       the directory itself and to its parent directory, respectively.

       The path resolution process will assume that these entries have their
       conventional meanings, regardless of whether they are actually present in
       the physical file system.

       One cannot walk down past the root: "/.." is the same as "/".

Mount points

       After a "mount dev path" command, the pathname "path" refers to the root of
       the file system hierarchy on the device "dev", and no longer to whatever it
       referred to earlier.

       One can walk out of a mounted file system: "path/.." refers to the parent
       directory of "path", outside of the file system hierarchy on "dev".

Trailing slashes

       If a pathname ends in a '/', that forces resolution of the preceding
       component as in Step 2: it has to exist and resolve to a directory.
       Otherwise a trailing '/' is ignored.  (Or, equivalently, a pathname with a
       trailing '/' is equivalent to the pathname obtained by appending '.' to
       it.)

Final symlink

       If the last component of a pathname is a symbolic link, then it depends on
       the system call whether the file referred to will be the symbolic link or
       the result of path resolution on its contents.  For example, the system
       call lstat(2) will operate on the symlink, while stat(2) operates on the
       file pointed to by the symlink.

Length limit

       There is a maximum length for pathnames.  If the pathname (or some
       intermediate pathname obtained while resolving symbolic links) is too long,
       an ENAMETOOLONG error is returned ("Filename too long").

Empty pathname

       In the original UNIX, the empty pathname referred to the current directory.
       Nowadays POSIX decrees that an empty pathname must not be resolved
       successfully.  Linux returns ENOENT in this case.

Permissions

       The permission bits of a file consist of three groups of three bits, cf.
       chmod(1) and stat(2).  The first group of three is used when the effective
       user ID of the calling process equals the owner ID of the file.  The second
       group of three is used when the group ID of the file either equals the
       effective group ID of the calling process, or is one of the supplementary
       group IDs of the calling process (as set by setgroups(2)).  When neither
       holds, the third group is used.

       Of the three bits used, the first bit determines read permission, the
       second write permission, and the last execute permission in case of
       ordinary files, or search permission in case of directories.

       Linux uses the fsuid instead of the effective user ID in permission checks.
       Ordinarily the fsuid will equal the effective user ID, but the fsuid can be
       changed by the system call setfsuid(2).

       (Here "fsuid" stands for something like "file system user ID".  The concept
       was required for the implementation of a user space NFS server at a time
       when processes could send a signal to a process with the same effective
       user ID.  It is obsolete now.  Nobody should use setfsuid(2).)

       Similarly, Linux uses the fsgid ("file system group ID") instead of the
       effective group ID.  See setfsgid(2).

Bypassing permission checks: superuser and capabilities

       On a traditional UNIX system, the superuser (root, user ID 0) is all-
       powerful, and bypasses all permissions restrictions when accessing files.

       On Linux, superuser privileges are divided into capabilities (see
       capabilities(7)).  Two capabilities are relevant for file permissions
       checks: CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH.  (A process has these
       capabilities if its fsuid is 0.)

       The CAP_DAC_OVERRIDE capability overrides all permission checking, but only
       grants execute permission when at least one of the file's three execute
       permission bits is set.

       The CAP_DAC_READ_SEARCH capability grants read and search permission on
       directories, and read permission on ordinary files.

SEE ALSO top

       readlink(2), capabilities(7), credentials(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-12-05                  PATH_RESOLUTION(7)


pause(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PAUSE(2)                     Linux Programmer's Manual                    PAUSE(2)

NAME top

       pause - wait for signal

SYNOPSIS top

       #include <unistd.h>

       int pause(void);

DESCRIPTION top

       pause() causes the calling process (or thread) to sleep until a signal is
       delivered that either terminates the process or causes the invocation of a
       signal-catching function.

RETURN VALUE top

       pause() only returns when a signal was caught and the signal-catching
       function returned.  In this case pause() returns -1, and errno is set to
       EINTR.

ERRORS top

       EINTR  a signal was caught and the signal-catching function returned.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

SEE ALSO top

       kill(2), select(2), signal(2), sigsuspend(2)

COLOPHON top

       This page is part of release 3.45 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-10-06                            PAUSE(2)


pciconfig_read(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PCICONFIG_READ(2)            Linux Programmer's Manual           PCICONFIG_READ(2)

NAME top

       pciconfig_read,  pciconfig_write, pciconfig_iobase - pci device information
       handling

SYNOPSIS top

       #include <pci.h>

       int pciconfig_read(unsigned long bus, unsigned long dfn,
                 unsigned long off, unsigned long len, void *buf);
       int pciconfig_write(unsigned long bus, unsigned long dfn,
                 unsigned long off, unsigned long len, void *buf);
       int pciconfig_iobase(long which, unsigned long bus,
                 unsigned long devfn);

DESCRIPTION top

       Most of the interaction with PCI devices is already handled by the kernel
       PCI layer, and thus these calls should not normally need to be accessed
       from user space.

       pciconfig_read()
              Reads to buf from device dev at offset off value.

       pciconfig_write()
              Writes from buf to device dev at offset off value.

       pciconfig_iobase()
              You pass it a bus/devfn pair and get a physical address for either
              the memory offset (for things like prep, this is 0xc0000000), the IO
              base for PIO cycles, or the ISA holes if any.

RETURN VALUE top

       pciconfig_read()
              On success zero is returned.  On error, -1 is returned and errno is
              set appropriately.

       pciconfig_write()
              On success zero is returned.  On error, -1 is returned and errno is
              set appropriately.

       pciconfig_iobase()
              Returns information on locations of various I/O regions in physical
              memory according to the which value.  Values for which are:
              IOBASE_BRIDGE_NUMBER, IOBASE_MEMORY, IOBASE_IO, IOBASE_ISA_IO,
              IOBASE_ISA_MEM.

ERRORS top

       EINVAL len value is invalid.  This does not apply to pciconfig_iobase().

       EIO    I/O error.

       ENODEV For pciconfig_iobase(), "hose" value is NULL.  For the other calls,
              could not find a slot.

       ENOSYS The system has not implemented these calls (CONFIG_PCI not defined).

       EOPNOTSUPP
              This return value is only valid for pciconfig_iobase().  It is
              returned if the value for which is invalid.

       EPERM  User does not have the CAP_SYS_ADMIN capability.  This does not
              apply to pciconfig_iobase().

CONFORMING TO top

       These calls are Linux-specific, available since Linux 2.0.26/2.1.11.

SEE ALSO top

       capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2003-07-14                   PCICONFIG_READ(2)


popen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

POPEN(3)                     Linux Programmer's Manual                    POPEN(3)

NAME top

       popen, pclose - pipe stream to or from a process

SYNOPSIS top

       #include <stdio.h>

       FILE *popen(const char *command, const char *type);

       int pclose(FILE *stream);

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

       popen(), pclose():
           _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The popen() function opens a process by creating a pipe, forking, and
       invoking the shell.  Since a pipe is by definition unidirectional, the type
       argument may specify only reading or writing, not both; the resulting
       stream is correspondingly read-only or write-only.

       The command argument is a pointer to a null-terminated string containing a
       shell command line.  This command is passed to /bin/sh using the -c flag;
       interpretation, if any, is performed by the shell.  The type argument is a
       pointer to a null-terminated string which must contain either the letter
       'r' for reading or the letter 'w' for writing.  Since glibc 2.9, this
       argument can additionally include the letter 'e', which causes the close-
       on-exec flag (FD_CLOEXEC) to be set on the underlying file descriptor; see
       the description of the O_CLOEXEC flag in open(2) for reasons why this may
       be useful.

       The return value from popen() is a normal standard I/O stream in all
       respects save that it must be closed with pclose() rather than fclose(3).
       Writing to such a stream writes to the standard input of the command; the
       command's standard output is the same as that of the process that called
       popen(), unless this is altered by the command itself.  Conversely, reading
       from a "popened" stream reads the command's standard output, and the
       command's standard input is the same as that of the process that called
       popen().

       Note that output popen() streams are fully buffered by default.

       The pclose() function waits for the associated process to terminate and
       returns the exit status of the command as returned by wait4(2).

RETURN VALUE top

       The popen() function returns NULL if the fork(2) or pipe(2) calls fail, or
       if it cannot allocate memory.

       The pclose() function returns -1 if wait4(2) returns an error, or some
       other error is detected.

ERRORS top

       The popen() function does not set errno if memory allocation fails.  If the
       underlying fork(2) or pipe(2) fails, errno is set appropriately.  If the
       type argument is invalid, and this condition is detected, errno is set to
       EINVAL.

       If pclose() cannot obtain the child status, errno is set to ECHILD.

CONFORMING TO top

       POSIX.1-2001.

       The 'e' value for type is a Linux extension.

BUGS top

       Since the standard input of a command opened for reading shares its seek
       offset with the process that called popen(), if the original process has
       done a buffered read, the command's input position may not be as expected.
       Similarly, the output from a command opened for writing may become
       intermingled with that of the original process.  The latter can be avoided
       by calling fflush(3) before popen().

       Failure to execute the shell is indistinguishable from the shell's failure
       to execute command, or an immediate exit of the command.  The only hint is
       an exit status of 127.

SEE ALSO top

       sh(1), fork(2), pipe(2), wait4(2), fclose(3), fflush(3), fopen(3),
       stdio(3), system(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-02-03                            POPEN(3)


perror(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PERROR(3)                    Linux Programmer's Manual                   PERROR(3)

NAME top

       perror - print a system error message

SYNOPSIS top

       #include <stdio.h>

       void perror(const char *s);

       #include <errno.h>

       const char *sys_errlist[];
       int sys_nerr;
       int errno;

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

       sys_errlist, sys_nerr: _BSD_SOURCE

DESCRIPTION top

       The routine perror() produces a message on the standard error output,
       describing the last error encountered during a call to a system or library
       function.  First (if s is not NULL and *s is not a null byte ('\0')) the
       argument string s is printed, followed by a colon and a blank.  Then the
       message and a new-line.

       To be of most use, the argument string should include the name of the
       function that incurred the error.  The error number is taken from the
       external variable errno, which is set when errors occur but not cleared
       when successful calls are made.

       The global error list sys_errlist[] indexed by errno can be used to obtain
       the error message without the newline.  The largest message number provided
       in the table is sys_nerr-1.  Be careful when directly accessing this list
       because new error values may not have been added to sys_errlist[].  The use
       of sys_errlist[] is nowadays deprecated.

       When a system call fails, it usually returns -1 and sets the variable errno
       to a value describing what went wrong.  (These values can be found in
       <errno.h>.)  Many library functions do likewise.  The function perror()
       serves to translate this error code into human-readable form.  Note that
       errno is undefined after a successful library call: this call may well
       change this variable, even though it succeeds, for example because it
       internally used some other library function that failed.  Thus, if a
       failing call is not immediately followed by a call to perror(), the value
       of errno should be saved.

CONFORMING TO top

       The function perror() and the external errno (see errno(3)) conform to C89,
       C99, 4.3BSD, POSIX.1-2001.  The externals sys_nerr and sys_errlist conform
       to BSD.

NOTES top

       The externals sys_nerr and sys_errlist are defined by glibc, but in
       <stdio.h>.

SEE ALSO top

       err(3), errno(3), error(3), strerror(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-17                           PERROR(3)


personality(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | COLOPHON The Linux Programming Interface

PERSONALITY(2)               Linux Programmer's Manual              PERSONALITY(2)

NAME top

       personality - set the process execution domain

SYNOPSIS top

       #include <sys/personality.h>

       int personality(unsigned long persona);

DESCRIPTION top

       Linux supports different execution domains, or personalities, for each
       process.  Among other things, execution domains tell Linux how to map
       signal numbers into signal actions.  The execution domain system allows
       Linux to provide limited support for binaries compiled under other UNIX-
       like operating systems.

       This function will return the current personality() when persona equals
       0xffffffff.  Otherwise, it will make the execution domain referenced by
       persona the new execution domain of the calling process.

RETURN VALUE top

       On success, the previous persona is returned.  On error, -1 is returned,
       and errno is set appropriately.

ERRORS top

       EINVAL The kernel was unable to change the personality.

CONFORMING TO top

       personality() is Linux-specific and should not be used in programs intended
       to be portable.

COLOPHON top

       This page is part of release 3.45 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                               2003-01-01                      PERSONALITY(2)


pipe(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PIPE(2)                      Linux Programmer's Manual                     PIPE(2)

NAME top

       pipe, pipe2 - create pipe

SYNOPSIS top

       #include <unistd.h>

       int pipe(int pipefd[2]);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <fcntl.h>              /* Obtain O_* constant definitions */
       #include <unistd.h>

       int pipe2(int pipefd[2], int flags);

DESCRIPTION top

       pipe() creates a pipe, a unidirectional data channel that can be used for
       interprocess communication.  The array pipefd is used to return two file
       descriptors referring to the ends of the pipe.  pipefd[0] refers to the
       read end of the pipe.  pipefd[1] refers to the write end of the pipe.  Data
       written to the write end of the pipe is buffered by the kernel until it is
       read from the read end of the pipe.  For further details, see pipe(7).

       If flags is 0, then pipe2() is the same as pipe().  The following values
       can be bitwise ORed in flags to obtain different behavior:

       O_NONBLOCK  Set the O_NONBLOCK file status flag on the two new open file
                   descriptions.  Using this flag saves extra calls to fcntl(2) to
                   achieve the same result.

       O_CLOEXEC   Set the close-on-exec (FD_CLOEXEC) flag on the two new file
                   descriptors.  See the description of the same flag in open(2)
                   for reasons why this may be useful.

RETURN VALUE top

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

ERRORS top

       EFAULT pipefd is not valid.

       EINVAL (pipe2()) Invalid value in flags.

       EMFILE Too many file descriptors are in use by the process.

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

VERSIONS top

       pipe2() was added to Linux in version 2.6.27; glibc support is available
       starting with version 2.9.

CONFORMING TO top

       pipe(): POSIX.1-2001.

       pipe2() is Linux-specific.

EXAMPLE top

       The following program creates a pipe, and then fork(2)s to create a child
       process; the child inherits a duplicate set of file descriptors that refer
       to the same pipe.  After the fork(2), each process closes the descriptors
       that it doesn't need for the pipe (see pipe(7)).  The parent then writes
       the string contained in the program's command-line argument to the pipe,
       and the child reads this string a byte at a time from the pipe and echoes
       it on standard output.

       #include <sys/wait.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           int pipefd[2];
           pid_t cpid;
           char buf;

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

           if (pipe(pipefd) == -1) {
               perror("pipe");
               exit(EXIT_FAILURE);
           }

           cpid = fork();
           if (cpid == -1) {
               perror("fork");
               exit(EXIT_FAILURE);
           }

           if (cpid == 0) {    /* Child reads from pipe */
               close(pipefd[1]);          /* Close unused write end */

               while (read(pipefd[0], &buf, 1) > 0)
                   write(STDOUT_FILENO, &buf, 1);

               write(STDOUT_FILENO, "\n", 1);
               close(pipefd[0]);
               _exit(EXIT_SUCCESS);

           } else {            /* Parent writes argv[1] to pipe */
               close(pipefd[0]);          /* Close unused read end */
               write(pipefd[1], argv[1], strlen(argv[1]));
               close(pipefd[1]);          /* Reader will see EOF */
               wait(NULL);                /* Wait for child */
               exit(EXIT_SUCCESS);
           }
       }

SEE ALSO top

       fork(2), read(2), socketpair(2), write(2), popen(3), pipe(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-02-14                             PIPE(2)


pipe(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

PIPE(7)                      Linux Programmer's Manual                     PIPE(7)

NAME top

       pipe - overview of pipes and FIFOs

DESCRIPTION top

       Pipes and FIFOs (also known as named pipes) provide a unidirectional
       interprocess communication channel.  A pipe has a read end and a write end.
       Data written to the write end of a pipe can be read from the read end of
       the pipe.

       A pipe is created using pipe(2), which creates a new pipe and returns two
       file descriptors, one referring to the read end of the pipe, the other
       referring to the write end.  Pipes can be used to create a communication
       channel between related processes; see pipe(2) for an example.

       A FIFO (short for First In First Out) has a name within the file system
       (created using mkfifo(3)), and is opened using open(2).  Any process may
       open a FIFO, assuming the file permissions allow it.  The read end is
       opened using the O_RDONLY flag; the write end is opened using the O_WRONLY
       flag.  See fifo(7) for further details.  Note: although FIFOs have a
       pathname in the file system, I/O on FIFOs does not involve operations on
       the underlying device (if there is one).

I/O on Pipes and FIFOs

       The only difference between pipes and FIFOs is the manner in which they are
       created and opened.  Once these tasks have been accomplished, I/O on pipes
       and FIFOs has exactly the same semantics.

       If a process attempts to read from an empty pipe, then read(2) will block
       until data is available.  If a process attempts to write to a full pipe
       (see below), then write(2) blocks until sufficient data has been read from
       the pipe to allow the write to complete.  Nonblocking I/O is possible by
       using the fcntl(2) F_SETFL operation to enable the O_NONBLOCK open file
       status flag.

       The communication channel provided by a pipe is a byte stream: there is no
       concept of message boundaries.

       If all file descriptors referring to the write end of a pipe have been
       closed, then an attempt to read(2) from the pipe will see end-of-file
       (read(2) will return 0).  If all file descriptors referring to the read end
       of a pipe have been closed, then a write(2) will cause a SIGPIPE signal to
       be generated for the calling process.  If the calling process is ignoring
       this signal, then write(2) fails with the error EPIPE.  An application that
       uses pipe(2) and fork(2) should use suitable close(2) calls to close
       unnecessary duplicate file descriptors; this ensures that end-of-file and
       SIGPIPE/EPIPE are delivered when appropriate.

       It is not possible to apply lseek(2) to a pipe.

Pipe Capacity

       A pipe has a limited capacity.  If the pipe is full, then a write(2) will
       block or fail, depending on whether the O_NONBLOCK flag is set (see below).
       Different implementations have different limits for the pipe capacity.
       Applications should not rely on a particular capacity: an application
       should be designed so that a reading process consumes data as soon as it is
       available, so that a writing process does not remain blocked.

       In Linux versions before 2.6.11, the capacity of a pipe was the same as the
       system page size (e.g., 4096 bytes on i386).  Since Linux 2.6.11, the pipe
       capacity is 65536 bytes.

PIPE_BUF

       POSIX.1-2001 says that write(2)s of less than PIPE_BUF bytes must be
       atomic: the output data is written to the pipe as a contiguous sequence.
       Writes of more than PIPE_BUF bytes may be nonatomic: the kernel may
       interleave the data with data written by other processes.  POSIX.1-2001
       requires PIPE_BUF to be at least 512 bytes.  (On Linux, PIPE_BUF is 4096
       bytes.)  The precise semantics depend on whether the file descriptor is
       nonblocking (O_NONBLOCK), whether there are multiple writers to the pipe,
       and on n, the number of bytes to be written:

       O_NONBLOCK disabled, n <= PIPE_BUF
              All n bytes are written atomically; write(2) may block if there is
              not room for n bytes to be written immediately

       O_NONBLOCK enabled, n <= PIPE_BUF
              If there is room to write n bytes to the pipe, then write(2)
              succeeds immediately, writing all n bytes; otherwise write(2) fails,
              with errno set to EAGAIN.

       O_NONBLOCK disabled, n > PIPE_BUF
              The write is nonatomic: the data given to write(2) may be
              interleaved with write(2)s by other process; the write(2) blocks
              until n bytes have been written.

       O_NONBLOCK enabled, n > PIPE_BUF
              If the pipe is full, then write(2) fails, with errno set to EAGAIN.
              Otherwise, from 1 to n bytes may be written (i.e., a "partial write"
              may occur; the caller should check the return value from write(2) to
              see how many bytes were actually written), and these bytes may be
              interleaved with writes by other processes.

Open File Status Flags

       The only open file status flags that can be meaningfully applied to a pipe
       or FIFO are O_NONBLOCK and O_ASYNC.

       Setting the O_ASYNC flag for the read end of a pipe causes a signal (SIGIO
       by default) to be generated when new input becomes available on the pipe
       (see fcntl(2) for details).  On Linux, O_ASYNC is supported for pipes and
       FIFOs only since kernel 2.6.

Portability notes

       On some systems (but not Linux), pipes are bidirectional: data can be
       transmitted in both directions between the pipe ends.  According to
       POSIX.1-2001, pipes only need to be unidirectional.  Portable applications
       should avoid reliance on bidirectional pipe semantics.

SEE ALSO top

       dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socketpair(2),
       stat(2), mkfifo(3), epoll(7), fifo(7)

COLOPHON top

       This page is part of release 3.45 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                               2005-12-08                             PIPE(7)


pivot_root(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PIVOT_ROOT(2)                Linux Programmer's Manual               PIVOT_ROOT(2)

NAME top

       pivot_root - change the root file system

SYNOPSIS top

       int pivot_root(const char *new_root, const char *put_old);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       pivot_root() moves the root file system of the calling process to the
       directory put_old and makes new_root the new root file system of the
       calling process.

       The typical use of pivot_root() is during system startup, when the system
       mounts a temporary root file system (e.g., an initrd), then mounts the real
       root file system, and eventually turns the latter into the current root of
       all relevant processes or threads.

       pivot_root() may or may not change the current root and the current working
       directory of any processes or threads which use the old root directory.
       The caller of pivot_root() must ensure that processes with root or current
       working directory at the old root operate correctly in either case.  An
       easy way to ensure this is to change their root and current working
       directory to new_root before invoking pivot_root().

       The paragraph above is intentionally vague because the implementation of
       pivot_root() may change in the future.  At the time of writing,
       pivot_root() changes root and current working directory of each process or
       thread to new_root if they point to the old root directory.  This is
       necessary in order to prevent kernel threads from keeping the old root
       directory busy with their root and current working directory, even if they
       never access the file system in any way.  In the future, there may be a
       mechanism for kernel threads to explicitly relinquish any access to the
       file system, such that this fairly intrusive mechanism can be removed from
       pivot_root().

       Note that this also applies to the calling process: pivot_root() may or may
       not affect its current working directory.  It is therefore recommended to
       call chdir("/") immediately after pivot_root().

       The following restrictions apply to new_root and put_old:

       -  They must be directories.

       -  new_root and put_old must not be on the same file system as the current
          root.

       -  put_old must be underneath new_root, that is, adding a nonzero number of
          /.. to the string pointed to by put_old must yield the same directory as
          new_root.

       -  No other file system may be mounted on put_old.

       See also pivot_root(8) for additional usage examples.

       If the current root is not a mount point (e.g., after chroot(2) or
       pivot_root(), see also below), not the old root directory, but the mount
       point of that file system is mounted on put_old.

       new_root does not have to be a mount point.  In this case, /proc/mounts
       will show the mount point of the file system containing new_root as root
       (/).

RETURN VALUE top

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

ERRORS top

       pivot_root() may return (in errno) any of the errors returned by stat(2).
       Additionally, it may return:

       EBUSY  new_root or put_old are on the current root file system, or a file
              system is already mounted on put_old.

       EINVAL put_old is not underneath new_root.

       ENOTDIR
              new_root or put_old is not a directory.

       EPERM  The calling process does not have the CAP_SYS_ADMIN capability.

VERSIONS top

       pivot_root() was introduced in Linux 2.3.41.

CONFORMING TO top

       pivot_root() is Linux-specific and hence is not portable.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

BUGS top

       pivot_root() should not have to change root and current working directory
       of all other processes in the system.

       Some of the more obscure uses of pivot_root() may quickly lead to insanity.

SEE ALSO top

       chdir(2), chroot(2), stat(2), initrd(4), pivot_root(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                       PIVOT_ROOT(2)


poll(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

POLL(2)                      Linux Programmer's Manual                     POLL(2)

NAME top

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

SYNOPSIS top

       #include <poll.h>

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

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <poll.h>

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

DESCRIPTION top

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

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

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

       The caller should specify the number of items in the fds array in nfds.

       The field fd contains a file descriptor for an open file.  If this field is
       negative, then the corresponding events field is ignored and the revents
       field returns zero.  (This provides an easy way of ignoring a file
       descriptor for a single poll() call: simply negate the fd field.)

       The field events is an input parameter, a bit mask specifying the events
       the application is interested in for the file descriptor fd.  If this field
       is specified as zero, then all events are ignored for fd and revents
       returns zero.

       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
       POLLNVAL.  (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 the minimum number of milliseconds that
       poll() will block.  (This interval will be rounded up to the system clock
       granularity, and kernel scheduling delays mean that the blocking interval
       may overrun by a small amount.)  Specifying a negative value in timeout
       means an infinite timeout.  Specifying a timeout of zero causes poll() to
       return immediately, even if no file descriptors are ready.

       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; pseudoterminal 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 feature test macro must
                     be defined (before including any header files) 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 precision of the timeout argument, the
       following ppoll() call:

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

       is equivalent to atomically executing the following calls:

           sigset_t origmask;
           int timeout;

           timeout = (timeout_ts == NULL) ? -1 :
                     (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
           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() differs from poll() only in the
       precision of the timeout argument).

       The timeout_ts 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_ts is specified as NULL, then ppoll() can block indefinitely.

RETURN VALUE top

       On success, a positive number is returned; this is the number of structures
       which have nonzero 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 top

       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 top

       The poll() system call was introduced in Linux 2.1.23.  On older kernels
       that lack this system call, the glibc (and the old Linux libc) poll()
       wrapper function provides emulation using select(2).

       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 top

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

NOTES top

       Some implementations define the nonstandard constant INFTIM with the value
       -1 for use as a timeout for poll().  This constant is not provided in
       glibc.

       For a discussion of what may happen if a file descriptor being monitored by
       poll() is closed in another thread, see select(2).

Linux Notes

       The Linux ppoll() system call modifies its timeout_ts 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_ts argument.

BUGS top

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

SEE ALSO top

       select(2), select_tut(2), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-17                             POLL(2)


posixoptions(7) - Linux manual page

NAME | DESCRIPTION | XOPEN EXTENSIONS | SEE ALSO | COLOPHON The Linux Programming Interface

POSIXOPTIONS(7)              Linux Programmer's Manual             POSIXOPTIONS(7)

NAME top

       posixoptions - optional parts of the POSIX standard

DESCRIPTION top

       The POSIX standard (the information below is from POSIX.1-2001) describes a
       set of behaviors and interfaces for a compliant system.  However, many
       interfaces are optional and there are feature test macros to test the
       availability of interfaces at compile time, and functions sysconf(3),
       fpathconf(3), pathconf(3), confstr(3) to do this at run time.  From shell
       scripts one can use getconf(1).  For more detail, see sysconf(3).

       We give the name of the POSIX abbreviation, the option, the name of the
       sysconf(3) parameter used to inquire about the option, and possibly a very
       short description.  Much more precise detail can be found in the POSIX
       standard itself, versions of which can nowadays be accessed freely on the
       web.

ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO

       The following advisory functions are present:

           posix_fadvise(),
           posix_fallocate(),
           posix_memalign(),
           posix_madvise().

AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO

       The header <aio.h> is present.  The following functions are present:

           aio_cancel(),
           aio_error(),
           aio_fsync(),
           aio_read(),
           aio_return(),
           aio_suspend(),
           aio_write(),
           lio_listio().

BAR - _POSIX_BARRIERS - _SC_BARRIERS

       This option implies the _POSIX_THREADS and _POSIX_THREAD_SAFE_FUNCTIONS
       options.  The following functions are present:

           pthread_barrier_destroy(),
           pthread_barrier_init(),
           pthread_barrier_wait(),
           pthread_barrierattr_destroy(),
           pthread_barrierattr_init().

--- - POSIX_CHOWN_RESTRICTED

       If this option is in effect (as it always is under POSIX.1-2001) then only
       root may change the owner of a file, and nonroot can only set the group of
       a file to one of the groups it belongs to.  This affects the functions
       chown(), fchown().

CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION

       This option implies the _POSIX_TIMERS option.  The following functions are
       present:

           pthread_condattr_getclock(),
           pthread_condattr_setclock(),
           clock_nanosleep().

       If CLOCK_REALTIME is changed by the function clock_settime(), then this
       affects all timers set for an absolute time.

CPT - _POSIX_CPUTIME - _SC_CPUTIME

       The clockID CLOCK_PROCESS_CPUTIME_ID is supported.  The initial value of
       this clock is 0 for each process.  This option implies the _POSIX_TIMERS
       option.  The function clock_getcpuclockid() is present.

--- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING

       This option has been deleted.  Not in final XPG6.

FSC - _POSIX_FSYNC - _SC_FSYNC

       The function fsync() is present.

IP6 - _POSIX_IPV6 - _SC_IPV6

       Internet Protocol Version 6 is supported.

--- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL

       If this option is in effect (as it always is under POSIX.1-2001) then the
       system implements POSIX-style job control, and the following functions are
       present:

           setpgid(),
           tcdrain(),
           tcflush(),
           tcgetpgrp(),
           tcsendbreak(),
           tcsetattr(),
           tcsetpgrp().

MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES

       Shared memory is supported.  The include file <sys/mman.h> is present.  The
       following functions are present: mmap(), msync(), munmap().

ML - _POSIX_MEMLOCK - _SC_MEMLOCK

       Shared memory can be locked into core.  The functions mlockall(),
       munlockall() are present.

MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE

       More precisely, ranges can be locked into core.  The functions mlock(),
       munlock() are present.

MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION

       The function mprotect() is present.

MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING

       The include file <mqueue.h> is present.  The following functions are
       present:

           mq_close(),
           mq_getattr(),
           mq_notify(),
           mq_open(),
           mq_receive(),
           mq_send(),
           mq_setattr(),
           mq_unlink().

MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK

       CLOCK_MONOTONIC is supported.  This option implies the _POSIX_TIMERS
       option.  Affected functions are

           aio_suspend(),
           clock_getres(),
           clock_gettime(),
           clock_settime(),
           timer_create().

--- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS

       This option has been deleted.  Not in final XPG6.

--- - _POSIX_NO_TRUNC

       If this option is in effect (as it always is under POSIX.1-2001) then
       pathname components longer than NAME_MAX are not truncated, but give an
       error.  This property may be dependent on the path prefix of the component.

PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO

       This option says that one can specify priorities for asynchronous I/O.
       This affects the functions

           aio_read(),
           aio_write().

PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING

       The include file <sched.h> is present.  The following functions are
       present:

           sched_get_priority_max(),
           sched_get_priority_min(),
           sched_getparam(),
           sched_getscheduler(),
           sched_rr_get_interval(),
           sched_setparam(),
           sched_setscheduler(),
           sched_yield().

       If also _POSIX_SPAWN is in effect, then the following functions are
       present:

           posix_spawnattr_getschedparam(),
           posix_spawnattr_getschedpolicy(),
           posix_spawnattr_setschedparam(),
           posix_spawnattr_setschedpolicy().

RS - _POSIX_RAW_SOCKETS

       Raw sockets are supported.  Affected functions are getsockopt(),
       setsockopt().

--- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS

       This option implies the _POSIX_THREADS option.  Conversely, under
       POSIX.1-2001 the _POSIX_THREADS option implies this option.
       The following functions are present:

           pthread_rwlock_destroy(),
           pthread_rwlock_init(),
           pthread_rwlock_rdlock(),
           pthread_rwlock_tryrdlock(),
           pthread_rwlock_trywrlock(),
           pthread_rwlock_unlock(),
           pthread_rwlock_wrlock(),
           pthread_rwlockattr_destroy(),
           pthread_rwlockattr_init().

RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS

       Realtime signals are supported.  The following functions are present:

           sigqueue(),
           sigtimedwait(),
           sigwaitinfo().

--- - _POSIX_REGEXP - _SC_REGEXP

       If this option is in effect (as it always is under POSIX.1-2001) then POSIX
       regular expressions are supported and the following functions are present:

           regcomp(),
           regerror(),
           regexec(),
           regfree().

--- - _POSIX_SAVED_IDS - _SC_SAVED_IDS

       If this option is in effect (as it always is under POSIX.1-2001) then a
       process has a saved set-user-ID and a saved set-group-ID.  Affected
       functions are

           exec(),
           kill(),
           seteuid(),
           setegid(),
           setgid(),
           setuid().

SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES

       The include file <semaphore.h> is present.  The following functions are
       present:

           sem_close(),
           sem_destroy(),
           sem_getvalue(),
           sem_init(),
           sem_open(),
           sem_post(),
           sem_trywait(),
           sem_unlink(),
           sem_wait().

SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS

       The following functions are present:

           mmap(),
           munmap(),
           shm_open(),
           shm_unlink().

--- - _POSIX_SHELL - _SC_SHELL

       If this option is in effect (as it always is under POSIX.1-2001), the
       function system() is present.

SPN - _POSIX_SPAWN - _SC_SPAWN

       This option describes support for process creation in a context where it is
       difficult or impossible to use fork(), for example, because no MMU is
       present.  If _POSIX_SPAWN is in effect, then the include file <spawn.h> and
       the following functions are present:

           posix_spawn(),
           posix_spawn_file_actions_addclose(),
           posix_spawn_file_actions_adddup2(),
           posix_spawn_file_actions_addopen(),
           posix_spawn_file_actions_destroy(),
           posix_spawn_file_actions_init(),
           posix_spawnattr_destroy(),
           posix_spawnattr_getsigdefault(),
           posix_spawnattr_getflags(),
           posix_spawnattr_getpgroup(),
           posix_spawnattr_getsigmask(),
           posix_spawnattr_init(),
           posix_spawnattr_setsigdefault(),
           posix_spawnattr_setflags(),
           posix_spawnattr_setpgroup(),
           posix_spawnattr_setsigmask(),
           posix_spawnp().
       If also _POSIX_PRIORITY_SCHEDULING is in effect, then the following
       functions are present:

           posix_spawnattr_getschedparam(),
           posix_spawnattr_getschedpolicy(),
           posix_spawnattr_setschedparam(),
           posix_spawnattr_setschedpolicy().

SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS

       This option implies the _POSIX_THREADS and _POSIX_THREAD_SAFE_FUNCTIONS
       options.  The following functions are present:

           pthread_spin_destroy(),
           pthread_spin_init(),
           pthread_spin_lock(),
           pthread_spin_trylock(),
           pthread_spin_unlock().

SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER

       The scheduling policy SCHED_SPORADIC is supported.  This option implies the
       _POSIX_PRIORITY_SCHEDULING option.  Affected functions are

           sched_setparam(),
           sched_setscheduler().

SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO

       Affected functions are open(), msync(), fsync(), fdatasync().

TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR

       Affected functions are

           pthread_attr_getstack(),
           pthread_attr_getstackaddr(),
           pthread_attr_setstack(),
           pthread_attr_setstackaddr().

TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE

       Affected functions are

           pthread_attr_getstack(),
           pthread_attr_getstacksize(),
           pthread_attr_setstack(),
           pthread_attr_setstacksize().

TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME

       The clockID CLOCK_THREAD_CPUTIME_ID is supported.  This option implies the
       _POSIX_TIMERS option.  Affected functions are

           pthread_getcpuclockid(),
           clock_getres(),
           clock_gettime(),
           clock_settime(),
           timer_create().

TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT

       Affected functions are

           pthread_mutexattr_getprotocol(),
           pthread_mutexattr_setprotocol().

TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT

       Affected functions are

           pthread_mutex_getprioceiling(),
           pthread_mutex_setprioceiling(),
           pthread_mutexattr_getprioceiling(),
           pthread_mutexattr_getprotocol(),
           pthread_mutexattr_setprioceiling(),
           pthread_mutexattr_setprotocol().

TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING

       If this option is in effect, the different threads inside a process can run
       with different priorities and/or different schedulers.  Affected functions
       are

           pthread_attr_getinheritsched(),
           pthread_attr_getschedpolicy(),
           pthread_attr_getscope(),
           pthread_attr_setinheritsched(),
           pthread_attr_setschedpolicy(),
           pthread_attr_setscope(),
           pthread_getschedparam(),
           pthread_setschedparam(),
           pthread_setschedprio().

TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED

       Affected functions are

           pthread_barrierattr_getpshared(),
           pthread_barrierattr_setpshared(),
           pthread_condattr_getpshared(),
           pthread_condattr_setpshared(),
           pthread_mutexattr_getpshared(),
           pthread_mutexattr_setpshared(),
           pthread_rwlockattr_getpshared(),
           pthread_rwlockattr_setpshared().

TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS

       Affected functions are

           readdir_r(),
           getgrgid_r(),
           getgrnam_r(),
           getpwnam_r(),
           getpwuid_r(),
           flockfile(),
           ftrylockfile(),
           funlockfile(),
           getc_unlocked(),
           getchar_unlocked(),
           putc_unlocked(),
           putchar_unlocked(),
           rand_r(),
           strerror_r(),
           strtok_r(),
           asctime_r(),
           ctime_r(),
           gmtime_r(),
           localtime_r().

TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER

       This option implies the _POSIX_THREAD_PRIORITY_SCHEDULING option.  Affected
       functions are

           sched_getparam(),
           sched_setparam(),
           sched_setscheduler().

THR - _POSIX_THREADS - _SC_THREADS

       Basic support for POSIX threads is available.  The following functions are
       present:

           pthread_atfork(),
           pthread_attr_destroy(),
           pthread_attr_getdetachstate(),
           pthread_attr_getschedparam(),
           pthread_attr_init(),
           pthread_attr_setdetachstate(),
           pthread_attr_setschedparam(),
           pthread_cancel(),
           pthread_cleanup_push(),
           pthread_cleanup_pop(),
           pthread_cond_broadcast(),
           pthread_cond_destroy(),
           pthread_cond_init(),
           pthread_cond_signal(),
           pthread_cond_timedwait(),
           pthread_cond_wait(),
           pthread_condattr_destroy(),
           pthread_condattr_init(),
           pthread_create(),
           pthread_detach(),
           pthread_equal(),
           pthread_exit(),
           pthread_getspecific(),
           pthread_join(),
           pthread_key_create(),
           pthread_key_delete(),
           pthread_mutex_destroy(),
           pthread_mutex_init(),
           pthread_mutex_lock(),
           pthread_mutex_trylock(),
           pthread_mutex_unlock(),
           pthread_mutexattr_destroy(),
           pthread_mutexattr_init(),
           pthread_once(),
           pthread_rwlock_destroy(),
           pthread_rwlock_init(),
           pthread_rwlock_rdlock(),
           pthread_rwlock_tryrdlock(),
           pthread_rwlock_trywrlock(),
           pthread_rwlock_unlock(),
           pthread_rwlock_wrlock(),
           pthread_rwlockattr_destroy(),
           pthread_rwlockattr_init(),
           pthread_self(),
           pthread_setcancelstate(),
           pthread_setcanceltype(),
           pthread_setspecific(),
           pthread_testcancel().

TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS

       The following functions are present:

           mq_timedreceive(),
           mq_timedsend(),
           pthread_mutex_timedlock(),
           pthread_rwlock_timedrdlock(),
           pthread_rwlock_timedwrlock(),
           sem_timedwait(),
           posix_trace_timedgetnext_event().

TMR - _POSIX_TIMERS - _SC_TIMERS

       The following functions are present:

           clock_getres(),
           clock_gettime(),
           clock_settime(),
           nanosleep(),
           timer_create(),
           timer_delete(),
           timer_gettime(),
           timer_getoverrun(),
           timer_settime().

TRC - _POSIX_TRACE - _SC_TRACE

       POSIX tracing is available.  The following functions are present:

           posix_trace_attr_destroy(),
           posix_trace_attr_getclockres(),
           posix_trace_attr_getcreatetime(),
           posix_trace_attr_getgenversion(),
           posix_trace_attr_getmaxdatasize(),
           posix_trace_attr_getmaxsystemeventsize(),
           posix_trace_attr_getmaxusereventsize(),
           posix_trace_attr_getname(),
           posix_trace_attr_getstreamfullpolicy(),
           posix_trace_attr_getstreamsize(),
           posix_trace_attr_init(),
           posix_trace_attr_setmaxdatasize(),
           posix_trace_attr_setname(),
           posix_trace_attr_setstreamsize(),
           posix_trace_attr_setstreamfullpolicy(),
           posix_trace_clear(),
           posix_trace_create(),
           posix_trace_event(),
           posix_trace_eventid_equal(),
           posix_trace_eventid_get_name(),
           posix_trace_eventid_open(),
           posix_trace_eventtypelist_getnext_id(),
           posix_trace_eventtypelist_rewind(),
           posix_trace_flush(),
           posix_trace_get_attr(),
           posix_trace_get_status(),
           posix_trace_getnext_event(),
           posix_trace_shutdown(),
           posix_trace_start(),
           posix_trace_stop(),
           posix_trace_trygetnext_event().

TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER

       This option implies the _POSIX_TRACE option.  The following functions are
       present:

           posix_trace_eventset_add(),
           posix_trace_eventset_del(),
           posix_trace_eventset_empty(),
           posix_trace_eventset_fill(),
           posix_trace_eventset_ismember(),
           posix_trace_get_filter(),
           posix_trace_set_filter(),
           posix_trace_trid_eventid_open().

TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT

       Tracing children of the traced process is supported.  This option implies
       the _POSIX_TRACE option.  The following functions are present:

           posix_trace_attr_getinherited(),
           posix_trace_attr_setinherited().

TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG

       This option implies the _POSIX_TRACE option.  The following functions are
       present:

           posix_trace_attr_getlogfullpolicy(),
           posix_trace_attr_getlogsize(),
           posix_trace_attr_setlogfullpolicy(),
           posix_trace_attr_setlogsize(),
           posix_trace_close(),
           posix_trace_create_withlog(),
           posix_trace_open(),
           posix_trace_rewind().

TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT

       The following functions are present:

           posix_mem_offset(),
           posix_typed_mem_get_info(),
           posix_typed_mem_open().

--- - _POSIX_VDISABLE

       Always present (probably 0).  Value to set a changeable special control
       character to indicate that it is disabled.

XOPEN EXTENSIONS top

       _XOPEN_CRYPT, _XOPEN_LEGACY, _XOPEN_REALTIME, _XOPEN_REALTIME_THREADS,
       _XOPEN_UNIX.

SEE ALSO top

       sysconf(3), standards(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-12-21                     POSIXOPTIONS(7)


posix_fallocate(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

POSIX_FALLOCATE(3)           Linux Programmer's Manual          POSIX_FALLOCATE(3)

NAME top

       posix_fallocate - allocate file space

SYNOPSIS top

       #include <fcntl.h>

       int posix_fallocate(int fd, off_t offset, off_t len);

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

       posix_fallocate():
           _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       The function posix_fallocate() ensures that disk space is allocated for the
       file referred to by the descriptor fd for the bytes in the range starting
       at offset and continuing for len bytes.  After a successful call to
       posix_fallocate(), subsequent writes to bytes in the specified range are
       guaranteed not to fail because of lack of disk space.

       If the size of the file is less than offset+len, then the file is increased
       to this size; otherwise the file size is left unchanged.

RETURN VALUE top

       posix_fallocate() returns zero on success, or an error number on failure.
       Note that errno is not set.

ERRORS top

       EBADF  fd is not a valid file descriptor, or is not opened for writing.

       EFBIG  offset+len exceeds the maximum file size.

       EINVAL offset was less than 0, or len was less than or equal to 0.

       ENODEV fd does not refer to a regular file.

       ENOSPC There is not enough space left on the device containing the file
              referred to by fd.

       ESPIPE fd refers to a pipe.

VERSIONS top

       posix_fallocate() is available since glibc 2.1.94.

CONFORMING TO top

       POSIX.1-2001.

       POSIX.1-2008 says that an implementation shall give the EINVAL error if len
       was 0, or offset was less than 0.  POSIX.1-2001 says that an implementation
       shall give the EINVAL error if len is less than 0, or offset was less than
       0, and may give the error if len equals zero.

SEE ALSO top

       fallocate(2), lseek(2), posix_fadvise(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                  POSIX_FALLOCATE(3)


posix_openpt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

POSIX_OPENPT(3)              Linux Programmer's Manual             POSIX_OPENPT(3)

NAME top

       posix_openpt - open a pseudoterminal device

SYNOPSIS top

       #include <stdlib.h>
       #include <fcntl.h>

       int posix_openpt(int flags);

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

       posix_openpt(): _XOPEN_SOURCE >= 600

DESCRIPTION top

       The posix_openpt() function opens an unused pseudoterminal master device,
       returning a file descriptor that can be used to refer to that device.

       The flags argument is a bit mask that ORs together zero or more of the
       following flags:

       O_RDWR Open the device for both reading and writing.  It is usual to
              specify this flag.

       O_NOCTTY
              Do not make this device the controlling terminal for the process.

RETURN VALUE top

       On success, posix_openpt() returns a nonnegative file descriptor which is
       the lowest numbered unused descriptor.  On failure, -1 is returned, and
       errno is set to indicate the error.

ERRORS top

       See open(2).

VERSIONS top

       Glibc support for posix_openpt() has been provided since version 2.2.1.

CONFORMING TO top

       posix_openpt() is part of the UNIX 98 pseudoterminal support (see pts(4)).
       This function is specified in POSIX.1-2001.

NOTES top

       The posix_openpt() function is a recent invention in POSIX.  Some UNIX
       implementations that support System V (aka UNIX 98) pseudoterminals don't
       have this function, but it is easy to implement:

           int
           posix_openpt(int flags)
           {
               return open("/dev/ptmx", flags);
           }

       Calling posix_openpt() creates a pathname for the corresponding
       pseudoterminal slave device.  The pathname of the slave device can be
       obtained using ptsname(3).  The slave device pathname exists only as long
       as the master device is open.

SEE ALSO top

       open(2), getpt(3), grantpt(3), ptsname(3), unlockpt(3), pts(4), pty(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-20                     POSIX_OPENPT(3)


pow(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

POW(3)                       Linux Programmer's Manual                      POW(3)

NAME top

       pow, powf, powl - power functions

SYNOPSIS top

       #include <math.h>

       double pow(double x, double y);
       float powf(float x, float y);
       long double powl(long double x, long double y);

       Link with -lm.

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

       powf(), powl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The pow() function returns the value of x raised to the power of y.

RETURN VALUE top

       On success, these functions return the value of x to the power of y.

       If x is a finite value less than 0, and y is a finite noninteger, a domain
       error occurs, and a NaN is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with the mathematically
       correct sign.

       If result underflows, and is not representable, a range error occurs, and
       0.0 is returned.

       Except as specified below, if x or y is a NaN, the result is a NaN.

       If x is +1, the result is 1.0 (even if y is a NaN).

       If y is 0, the result is 1.0 (even if x is a NaN).

       If x is +0 (-0), and y is an odd integer greater than 0, the result is +0
       (-0).

       If x is 0, and y greater than 0 and not an odd integer, the result is +0.

       If x is -1, and y is positive infinity or negative infinity, the result is
       1.0.

       If the absolute value of x is less than 1, and y is negative infinity, the
       result is positive infinity.

       If the absolute value of x is greater than 1, and y is negative infinity,
       the result is +0.

       If the absolute value of x is less than 1, and y is positive infinity, the
       result is +0.

       If the absolute value of x is greater than 1, and y is positive infinity,
       the result is positive infinity.

       If x is negative infinity, and y is an odd integer less than 0, the result
       is -0.

       If x is negative infinity, and y less than 0 and not an odd integer, the
       result is +0.

       If x is negative infinity, and y is an odd integer greater than 0, the
       result is negative infinity.

       If x is negative infinity, and y greater than 0 and not an odd integer, the
       result is positive infinity.

       If x is positive infinity, and y less than 0, the result is +0.

       If x is positive infinity, and y greater than 0, the result is positive
       infinity.

       If x is +0 or -0, and y is an odd integer less than 0, a pole error occurs
       and HUGE_VAL, HUGE_VALF, or HUGE_VALL, is returned, with the same sign as
       x.

       If x is +0 or -0, and y is less than 0 and not an odd integer, a pole error
       occurs and +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL, is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is negative, and y is a finite noninteger
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

       Pole error: x is zero, and y is negative
              errno is set to ERANGE (but see BUGS).  A divide-by-zero floating-
              point exception (FE_DIVBYZERO) is raised.

       Range error: the result overflows
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

       Range error: the result underflows
              errno is set to ERANGE.  An underflow floating-point exception
              (FE_UNDERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

BUGS top

       In glibc 2.9 and earlier, when a pole error occurs, errno is set to EDOM
       instead of the POSIX-mandated ERANGE.  Since version 2.10, glibc does the
       right thing.

       If x is negative, then large negative or positive y values yield a NaN as
       the function result, with errno set to EDOM, and an invalid (FE_INVALID)
       floating-point exception.  For example, with pow(), one sees this behavior
       when the absolute value of y is greater than about 9.223373e18.

       In version 2.3.2 and earlier, when an overflow or underflow error occurs,
       glibc's pow() generates a bogus invalid floating-point exception
       (FE_INVALID) in addition to the overflow or underflow exception.

SEE ALSO top

       cbrt(3), cpow(3), sqrt(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-12                              POW(3)


pow10(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

POW10(3)                     Linux Programmer's Manual                    POW10(3)

NAME top

       pow10, pow10f, pow10l - base-10 power functions

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <math.h>

       double pow10(double x);
       float pow10f(float x);
       long double pow10l(long double x);

       Link with -lm.

DESCRIPTION top

       The pow10() function returns the value of 10 raised to the power x.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       This is a GNU extension.

NOTES top

       These functions are identical to the functions listed under exp10(3).

SEE ALSO top

       exp10(3), pow(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-11                            POW10(3)


prctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PRCTL(2)                     Linux Programmer's Manual                    PRCTL(2)

NAME top

       prctl - operations on a process

SYNOPSIS top

       #include <sys/prctl.h>

       int prctl(int option, unsigned long arg2, unsigned long arg3,
                 unsigned long arg4, unsigned long arg5);

DESCRIPTION top

       prctl() is called with a first argument describing what to do (with values
       defined in <linux/prctl.h>), and further arguments with a significance
       depending on the first one.  The first argument can be:

       PR_CAPBSET_READ (since Linux 2.6.25)
              Return (as the function result) 1 if the capability specified in
              arg2 is in the calling thread's capability bounding set, or 0 if it
              is not.  (The capability constants are defined in
              <linux/capability.h>.)  The capability bounding set dictates whether
              the process can receive the capability through a file's permitted
              capability set on a subsequent call to execve(2).

              If the capability specified in arg2 is not valid, then the call
              fails with the error EINVAL.

       PR_CAPBSET_DROP (since Linux 2.6.25)
              If the calling thread has the CAP_SETPCAP capability, then drop the
              capability specified by arg2 from the calling thread's capability
              bounding set.  Any children of the calling thread will inherit the
              newly reduced bounding set.

              The call fails with the error: EPERM if the calling thread does not
              have the CAP_SETPCAP; EINVAL if arg2 does not represent a valid
              capability; or EINVAL if file capabilities are not enabled in the
              kernel, in which case bounding sets are not supported.

       PR_SET_DUMPABLE (since Linux 2.3.20)
              Set the state of the flag determining whether core dumps are
              produced for this process upon delivery of a signal whose default
              behavior is to produce a core dump.  (Normally this flag is set for
              a process by default, but it is cleared when a set-user-ID or set-
              group-ID program is executed and also by various system calls that
              manipulate process UIDs and GIDs).  In kernels up to and including
              2.6.12, arg2 must be either 0 (process is not dumpable) or 1
              (process is dumpable).  Between kernels 2.6.13 and 2.6.17, the value
              2 was also permitted, which caused any binary which normally would
              not be dumped to be dumped readable by root only; for security
              reasons, this feature has been removed.  (See also the description
              of /proc/sys/fs/suid_dumpable in proc(5).)  Processes that are not
              dumpable can not be attached via ptrace(2) PTRACE_ATTACH.

       PR_GET_DUMPABLE (since Linux 2.3.20)
              Return (as the function result) the current state of the calling
              process's dumpable flag.

       PR_SET_ENDIAN (since Linux 2.6.18, PowerPC only)
              Set the endian-ness of the calling process to the value given in
              arg2, which should be one of the following: PR_ENDIAN_BIG,
              PR_ENDIAN_LITTLE, or PR_ENDIAN_PPC_LITTLE (PowerPC pseudo little
              endian).

       PR_GET_ENDIAN (since Linux 2.6.18, PowerPC only)
              Return the endian-ness of the calling process, in the location
              pointed to by (int *) arg2.

       PR_SET_FPEMU (since Linux 2.4.18, 2.5.9, only on ia64)
              Set floating-point emulation control bits to arg2.  Pass
              PR_FPEMU_NOPRINT to silently emulate fp operations accesses, or
              PR_FPEMU_SIGFPE to not emulate fp operations and send SIGFPE
              instead.

       PR_GET_FPEMU (since Linux 2.4.18, 2.5.9, only on ia64)
              Return floating-point emulation control bits, in the location
              pointed to by (int *) arg2.

       PR_SET_FPEXC (since Linux 2.4.21, 2.5.32, only on PowerPC)
              Set floating-point exception mode to arg2.  Pass PR_FP_EXC_SW_ENABLE
              to use FPEXC for FP exception enables, PR_FP_EXC_DIV for floating-
              point divide by zero, PR_FP_EXC_OVF for floating-point overflow,
              PR_FP_EXC_UND for floating-point underflow, PR_FP_EXC_RES for
              floating-point inexact result, PR_FP_EXC_INV for floating-point
              invalid operation, PR_FP_EXC_DISABLED for FP exceptions disabled,
              PR_FP_EXC_NONRECOV for async nonrecoverable exception mode,
              PR_FP_EXC_ASYNC for async recoverable exception mode,
              PR_FP_EXC_PRECISE for precise exception mode.

       PR_GET_FPEXC (since Linux 2.4.21, 2.5.32, only on PowerPC)
              Return floating-point exception mode, in the location pointed to by
              (int *) arg2.

       PR_SET_KEEPCAPS (since Linux 2.2.18)
              Set the state of the thread's "keep capabilities" flag, which
              determines whether the threads's permitted capability set is cleared
              when a change is made to the threads's user IDs such that the
              threads's real UID, effective UID, and saved set-user-ID all become
              nonzero when at least one of them previously had the value 0.  By
              default, the permitted capability set is cleared when such a change
              is made; setting the "keep capabilities" flag prevents it from being
              cleared.  arg2 must be either 0 (permitted capabilities are cleared)
              or 1 (permitted capabilities are kept).  (A thread's effective
              capability set is always cleared when such a credential change is
              made, regardless of the setting of the "keep capabilities" flag.)
              The "keep capabilities" value will be reset to 0 on subsequent calls
              to execve(2).

       PR_GET_KEEPCAPS (since Linux 2.2.18)
              Return (as the function result) the current state of the calling
              threads's "keep capabilities" flag.

       PR_SET_NAME (since Linux 2.6.9)
              Set the process name for the calling thread, using the value in the
              location pointed to by (char *) arg2.  The name can be up to 16
              bytes long, and should be null-terminated if it contains fewer
              bytes.

       PR_GET_NAME (since Linux 2.6.11)
              Return the name for the calling thread, in the buffer pointed to by
              (char *) arg2.  The buffer should allow space for up to 16 bytes;
              the returned string will be null-terminated if it is shorter than
              that.

       PR_SET_NO_NEW_PRIVS (since Linux 3.5)
              Set the calling process's no_new_privs bit to the value in arg2.
              With no_new_privs set to 1, execve(2) promises not to grant
              privileges to do anything that could not have been done without the
              execve(2) call (for example, rendering the set-user-ID and set-
              group-ID permission bits, and file capabilities non-functional).
              Once set, this bit cannot be unset.  The setting of this bit is
              inherited by children created by fork(2) and clone(2), and preserved
              across execve(2).

              For more information, see the kernel source file
              Documentation/prctl/no_new_privs.txt.

       PR_GET_NO_NEW_PRIVS (since Linux 3.5)
              Return the value of the no_new_privs bit for the current process.  A
              value of 0 indicates the regular execve(2) behavior.  A value of 1
              indicates execve(2) will operate in the privilege-restricting mode
              described above.

       PR_SET_PDEATHSIG (since Linux 2.1.57)
              Set the parent process death signal of the calling process to arg2
              (either a signal value in the range 1..maxsig, or 0 to clear).  This
              is the signal that the calling process will get when its parent
              dies.  This value is cleared for the child of a fork(2) and (since
              Linux 2.4.36 / 2.6.23) when executing a set-user-ID or set-group-ID
              binary.

       PR_GET_PDEATHSIG (since Linux 2.3.15)
              Return the current value of the parent process death signal, in the
              location pointed to by (int *) arg2.

       PR_SET_SECCOMP (since Linux 2.6.23)
              Set the secure computing (seccomp) mode for the calling thread, to
              limit the available system calls.  The seccomp mode is selected via
              arg2.  (The seccomp constants are defined in <linux/seccomp.h>.)

              With arg2 set to SECCOMP_MODE_STRICT the only system calls that the
              thread is permitted to make are read(2), write(2), _exit(2), and
              sigreturn(2).  Other system calls result in the delivery of a
              SIGKILL signal.  Strict secure computing mode is useful for number-
              crunching applications that may need to execute untrusted byte code,
              perhaps obtained by reading from a pipe or socket.  This operation
              is only available if the kernel is configured with CONFIG_SECCOMP
              enabled.

              With arg2 set to SECCOMP_MODE_FILTER (since Linux 3.5) the system
              calls allowed are defined by a pointer to a Berkeley Packet Filter
              passed in arg3.  This argument is a pointer to struct sock_fprog; it
              can be designed to filter arbitrary system calls and system call
              arguments.  This mode is only available if the kernel is configured
              with CONFIG_SECCOMP_FILTER enabled.

              If SECCOMP_MODE_FILTER filters permit fork(2), then the seccomp mode
              is inherited by children created by fork(2); if execve(2) is
              permitted, then the seccomp mode is preserved across execve(2).  If
              the filters permit prctl(0 calls, then additional filters can be
              added; they are run in order until the first non-allow result is
              seen.

              For further information, see the kernel source file
              Documentation/prctl/seccomp_filter.txt.

       PR_GET_SECCOMP (since Linux 2.6.23)
              Return the secure computing mode of the calling thread.  If the
              caller is not in secure computing mode, this operation returns 0; if
              the caller is in strict secure computing mode, then the prctl() call
              will cause a SIGKILL signal to be sent to the process.  If the
              caller is in filter mode, and this system call is allowed by the
              seccomp filters, it returns 2.  This operation is only available if
              the kernel is configured with CONFIG_SECCOMP enabled.

       PR_SET_SECUREBITS (since Linux 2.6.26)
              Set the "securebits" flags of the calling thread to the value
              supplied in arg2.  See capabilities(7).

       PR_GET_SECUREBITS (since Linux 2.6.26)
              Return (as the function result) the "securebits" flags of the
              calling thread.  See capabilities(7).

       PR_SET_TIMERSLACK (since Linux 2.6.28)
              Set the current timer slack for the calling thread to the nanosecond
              value supplied in arg2.  If arg2 is less than or equal to zero,
              reset the current timer slack to the thread's default timer slack
              value.  The timer slack is used by the kernel to group timer
              expirations for the calling thread that are close to one another; as
              a consequence, timer expirations for the thread may be up to the
              specified number of nanoseconds late (but will never expire early).
              Grouping timer expirations can help reduce system power consumption
              by minimizing CPU wake-ups.

              The timer expirations affected by timer slack are those set by
              select(2), pselect(2), poll(2), ppoll(2), epoll_wait(2),
              epoll_pwait(2), clock_nanosleep(2), nanosleep(2), and futex(2) (and
              thus the library functions implemented via futexes, including
              pthread_cond_timedwait(3), pthread_mutex_timedlock(3),
              pthread_rwlock_timedrdlock(3), pthread_rwlock_timedwrlock(3), and
              sem_timedwait(3)).

              Timer slack is not applied to threads that are scheduled under a
              realtime scheduling policy (see sched_setscheduler(2)).

              Each thread has two associated timer slack values: a "default"
              value, and a "current" value.  The current value is the one that
              governs grouping of timer expirations.  When a new thread is
              created, the two timer slack values are made the same as the current
              value of the creating thread.  Thereafter, a thread can adjust its
              current timer slack value via PR_SET_TIMERSLACK (the default value
              can't be changed).  The timer slack values of init (PID 1), the
              ancestor of all processes, are 50,000 nanoseconds (50 microseconds).
              The timer slack values are preserved across execve(2).

       PR_GET_TIMERSLACK (since Linux 2.6.28)
              Return the current timer slack value of the calling thread.

       PR_SET_TIMING (since Linux 2.6.0-test4)
              Set whether to use (normal, traditional) statistical process timing
              or accurate timestamp-based process timing, by passing
              PR_TIMING_STATISTICAL or PR_TIMING_TIMESTAMP to arg2.
              PR_TIMING_TIMESTAMP is not currently implemented (attempting to set
              this mode will yield the error EINVAL).

       PR_GET_TIMING (since Linux 2.6.0-test4)
              Return (as the function result) which process timing method is
              currently in use.

       PR_TASK_PERF_EVENTS_DISABLE (since Linux 2.6.31)
              Disable all performance counters attached to the calling process,
              regardless of whether the counters were created by this process or
              another process.  Performance counters created by the calling
              process for other processes are unaffected.  For more information on
              performance counters, see the Linux kernel source file
              tools/perf/design.txt.

              Originally called PR_TASK_PERF_COUNTERS_DISABLE; renamed (with same
              numerical value) in Linux 2.6.32.

       PR_TASK_PERF_EVENTS_ENABLE (since Linux 2.6.31)
              The converse of PR_TASK_PERF_EVENTS_DISABLE; enable performance
              counters attached to the calling process.

              Originally called PR_TASK_PERF_COUNTERS_ENABLE; renamed in Linux
              2.6.32.

       PR_SET_TSC (since Linux 2.6.26, x86 only)
              Set the state of the flag determining whether the timestamp counter
              can be read by the process.  Pass PR_TSC_ENABLE to arg2 to allow it
              to be read, or PR_TSC_SIGSEGV to generate a SIGSEGV when the process
              tries to read the timestamp counter.

       PR_GET_TSC (since Linux 2.6.26, x86 only)
              Return the state of the flag determining whether the timestamp
              counter can be read, in the location pointed to by (int *) arg2.

       PR_SET_UNALIGN
              (Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
              PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22) Set
              unaligned access control bits to arg2.  Pass PR_UNALIGN_NOPRINT to
              silently fix up unaligned user accesses, or PR_UNALIGN_SIGBUS to
              generate SIGBUS on unaligned user access.

       PR_GET_UNALIGN
              (see PR_SET_UNALIGN for information on versions and architectures)
              Return unaligned access control bits, in the location pointed to by
              (int *) arg2.

       PR_MCE_KILL (since Linux 2.6.32)
              Set the machine check memory corruption kill policy for the current
              thread.  If arg2 is PR_MCE_KILL_CLEAR, clear the thread memory
              corruption kill policy and use the system-wide default.  (The
              system-wide default is defined by
              /proc/sys/vm/memory_failure_early_kill; see proc(5).)  If arg2 is
              PR_MCE_KILL_SET, use a thread-specific memory corruption kill
              policy.  In this case, arg3 defines whether the policy is early kill
              (PR_MCE_KILL_EARLY), late kill (PR_MCE_KILL_LATE), or the system-
              wide default (PR_MCE_KILL_DEFAULT).  Early kill means that the
              thread receives a SIGBUS signal as soon as hardware memory
              corruption is detected inside its address space.  In late kill mode,
              the process is only killed when it accesses a corrupted page.  See
              sigaction(2) for more information on the SIGBUS signal.  The policy
              is inherited by children.  The remaining unused prctl() arguments
              must be zero for future compatibility.

       PR_MCE_KILL_GET (since Linux 2.6.32)
              Return the current per-process machine check kill policy.  All
              unused prctl() arguments must be zero.

       PR_SET_MM (since Linux 3.3)
              Modify certain kernel memory map descriptor fields of the calling
              process.  Usually these fields are set by the kernel and dynamic
              loader (see ld.so(8) for more information) and a regular application
              should not use this feature.  However, there are cases, such as
              self-modifying programs, where a program might find it useful to
              change its own memory map.  This feature is available only if the
              kernel is built with the CONFIG_CHECKPOINT_RESTORE option enabled.
              The calling process must have the CAP_SYS_RESOURCE capability.  The
              value in arg2 is one of the options below, while arg3 provides a new
              value for the option.

              PR_SET_MM_START_CODE
                     Set the address above which the program text can run.  The
                     corresponding memory area must be readable and executable,
                     but not writable or sharable (see mprotect(2) and mmap(2) for
                     more information).

              PR_SET_MM_END_CODE
                     Set the address below which the program text can run.  The
                     corresponding memory area must be readable and executable,
                     but not writable or sharable.

              PR_SET_MM_START_DATA
                     Set the address above which initialized and uninitialized
                     (bss) data are placed.  The corresponding memory area must be
                     readable and writable, but not executable or sharable.

              PR_SET_MM_END_DATA
                     Set the address below which initialized and uninitialized
                     (bss) data are placed.  The corresponding memory area must be
                     readable and writable, but not executable or sharable.

              PR_SET_MM_START_STACK
                     Set the start address of the stack.  The corresponding memory
                     area must be readable and writable.

              PR_SET_MM_START_BRK
                     Set the address above which the program heap can be expanded
                     with brk(2) call.  The address must be greater than the
                     ending address of the current program data segment.  In
                     addition, the combined size of the resulting heap and the
                     size of the data segment can't exceed the RLIMIT_DATA
                     resource limit (see setrlimit(2)).

              PR_SET_MM_BRK
                     Set the current brk(2) value.  The requirements for the
                     address are the same as for the PR_SET_MM_START_BRK option.

RETURN VALUE top

       On success, PR_GET_DUMPABLE, PR_GET_KEEPCAPS, PR_GET_NO_NEW_PRIVS,
       PR_CAPBSET_READ, PR_GET_TIMING, PR_GET_SECUREBITS, PR_MCE_KILL_GET, and (if
       it returns) PR_GET_SECCOMP return the nonnegative values described above.
       All other option values return 0 on success.  On error, -1 is returned, and
       errno is set appropriately.

ERRORS top

       EFAULT arg2 is an invalid address.

       EINVAL The value of option is not recognized.

       EINVAL option is PR_MCE_KILL or PR_MCE_KILL_GET or PR_SET_MM, and unused
              prctl() arguments were not specified as zero.

       EINVAL arg2 is not valid value for this option.

       EINVAL option is PR_SET_SECCOMP or PR_SET_SECCOMP, and the kernel was not
              configured with CONFIG_SECCOMP.

       EINVAL option is PR_SET_MM, and one of the following is true

              *  arg4 or arg5 is nonzero;

              *  arg3 is greater than TASK_SIZE (the limit on the size of the user
                 address space for this architecture);

              *  arg2 is PR_SET_MM_START_CODE, PR_SET_MM_END_CODE,
                 PR_SET_MM_START_DATA, PR_SET_MM_END_DATA, or
                 PR_SET_MM_START_STACK, and the permissions of the corresponding
                 memory area are not as required;

              *  arg2 is PR_SET_MM_START_BRK or PR_SET_MM_BRK, and arg3 is less
                 than or equal to the end of the data segment or specifies a value
                 that would cause the RLIMIT_DATA resource limit to be exceeded.

       EPERM  option is PR_SET_SECUREBITS, and the caller does not have the
              CAP_SETPCAP capability, or tried to unset a "locked" flag, or tried
              to set a flag whose corresponding locked flag was set (see
              capabilities(7)).

       EPERM  option is PR_SET_KEEPCAPS, and the callers's SECURE_KEEP_CAPS_LOCKED
              flag is set (see capabilities(7)).

       EPERM  option is PR_CAPBSET_DROP, and the caller does not have the
              CAP_SETPCAP capability.

       EPERM  option is PR_SET_MM, and the caller does not have the
              CAP_SYS_RESOURCE capability.

VERSIONS top

       The prctl() system call was introduced in Linux 2.1.57.

CONFORMING TO top

       This call is Linux-specific.  IRIX has a prctl() system call (also
       introduced in Linux 2.1.44 as irix_prctl on the MIPS architecture), with
       prototype

       ptrdiff_t prctl(int option, int arg2, int arg3);

       and options to get the maximum number of processes per user, get the
       maximum number of processors the calling process can use, find out whether
       a specified process is currently blocked, get or set the maximum stack
       size, and so on.

SEE ALSO top

       signal(2), core(5)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-25                            PRCTL(2)


pread(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PREAD(2)                     Linux Programmer's Manual                    PREAD(2)

NAME top

       pread, pwrite - read from or write to a file descriptor at a given offset

SYNOPSIS top

       #include <unistd.h>

       ssize_t pread(int fd, void *buf, size_t count, off_t offset);

       ssize_t pwrite(int fd, const void *buf, size_t count, off_t offset);

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

       pread(), pwrite():
           _XOPEN_SOURCE >= 500
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       pread() reads up to count bytes from file descriptor fd at offset offset
       (from the start of the file) into the buffer starting at buf.  The file
       offset is not changed.

       pwrite() writes up to count bytes from the buffer starting at buf to the
       file descriptor fd at offset offset.  The file offset is not changed.

       The file referenced by fd must be capable of seeking.

RETURN VALUE top

       On success, the number of bytes read or written is returned (zero indicates
       that nothing was written, in the case of pwrite(), or end of file, in the
       case of pread()), or -1 on error, in which case errno is set to indicate
       the error.

ERRORS top

       pread() can fail and set errno to any error specified for read(2) or
       lseek(2).  pwrite() can fail and set errno to any error specified for
       write(2) or lseek(2).

VERSIONS top

       The pread() and pwrite() system calls were added to Linux in version
       2.1.60; the entries in the i386 system call table were added in 2.1.69.  C
       library support (including emulation using lseek(2) on older kernels
       without the system calls) was added in glibc 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       On Linux, the underlying system calls were renamed in kernel 2.6: pread()
       became pread64(), and pwrite() became pwrite64().  The system call numbers
       remained the same.  The glibc pread() and pwrite() wrapper functions
       transparently deal with the change.

BUGS top

       POSIX requires that opening a file with the O_APPEND flag should have no
       affect on the location at which pwrite() writes data.  However, on Linux,
       if a file is opened with O_APPEND, pwrite() appends data to the end of the
       file, regardless of the value of offset.

SEE ALSO top

       lseek(2), read(2), readv(2), write(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-30                            PREAD(2)


readv(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

READV(2)                     Linux Programmer's Manual                    READV(2)

NAME top

       readv, writev, preadv, pwritev - read or write data into multiple buffers

SYNOPSIS top

       #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);

       ssize_t preadv(int fd, const struct iovec *iov, int iovcnt,
                      off_t offset);

       ssize_t pwritev(int fd, const struct iovec *iov, int iovcnt,
                       off_t offset);

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

       preadv(), pwritev(): _BSD_SOURCE

DESCRIPTION top

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

       The writev() system call writes iovcnt buffers of data described by iov to
       the file associated with the file descriptor 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() system call works just like read(2) except that multiple
       buffers are filled.

       The writev() system call 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.)
       Similarly, 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 single 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)).

preadv() and pwritev()

       The preadv() system call combines the functionality of readv() and
       pread(2).  It performs the same task as readv(), but adds a fourth
       argument, offset, which specifies the file offset at which the input
       operation is to be performed.

       The pwritev() system call combines the functionality of writev() and
       pwrite(2).  It performs the same task as writev(), but adds a fourth
       argument, offset, which specifies the file offset at which the output
       operation is to be performed.

       The file offset is not changed by these system calls.  The file referred to
       by fd must be capable of seeking.

RETURN VALUE top

       On success, readv() and preadv() return the number of bytes read; writev()
       and pwritev() return the number of bytes written.  On error, -1 is
       returned, and errno is set appropriately.

ERRORS top

       The errors are as given for read(2) and write(2).  Furthermore, preadv()
       and pwritev() can also fail for the same reasons as lseek(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.

VERSIONS top

       preadv() and pwritev() first appeared in Linux 2.6.30; library support was
       added in glibc 2.10.

CONFORMING TO top

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

       preadv(), pwritev(): nonstandard, but present also on the modern BSDs.

NOTES top

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          top
       It is not advisable to mix calls to 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          top
       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          top
       pread(2), read(2), write(2)

COLOPHON          top
       This page is part of release 3.45 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                               2010-11-17                            READV(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


proc(5) - Linux manual page

NAME | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PROC(5)                      Linux Programmer's Manual                     PROC(5)

NAME top

       proc - process information pseudo-file system

DESCRIPTION top

       The proc file system is a pseudo-file system which is used as an interface
       to kernel data structures.  It is commonly mounted at /proc.  Most of it is
       read-only, but some files allow kernel variables to be changed.

       The following outline gives a quick tour through the /proc hierarchy.

       /proc/[pid]
              There is a numerical subdirectory for each running process; the
              subdirectory is named by the process ID.  Each such subdirectory
              contains the following pseudo-files and directories.

       /proc/[pid]/auxv (since 2.6.0-test7)
              This contains the contents of the ELF interpreter information passed
              to the process at exec time.  The format is one unsigned long ID
              plus one unsigned long value for each entry.  The last entry
              contains two zeros.

       /proc/[pid]/cgroup (since Linux 2.6.24)
              This file describes control groups to which the process/task
              belongs.  For each cgroup hierarchy there is one entry containing
              colon-separated fields of the form:

                  5:cpuacct,cpu,cpuset:/daemons

              The colon-separated fields are, from left to right:

                  1. hierarchy ID number

                  2. set of subsystems bound to the hierarchy

                  3. control group in the hierarchy to which the process belongs

              This file is only present if the CONFIG_CGROUPS kernel configuration
              option is enabled.

       /proc/[pid]/cmdline
              This holds the complete command line for the process, unless the
              process is a zombie.  In the latter case, there is nothing in this
              file: that is, a read on this file will return 0 characters.  The
              command-line arguments appear in this file as a set of strings
              separated by null bytes ('\0'), with a further null byte after the
              last string.

       /proc/[pid]/coredump_filter (since kernel 2.6.23)
              See core(5).

       /proc/[pid]/cpuset (since kernel 2.6.12)
              See cpuset(7).

       /proc/[pid]/cwd
              This is a symbolic link to the current working directory of the
              process.  To find out the current working directory of process 20,
              for instance, you can do this:

                  $ cd /proc/20/cwd; /bin/pwd

              Note that the pwd command is often a shell built-in, and might not
              work properly.  In bash(1), you may use pwd -P.

              In a multithreaded process, the contents of this symbolic link are
              not available if the main thread has already terminated (typically
              by calling pthread_exit(3)).

       /proc/[pid]/environ
              This file contains the environment for the process.  The entries are
              separated by null bytes ('\0'), and there may be a null byte at the
              end.  Thus, to print out the environment of process 1, you would do:

                  $ (cat /proc/1/environ; echo) | tr '\000' '\n'

       /proc/[pid]/exe
              Under Linux 2.2 and later, this file is a symbolic link containing
              the actual pathname of the executed command.  This symbolic link can
              be dereferenced normally; attempting to open it will open the
              executable.  You can even type /proc/[pid]/exe to run another copy
              of the same executable as is being run by process [pid].  In a
              multithreaded process, the contents of this symbolic link are not
              available if the main thread has already terminated (typically by
              calling pthread_exit(3)).

              Under Linux 2.0 and earlier /proc/[pid]/exe is a pointer to the
              binary which was executed, and appears as a symbolic link.  A
              readlink(2) call on this file under Linux 2.0 returns a string in
              the format:

                  [device]:inode

              For example, [0301]:1502 would be inode 1502 on device major 03
              (IDE, MFM, etc. drives) minor 01 (first partition on the first
              drive).

              find(1) with the -inum option can be used to locate the file.

       /proc/[pid]/fd
              This is a subdirectory containing one entry for each file which the
              process has open, named by its file descriptor, and which is a
              symbolic link to the actual file.  Thus, 0 is standard input, 1
              standard output, 2 standard error, etc.

              In a multithreaded process, the contents of this directory are not
              available if the main thread has already terminated (typically by
              calling pthread_exit(3)).

              Programs that will take a filename as a command-line argument, but
              will not take input from standard input if no argument is supplied,
              or that write to a file named as a command-line argument, but will
              not send their output to standard output if no argument is supplied,
              can nevertheless be made to use standard input or standard out using
              /proc/[pid]/fd.  For example, assuming that -i is the flag
              designating an input file and -o is the flag designating an output
              file:

                  $ foobar -i /proc/self/fd/0 -o /proc/self/fd/1 ...

              and you have a working filter.

              /proc/self/fd/N is approximately the same as /dev/fd/N in some UNIX
              and UNIX-like systems.  Most Linux MAKEDEV scripts symbolically link
              /dev/fd to /proc/self/fd, in fact.

              Most systems provide symbolic links /dev/stdin, /dev/stdout, and
              /dev/stderr, which respectively link to the files 0, 1, and 2 in
              /proc/self/fd.  Thus the example command above could be written as:

                  $ foobar -i /dev/stdin -o /dev/stdout ...

       /proc/[pid]/fdinfo/ (since kernel 2.6.22)
              This is a subdirectory containing one entry for each file which the
              process has open, named by its file descriptor.  The contents of
              each file can be read to obtain information about the corresponding
              file descriptor, for example:

                  $ cat /proc/12015/fdinfo/4
                  pos:    1000
                  flags:  01002002

              The pos field is a decimal number showing the current file offset.
              The flags field is an octal number that displays the file access
              mode and file status flags (see open(2)).

              The files in this directory are readable only by the owner of the
              process.

       /proc/[pid]/limits (since kernel 2.6.24)
              This file displays the soft limit, hard limit, and units of
              measurement for each of the process's resource limits (see
              getrlimit(2)).  Up to and including Linux 2.6.35, this file is
              protected to only allow reading by the real UID of the process.
              Since Linux 2.6.36, this file is readable file is readable by all
              users on the system.

       /proc/[pid]/maps
              A file containing the currently mapped memory regions and their
              access permissions.

              The format is:

              address           perms offset  dev   inode   pathname
              08048000-08056000 r-xp 00000000 03:0c 64593   /usr/sbin/gpm
              08056000-08058000 rw-p 0000d000 03:0c 64593   /usr/sbin/gpm
              08058000-0805b000 rwxp 00000000 00:00 0
              40000000-40013000 r-xp 00000000 03:0c 4165    /lib/ld-2.2.4.so
              40013000-40015000 rw-p 00012000 03:0c 4165    /lib/ld-2.2.4.so
              4001f000-40135000 r-xp 00000000 03:0c 45494   /lib/libc-2.2.4.so
              40135000-4013e000 rw-p 00115000 03:0c 45494   /lib/libc-2.2.4.so
              4013e000-40142000 rw-p 00000000 00:00 0
              bffff000-c0000000 rwxp 00000000 00:00 0

              where "address" is the address space in the process that it
              occupies, "perms" is a set of permissions:

                   r = read
                   w = write
                   x = execute
                   s = shared
                   p = private (copy on write)

              "offset" is the offset into the file/whatever, "dev" is the device
              (major:minor), and "inode" is the inode on that device.  0 indicates
              that no inode is associated with the memory region, as the case
              would be with BSS (uninitialized data).

              Under Linux 2.0 there is no field giving pathname.

       /proc/[pid]/mem
              This file can be used to access the pages of a process's memory
              through open(2), read(2), and lseek(2).

       /proc/[pid]/mountinfo (since Linux 2.6.26)
              This file contains information about mount points.  It contains
              lines of the form:

              36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root rw,errors=continue
              (1)(2)(3)   (4)   (5)      (6)      (7)   (8) (9)   (10)         (11)

              The numbers in parentheses are labels for the descriptions below:

              (1)  mount ID: unique identifier of the mount (may be reused after
                   umount(2)).

              (2)  parent ID: ID of parent mount (or of self for the top of the
                   mount tree).

              (3)  major:minor: value of st_dev for files on file system (see
                   stat(2)).

              (4)  root: root of the mount within the file system.

              (5)  mount point: mount point relative to the process's root.

              (6)  mount options: per-mount options.

              (7)  optional fields: zero or more fields of the form "tag[:value]".

              (8)  separator: marks the end of the optional fields.

              (9)  file system type: name of file system in the form
                   "type[.subtype]".

              (10) mount source: file system-specific information or "none".

              (11) super options: per-super block options.

              Parsers should ignore all unrecognized optional fields.  Currently
              the possible optional fields are:

                   shared:X          mount is shared in peer group X

                   master:X          mount is slave to peer group X

                   propagate_from:X  mount is slave and receives propagation from
                                     peer group X (*)

                   unbindable        mount is unbindable

              (*) X is the closest dominant peer group under the process's root.
              If X is the immediate master of the mount, or if there is no
              dominant peer group under the same root, then only the "master:X"
              field is present and not the "propagate_from:X" field.

              For more information on mount propagation see:
              Documentation/filesystems/sharedsubtree.txt in the Linux kernel
              source tree.

       /proc/[pid]/mounts (since Linux 2.4.19)
              This is a list of all the file systems currently mounted in the
              process's mount namespace.  The format of this file is documented in
              fstab(5).  Since kernel version 2.6.15, this file is pollable: after
              opening the file for reading, a change in this file (i.e., a file
              system mount or unmount) causes select(2) to mark the file
              descriptor as readable, and poll(2) and epoll_wait(2) mark the file
              as having an error condition.

       /proc/[pid]/mountstats (since Linux 2.6.17)
              This file exports information (statistics, configuration
              information) about the mount points in the process's name space.
              Lines in this file have the form:

              device /dev/sda7 mounted on /home with fstype ext3 [statistics]
              (       1      )            ( 2 )             (3 ) (4)

              The fields in each line are:

              (1)  The name of the mounted device (or "nodevice" if there is no
                   corresponding device).

              (2)  The mount point within the file system tree.

              (3)  The file system type.

              (4)  Optional statistics and configuration information.  Currently
                   (as at Linux 2.6.26), only NFS file systems export information
                   via this field.

              This file is only readable by the owner of the process.

       /proc/[pid]/ns/ (since Linux 3.0)
              This is a subdirectory containing one entry for each namespace that
              supports being manipulated by setns(2).  For information about
              namespaces, see clone(2).

       /proc/[pid]/ns/ipc (since Linux 3.0)
              Bind mounting this file (see mount(2)) to somewhere else in the
              filesystem keeps the IPC namespace of the process specified by pid
              alive even if all processes currently in the namespace terminate.

              Opening this file returns a file handle for the IPC namespace of the
              process specified by pid.  As long as this file descriptor remains
              open, the IPC namespace will remain alive, even if all processes in
              the namespace terminate.  The file descriptor can be passed to
              setns(2).

       /proc/[pid]/ns/net (since Linux 3.0)
              Bind mounting this file (see mount(2)) to somewhere else in the
              filesystem keeps the network namespace of the process specified by
              pid alive even if all processes in the namespace terminate.

              Opening this file returns a file handle for the network namespace of
              the process specified by pid.  As long as this file descriptor
              remains open, the network namespace will remain alive, even if all
              processes in the namespace terminate.  The file descriptor can be
              passed to setns(2).

       /proc/[pid]/ns/uts (since Linux 3.0)
              Bind mounting this file (see mount(2)) to somewhere else in the
              filesystem keeps the UTS namespace of the process specified by pid
              alive even if all processes currently in the namespace terminate.

              Opening this file returns a file handle for the UTS namespace of the
              process specified by pid.  As long as this file descriptor remains
              open, the UTS namespace will remain alive, even if all processes in
              the namespace terminate.  The file descriptor can be passed to
              setns(2).

       /proc/[pid]/numa_maps (since Linux 2.6.14)
              See numa(7).

       /proc/[pid]/oom_adj (since Linux 2.6.11)
              This file can be used to adjust the score used to select which
              process should be killed in an out-of-memory (OOM) situation.  The
              kernel uses this value for a bit-shift operation of the process's
              oom_score value: valid values are in the range -16 to +15, plus the
              special value -17, which disables OOM-killing altogether for this
              process.  A positive score increases the likelihood of this process
              being killed by the OOM-killer; a negative score decreases the
              likelihood.  The default value for this file is 0; a new process
              inherits its parent's oom_adj setting.  A process must be privileged
              (CAP_SYS_RESOURCE) to update this file.

       /proc/[pid]/oom_score (since Linux 2.6.11)
              This file displays the current score that the kernel gives to this
              process for the purpose of selecting a process for the OOM-killer.
              A higher score means that the process is more likely to be selected
              by the OOM-killer.  The basis for this score is the amount of memory
              used by the process, with increases (+) or decreases (-) for factors
              including:

              * whether the process creates a lot of children using fork(2) (+);

              * whether the process has been running a long time, or has used a
                lot of CPU time (-);

              * whether the process has a low nice value (i.e., > 0) (+);

              * whether the process is privileged (-); and

              * whether the process is making direct hardware access (-).

              The oom_score also reflects the bit-shift adjustment specified by
              the oom_adj setting for the process.

       /proc/[pid]/root
              UNIX and Linux support the idea of a per-process root of the file
              system, set by the chroot(2) system call.  This file is a symbolic
              link that points to the process's root directory, and behaves as
              exe, fd/*, etc. do.

              In a multithreaded process, the contents of this symbolic link are
              not available if the main thread has already terminated (typically
              by calling pthread_exit(3)).

       /proc/[pid]/smaps (since Linux 2.6.14)
              This file shows memory consumption for each of the process's
              mappings.  For each of mappings there is a series of lines such as
              the following:

                  08048000-080bc000 r-xp 00000000 03:02 13130      /bin/bash
                  Size:               464 kB
                  Rss:                424 kB
                  Shared_Clean:       424 kB
                  Shared_Dirty:         0 kB
                  Private_Clean:        0 kB
                  Private_Dirty:        0 kB

              The first of these lines shows the same information as is displayed
              for the mapping in /proc/[pid]/maps.  The remaining lines show the
              size of the mapping, the amount of the mapping that is currently
              resident in RAM, the number of clean and dirty shared pages in the
              mapping, and the number of clean and dirty private pages in the
              mapping.

              This file is only present if the CONFIG_MMU kernel configuration
              option is enabled.

       /proc/[pid]/stat
              Status information about the process.  This is used by ps(1).  It is
              defined in /usr/src/linux/fs/proc/array.c.

              The fields, in order, with their proper scanf(3) format specifiers,
              are:

              pid %d      The process ID.

              comm %s     The filename of the executable, in parentheses.  This is
                          visible whether or not the executable is swapped out.

              state %c    One character from the string "RSDZTW" where R is
                          running, S is sleeping in an interruptible wait, D is
                          waiting in uninterruptible disk sleep, Z is zombie, T is
                          traced or stopped (on a signal), and W is paging.

              ppid %d     The PID of the parent.

              pgrp %d     The process group ID of the process.

              session %d  The session ID of the process.

              tty_nr %d   The controlling terminal of the process.  (The minor
                          device number is contained in the combination of bits 31
                          to 20 and 7 to 0; the major device number is in bits 15
                          to 8.)

              tpgid %d    The ID of the foreground process group of the
                          controlling terminal of the process.

              flags %u (%lu before Linux 2.6.22)
                          The kernel flags word of the process.  For bit meanings,
                          see the PF_* defines in the Linux kernel source file
                          include/linux/sched.h.  Details depend on the kernel
                          version.

              minflt %lu  The number of minor faults the process has made which
                          have not required loading a memory page from disk.

              cminflt %lu The number of minor faults that the process's waited-for
                          children have made.

              majflt %lu  The number of major faults the process has made which
                          have required loading a memory page from disk.

              cmajflt %lu The number of major faults that the process's waited-for
                          children have made.

              utime %lu   Amount of time that this process has been scheduled in
                          user mode, measured in clock ticks (divide by
                          sysconf(_SC_CLK_TCK)).  This includes guest time,
                          guest_time (time spent running a virtual CPU, see
                          below), so that applications that are not aware of the
                          guest time field do not lose that time from their
                          calculations.

              stime %lu   Amount of time that this process has been scheduled in
                          kernel mode, measured in clock ticks (divide by
                          sysconf(_SC_CLK_TCK)).

              cutime %ld  Amount of time that this process's waited-for children
                          have been scheduled in user mode, measured in clock
                          ticks (divide by sysconf(_SC_CLK_TCK)).  (See also
                          times(2).)  This includes guest time, cguest_time (time
                          spent running a virtual CPU, see below).

              cstime %ld  Amount of time that this process's waited-for children
                          have been scheduled in kernel mode, measured in clock
                          ticks (divide by sysconf(_SC_CLK_TCK)).

              priority %ld
                          (Explanation for Linux 2.6) For processes running a
                          real-time scheduling policy (policy below; see
                          sched_setscheduler(2)), this is the negated scheduling
                          priority, minus one; that is, a number in the range -2
                          to -100, corresponding to real-time priorities 1 to 99.
                          For processes running under a non-real-time scheduling
                          policy, this is the raw nice value (setpriority(2)) as
                          represented in the kernel.  The kernel stores nice
                          values as numbers in the range 0 (high) to 39 (low),
                          corresponding to the user-visible nice range of -20 to
                          19.

                          Before Linux 2.6, this was a scaled value based on the
                          scheduler weighting given to this process.

              nice %ld    The nice value (see setpriority(2)), a value in the
                          range 19 (low priority) to -20 (high priority).

              num_threads %ld
                          Number of threads in this process (since Linux 2.6).
                          Before kernel 2.6, this field was hard coded to 0 as a
                          placeholder for an earlier removed field.

              itrealvalue %ld
                          The time in jiffies before the next SIGALRM is sent to
                          the process due to an interval timer.  Since kernel
                          2.6.17, this field is no longer maintained, and is hard
                          coded as 0.

              starttime %llu (was %lu before Linux 2.6)
                          The time the process started after system boot.  In
                          kernels before Linux 2.6, this value was expressed in
                          jiffies.  Since Linux 2.6, the value is expressed in
                          clock ticks (divide by sysconf(_SC_CLK_TCK)).

              vsize %lu   Virtual memory size in bytes.

              rss %ld     Resident Set Size: number of pages the process has in
                          real memory.  This is just the pages which count toward
                          text, data, or stack space.  This does not include pages
                          which have not been demand-loaded in, or which are
                          swapped out.

              rsslim %lu  Current soft limit in bytes on the rss of the process;
                          see the description of RLIMIT_RSS in getrlimit(2).

              startcode %lu
                          The address above which program text can run.

              endcode %lu The address below which program text can run.

              startstack %lu
                          The address of the start (i.e., bottom) of the stack.

              kstkesp %lu The current value of ESP (stack pointer), as found in
                          the kernel stack page for the process.

              kstkeip %lu The current EIP (instruction pointer).

              signal %lu  The bitmap of pending signals, displayed as a decimal
                          number.  Obsolete, because it does not provide
                          information on real-time signals; use /proc/[pid]/status
                          instead.

              blocked %lu The bitmap of blocked signals, displayed as a decimal
                          number.  Obsolete, because it does not provide
                          information on real-time signals; use /proc/[pid]/status
                          instead.

              sigignore %lu
                          The bitmap of ignored signals, displayed as a decimal
                          number.  Obsolete, because it does not provide
                          information on real-time signals; use /proc/[pid]/status
                          instead.

              sigcatch %lu
                          The bitmap of caught signals, displayed as a decimal
                          number.  Obsolete, because it does not provide
                          information on real-time signals; use /proc/[pid]/status
                          instead.

              wchan %lu   This is the "channel" in which the process is waiting.
                          It is the address of a system call, and can be looked up
                          in a namelist if you need a textual name.  (If you have
                          an up-to-date /etc/psdatabase, then try ps -l to see the
                          WCHAN field in action.)

              nswap %lu   Number of pages swapped (not maintained).

              cnswap %lu  Cumulative nswap for child processes (not maintained).

              exit_signal %d (since Linux 2.1.22)
                          Signal to be sent to parent when we die.

              processor %d (since Linux 2.2.8)
                          CPU number last executed on.

              rt_priority %u (since Linux 2.5.19; was %lu before Linux 2.6.22)
                          Real-time scheduling priority, a number in the range 1
                          to 99 for processes scheduled under a real-time policy,
                          or 0, for non-real-time processes (see
                          sched_setscheduler(2)).

              policy %u (since Linux 2.5.19; was %lu before Linux 2.6.22)
                          Scheduling policy (see sched_setscheduler(2)).  Decode
                          using the SCHED_* constants in linux/sched.h.

              delayacct_blkio_ticks %llu (since Linux 2.6.18)
                          Aggregated block I/O delays, measured in clock ticks
                          (centiseconds).

              guest_time %lu (since Linux 2.6.24)
                          Guest time of the process (time spent running a virtual
                          CPU for a guest operating system), measured in clock
                          ticks (divide by sysconf(_SC_CLK_TCK)).

              cguest_time %ld (since Linux 2.6.24)
                          Guest time of the process's children, measured in clock
                          ticks (divide by sysconf(_SC_CLK_TCK)).

       /proc/[pid]/statm
              Provides information about memory usage, measured in pages.  The
              columns are:

                  size       total program size
                             (same as VmSize in /proc/[pid]/status)
                  resident   resident set size
                             (same as VmRSS in /proc/[pid]/status)
                  share      shared pages (from shared mappings)
                  text       text (code)
                  lib        library (unused in Linux 2.6)
                  data       data + stack
                  dt         dirty pages (unused in Linux 2.6)

       /proc/[pid]/status
              Provides much of the information in /proc/[pid]/stat and
              /proc/[pid]/statm in a format that's easier for humans to parse.
              Here's an example:

                  $ cat /proc/$$/status
                  Name:   bash
                  State:  S (sleeping)
                  Tgid:   3515
                  Pid:    3515
                  PPid:   3452
                  TracerPid:      0
                  Uid:    1000    1000    1000    1000
                  Gid:    100     100     100     100
                  FDSize: 256
                  Groups: 16 33 100
                  VmPeak:     9136 kB
                  VmSize:     7896 kB
                  VmLck:         0 kB
                  VmHWM:      7572 kB
                  VmRSS:      6316 kB
                  VmData:     5224 kB
                  VmStk:        88 kB
                  VmExe:       572 kB
                  VmLib:      1708 kB
                  VmPTE:        20 kB
                  Threads:        1
                  SigQ:   0/3067
                  SigPnd: 0000000000000000
                  ShdPnd: 0000000000000000
                  SigBlk: 0000000000010000
                  SigIgn: 0000000000384004
                  SigCgt: 000000004b813efb
                  CapInh: 0000000000000000
                  CapPrm: 0000000000000000
                  CapEff: 0000000000000000
                  CapBnd: ffffffffffffffff
                  Cpus_allowed:   00000001
                  Cpus_allowed_list:      0
                  Mems_allowed:   1
                  Mems_allowed_list:      0
                  voluntary_ctxt_switches:        150
                  nonvoluntary_ctxt_switches:     545

              The fields are as follows:

              * Name: Command run by this process.

              * State: Current state of the process.  One of "R (running)", "S
                (sleeping)", "D (disk sleep)", "T (stopped)", "T (tracing stop)",
                "Z (zombie)", or "X (dead)".

              * Tgid: Thread group ID (i.e., Process ID).

              * Pid: Thread ID (see gettid(2)).

              * PPid: PID of parent process.

              * TracerPid: PID of process tracing this process (0 if not being
                traced).

              * Uid, Gid: Real, effective, saved set, and file system UIDs (GIDs).

              * FDSize: Number of file descriptor slots currently allocated.

              * Groups: Supplementary group list.

              * VmPeak: Peak virtual memory size.

              * VmSize: Virtual memory size.

              * VmLck: Locked memory size (see mlock(3)).

              * VmHWM: Peak resident set size ("high water mark").

              * VmRSS: Resident set size.

              * VmData, VmStk, VmExe: Size of data, stack, and text segments.

              * VmLib: Shared library code size.

              * VmPTE: Page table entries size (since Linux 2.6.10).

              * Threads: Number of threads in process containing this thread.

              * SigQ: This field contains two slash-separated numbers that relate
                to queued signals for the real user ID of this process.  The first
                of these is the number of currently queued signals for this real
                user ID, and the second is the resource limit on the number of
                queued signals for this process (see the description of
                RLIMIT_SIGPENDING in getrlimit(2)).

              * SigPnd, ShdPnd: Number of signals pending for thread and for
                process as a whole (see pthreads(7) and signal(7)).

              * SigBlk, SigIgn, SigCgt: Masks indicating signals being blocked,
                ignored, and caught (see signal(7)).

              * CapInh, CapPrm, CapEff: Masks of capabilities enabled in
                inheritable, permitted, and effective sets (see capabilities(7)).

              * CapBnd: Capability Bounding set (since kernel 2.6.26, see
                capabilities(7)).

              * Cpus_allowed: Mask of CPUs on which this process may run (since
                Linux 2.6.24, see cpuset(7)).

              * Cpus_allowed_list: Same as previous, but in "list format" (since
                Linux 2.6.26, see cpuset(7)).

              * Mems_allowed: Mask of memory nodes allowed to this process (since
                Linux 2.6.24, see cpuset(7)).

              * Mems_allowed_list: Same as previous, but in "list format" (since
                Linux 2.6.26, see cpuset(7)).

              * voluntary_context_switches, nonvoluntary_context_switches: Number
                of voluntary and involuntary context switches (since Linux
                2.6.23).

       /proc/[pid]/task (since Linux 2.6.0-test6)
              This is a directory that contains one subdirectory for each thread
              in the process.  The name of each subdirectory is the numerical
              thread ID ([tid]) of the thread (see gettid(2)).  Within each of
              these subdirectories, there is a set of files with the same names
              and contents as under the /proc/[pid] directories.  For attributes
              that are shared by all threads, the contents for each of the files
              under the task/[tid] subdirectories will be the same as in the
              corresponding file in the parent /proc/[pid] directory (e.g., in a
              multithreaded process, all of the task/[tid]/cwd files will have the
              same value as the /proc/[pid]/cwd file in the parent directory,
              since all of the threads in a process share a working directory).
              For attributes that are distinct for each thread, the corresponding
              files under task/[tid] may have different values (e.g., various
              fields in each of the task/[tid]/status files may be different for
              each thread).

              In a multithreaded process, the contents of the /proc/[pid]/task
              directory are not available if the main thread has already
              terminated (typically by calling pthread_exit(3)).

       /proc/apm
              Advanced power management version and battery information when
              CONFIG_APM is defined at kernel compilation time.

       /proc/bus
              Contains subdirectories for installed busses.

       /proc/bus/pccard
              Subdirectory for PCMCIA devices when CONFIG_PCMCIA is set at kernel
              compilation time.

       /proc/bus/pccard/drivers

       /proc/bus/pci
              Contains various bus subdirectories and pseudo-files containing
              information about PCI busses, installed devices, and device drivers.
              Some of these files are not ASCII.

       /proc/bus/pci/devices
              Information about PCI devices.  They may be accessed through
              lspci(8) and setpci(8).

       /proc/cmdline
              Arguments passed to the Linux kernel at boot time.  Often done via a
              boot manager such as lilo(8) or grub(8).

       /proc/config.gz (since Linux 2.6)
              This file exposes the configuration options that were used to build
              the currently running kernel, in the same format as they would be
              shown in the .config file that resulted when configuring the kernel
              (using make xconfig, make config, or similar).  The file contents
              are compressed; view or search them using zcat(1), zgrep(1), etc.
              As long as no changes have been made to the following file, the
              contents of /proc/config.gz are the same as those provided by :

                  cat /lib/modules/$(uname -r)/build/.config

              /proc/config.gz is only provided if the kernel is configured with
              CONFIG_IKCONFIG_PROC.

       /proc/cpuinfo
              This is a collection of CPU and system architecture dependent items,
              for each supported architecture a different list.  Two common
              entries are processor which gives CPU number and bogomips; a system
              constant that is calculated during kernel initialization.  SMP
              machines have information for each CPU.

       /proc/devices
              Text listing of major numbers and device groups.  This can be used
              by MAKEDEV scripts for consistency with the kernel.

       /proc/diskstats (since Linux 2.5.69)
              This file contains disk I/O statistics for each disk device.  See
              the Linux kernel source file Documentation/iostats.txt for further
              information.

       /proc/dma
              This is a list of the registered ISA DMA (direct memory access)
              channels in use.

       /proc/driver
              Empty subdirectory.

       /proc/execdomains
              List of the execution domains (ABI personalities).

       /proc/fb
              Frame buffer information when CONFIG_FB is defined during kernel
              compilation.

       /proc/filesystems
              A text listing of the file systems which are supported by the
              kernel, namely file systems which were compiled into the kernel or
              whose kernel modules are currently loaded.  (See also
              filesystems(5).)  If a file system is marked with "nodev", this
              means that it does not require a block device to be mounted (e.g.,
              virtual file system, network file system).

              Incidentally, this file may be used by mount(8) when no file system
              is specified and it didn't manage to determine the file system type.
              Then file systems contained in this file are tried (excepted those
              that are marked with "nodev").

       /proc/fs
              Empty subdirectory.

       /proc/ide
              This directory exists on systems with the IDE bus.  There are
              directories for each IDE channel and attached device.  Files
              include:

                  cache              buffer size in KB
                  capacity           number of sectors
                  driver             driver version
                  geometry           physical and logical geometry
                  identify           in hexadecimal
                  media              media type
                  model              manufacturer's model number
                  settings           drive settings
                  smart_thresholds   in hexadecimal
                  smart_values       in hexadecimal

              The hdparm(8) utility provides access to this information in a
              friendly format.

       /proc/interrupts
              This is used to record the number of interrupts per CPU per IO
              device.  Since Linux 2.6.24, for the i386 and x86_64 architectures,
              at least, this also includes interrupts internal to the system (that
              is, not associated with a device as such), such as NMI (nonmaskable
              interrupt), LOC (local timer interrupt), and for SMP systems, TLB
              (TLB flush interrupt), RES (rescheduling interrupt), CAL (remote
              function call interrupt), and possibly others.  Very easy to read
              formatting, done in ASCII.

       /proc/iomem
              I/O memory map in Linux 2.4.

       /proc/ioports
              This is a list of currently registered Input-Output port regions
              that are in use.

       /proc/kallsyms (since Linux 2.5.71)
              This holds the kernel exported symbol definitions used by the
              modules(X) tools to dynamically link and bind loadable modules.  In
              Linux 2.5.47 and earlier, a similar file with slightly different
              syntax was named ksyms.

       /proc/kcore
              This file represents the physical memory of the system and is stored
              in the ELF core file format.  With this pseudo-file, and an
              unstripped kernel (/usr/src/linux/vmlinux) binary, GDB can be used
              to examine the current state of any kernel data structures.

              The total length of the file is the size of physical memory (RAM)
              plus 4KB.

       /proc/kmsg
              This file can be used instead of the syslog(2) system call to read
              kernel messages.  A process must have superuser privileges to read
              this file, and only one process should read this file.  This file
              should not be read if a syslog process is running which uses the
              syslog(2) system call facility to log kernel messages.

              Information in this file is retrieved with the dmesg(1) program.

       /proc/ksyms (Linux 1.1.23-2.5.47)
              See /proc/kallsyms.

       /proc/loadavg
              The first three fields in this file are load average figures giving
              the number of jobs in the run queue (state R) or waiting for disk
              I/O (state D) averaged over 1, 5, and 15 minutes.  They are the same
              as the load average numbers given by uptime(1) and other programs.
              The fourth field consists of two numbers separated by a slash (/).
              The first of these is the number of currently runnable kernel
              scheduling entities (processes, threads).  The value after the slash
              is the number of kernel scheduling entities that currently exist on
              the system.  The fifth field is the PID of the process that was most
              recently created on the system.

       /proc/locks
              This file shows current file locks (flock(2) and fcntl(2)) and
              leases (fcntl(2)).

       /proc/malloc (only up to and including Linux 2.2)
              This file is only present if CONFIG_DEBUG_MALLOC was defined during
              compilation.

       /proc/meminfo
              This file reports statistics about memory usage on the system.  It
              is used by free(1) to report the amount of free and used memory
              (both physical and swap) on the system as well as the shared memory
              and buffers used by the kernel.  Each line of the file consists of a
              parameter name, followed by a colon, the value of the parameter, and
              an option unit of measurement (e.g., "kB").  The list below
              describes the parameter names and the format specifier required to
              read the field value.  Except as noted below, all of the fields have
              been present since at least Linux 2.6.0.  Some fileds are only
              displayed if the kernel was configured with various options; those
              dependencies are noted in the list.

              MemTotal %lu
                     Total usable RAM (i.e. physical RAM minus a few reserved bits
                     and the kernel binary code).

              MemFree %lu
                     The sum of LowFree+HighFree.

              Buffers %lu
                     Relatively temporary storage for raw disk blocks that
                     shouldn't get tremendously large (20MB or so).

              Cached %lu
                     In-memory cache for files read from the disk (the page
                     cache).  Doesn't include SwapCached.

              SwapCached %lu
                     Memory that once was swapped out, is swapped back in but
                     still also is in the swap file.  (If memory pressure is high,
                     these pages don't need to be swapped out again because they
                     are already in the swap file.  This saves I/O.)

              Active %lu
                     Memory that has been used more recently and usually not
                     reclaimed unless absolutely necessary.

              Inactive %lu
                     Memory which has been less recently used.  It is more
                     eligible to be reclaimed for other purposes.

              Active(anon) %lu (since Linux 2.6.28)
                     [To be documented.]

              Inactive(anon) %lu (since Linux 2.6.28)
                     [To be documented.]

              Active(file) %lu (since Linux 2.6.28)
                     [To be documented.]

              Inactive(file) %lu (since Linux 2.6.28)
                     [To be documented.]

              Unevictable %lu (since Linux 2.6.28)
                     (From Linux 2.6.28 to 2.6.30, CONFIG_UNEVICTABLE_LRU was
                     required.)  [To be documented.]

              Mlocked %lu (since Linux 2.6.28)
                     (From Linux 2.6.28 to 2.6.30, CONFIG_UNEVICTABLE_LRU was
                     required.)  [To be documented.]

              HighTotal %lu
                     (Starting with Linux 2.6.19, CONFIG_HIGHMEM is required.)
                     Total amount of highmem.  Highmem is all memory above ~860MB
                     of physical memory.  Highmem areas are for use by user-space
                     programs, or for the page cache.  The kernel must use tricks
                     to access this memory, making it slower to access than
                     lowmem.

              HighFree %lu
                     (Starting with Linux 2.6.19, CONFIG_HIGHMEM is required.)
                     Amount of free highmem.

              LowTotal %lu
                     (Starting with Linux 2.6.19, CONFIG_HIGHMEM is required.)
                     Total amount of lowmem.  Lowmem is memory which can be used
                     for everything that highmem can be used for, but it is also
                     available for the kernel's use for its own data structures.
                     Among many other things, it is where everything from Slab is
                     allocated.  Bad things happen when you're out of lowmem.

              LowFree %lu
                     (Starting with Linux 2.6.19, CONFIG_HIGHMEM is required.)
                     Amount of free lowmem.

              MmapCopy %lu (since Linux 2.6.29)
                     (CONFIG_MMU is required.)  [To be documented.]

              SwapTotal %lu
                     Total amount of swap space available.

              SwapFree %lu
                     Amount of swap space that is currently unused.

              Dirty %lu
                     Memory which is waiting to get written back to the disk.

              Writeback %lu
                     Memory which is actively being written back to the disk.

              AnonPages %lu (since Linux 2.6.18)
                     Non-file backed pages mapped into user-space page tables.

              Mapped %lu
                     Files which have been mmaped, such as libraries.

              Shmem %lu (since Linux 2.6.32)
                     [To be documented.]

              Slab %lu
                     In-kernel data structures cache.

              SReclaimable %lu (since Linux 2.6.19)
                     Part of Slab, that might be reclaimed, such as caches.

              SUnreclaim %lu (since Linux 2.6.19)
                     Part of Slab, that cannot be reclaimed on memory pressure.

              KernelStack %lu (since Linux 2.6.32)
                     Amount of memory allocated to kernel stacks.

              PageTables %lu (since Linux 2.6.18)
                     Amount of memory dedicated to the lowest level of page
                     tables.

              Quicklists %lu (since Linux 2.6.27)
                     (CONFIG_QUICKLIST is required.)  [To be documented.]

              NFS_Unstable %lu (since Linux 2.6.18)
                     NFS pages sent to the server, but not yet committed to stable
                     storage.

              Bounce %lu (since Linux 2.6.18)
                     Memory used for block device "bounce buffers".

              WritebackTmp %lu (since Linux 2.6.26)
                     Memory used by FUSE for temporary writeback buffers.

              CommitLimit %lu (since Linux 2.6.10)
                     Based on the overcommit ratio ('vm.overcommit_ratio'), this
                     is the total amount of  memory currently available to be
                     allocated on the system. This limit is only adhered to if
                     strict overcommit accounting is enabled (mode 2 in
                     /proc/sys/vm/overcommit_ratio).  The CommitLimit is
                     calculated using the following formula:

                         CommitLimit = (overcommit_ratio * Physical RAM) + Swap

                     For example, on a system with 1GB of physical RAM and 7GB of
                     swap with a overcommit_ratio of 30, this formula yields a
                     CommitLimit of 7.3GB.  For more details, see the memory
                     overcommit documentation in the kernel source file
                     Documentation/vm/overcommit-accounting.

              Committed_AS %lu
                     The amount of memory presently allocated on the system.  The
                     committed memory is a sum of all of the memory which has been
                     allocated by processes, even if it has not been "used" by
                     them as of yet.  A process which allocates 1GB of memory
                     (using malloc(3) or similar), but only touches 300MB of that
                     memory will only show up as using 300MB of memory even if it
                     has the address space allocated for the entire 1GB.  This 1GB
                     is memory which has been "committed" to by the VM and can be
                     used at any time by the allocating application.  With strict
                     overcommit enabled on the system (mode 2
                     /proc/sys/vm/overcommit_memory), allocations which would
                     exceed the CommitLimit (detailed above) will not be
                     permitted.  This is useful if one needs to guarantee that
                     processes will not fail due to lack of memory once that
                     memory has been successfully allocated.

              VmallocTotal %lu
                     Total size of vmalloc memory area.

              VmallocUsed %lu
                     Amount of vmalloc area which is used.

              VmallocChunk %lu
                     Largest contiguous block of vmalloc area which is free.

              HardwareCorrupted %lu (since Linux 2.6.32)
                     (CONFIG_MEMORY_FAILURE is required.)  [To be documented.]

              AnonHugePages %lu (since Linux 2.6.38)
                     (CONFIG_TRANSPARENT_HUGEPAGE is required.)  Non-file backed
                     huge pages mapped into user-space page tables.

              HugePages_Total %lu
                     (CONFIG_HUGETLB_PAGE is required.)  The size of the pool of
                     huge pages.

              HugePages_Free %lu
                     (CONFIG_HUGETLB_PAGE is required.)  The number of huge pages
                     in the pool that are not yet allocated.

              HugePages_Rsvd %lu (since Linux 2.6.17)
                     (CONFIG_HUGETLB_PAGE is required.)  This is the number of
                     huge pages for which a commitment to allocate from the pool
                     has been made, but no allocation has yet been made.  These
                     reserved huge pages guarantee that an application will be
                     able to allocate a huge page from the pool of huge pages at
                     fault time.

              HugePages_Surp %lu (since Linux 2.6.24)
                     (CONFIG_HUGETLB_PAGE is required.)  This is the number of
                     huge pages in the pool above the value in
                     /proc/sys/vm/nr_hugepages.  The maximum number of surplus
                     huge pages is controlled by
                     /proc/sys/vm/nr_overcommit_hugepages.

              Hugepagesize %lu
                     (CONFIG_HUGETLB_PAGE is required.)  The size of huge pages.

       /proc/modules
              A text list of the modules that have been loaded by the system.  See
              also lsmod(8).

       /proc/mounts
              Before kernel 2.4.19, this file was a list of all the file systems
              currently mounted on the system.  With the introduction of per-
              process mount namespaces in Linux 2.4.19, this file became a link to
              /proc/self/mounts, which lists the mount points of the process's own
              mount namespace.  The format of this file is documented in fstab(5).

       /proc/mtrr
              Memory Type Range Registers.  See the Linux kernel source file
              Documentation/mtrr.txt for details.

       /proc/net
              various net pseudo-files, all of which give the status of some part
              of the networking layer.  These files contain ASCII structures and
              are, therefore, readable with cat(1).  However, the standard
              netstat(8) suite provides much cleaner access to these files.

       /proc/net/arp
              This holds an ASCII readable dump of the kernel ARP table used for
              address resolutions.  It will show both dynamically learned and
              preprogrammed ARP entries.  The format is:

        IP address     HW type   Flags     HW address          Mask   Device
        192.168.0.50   0x1       0x2       00:50:BF:25:68:F3   *      eth0
        192.168.0.250  0x1       0xc       00:00:00:00:00:00   *      eth0

              Here "IP address" is the IPv4 address of the machine and the "HW
              type" is the hardware type of the address from RFC 826.  The flags
              are the internal flags of the ARP structure (as defined in
              /usr/include/linux/if_arp.h) and the "HW address" is the data link
              layer mapping for that IP address if it is known.

       /proc/net/dev
              The dev pseudo-file contains network device status information.
              This gives the number of received and sent packets, the number of
              errors and collisions and other basic statistics.  These are used by
              the ifconfig(8) program to report device status.  The format is:

 Inter-|   Receive                                                |  Transmit
  face |bytes    packets errs drop fifo frame compressed multicast|bytes    packets errs drop fifo colls carrier compressed
     lo: 2776770   11307    0    0    0     0          0         0  2776770   11307    0    0    0     0       0          0
   eth0: 1215645    2751    0    0    0     0          0         0  1782404    4324    0    0    0   427       0          0
   ppp0: 1622270    5552    1    0    0     0          0         0   354130    5669    0    0    0     0       0          0
   tap0:    7714      81    0    0    0     0          0         0     7714      81    0    0    0     0       0          0

       /proc/net/dev_mcast
              Defined in /usr/src/linux/net/core/dev_mcast.c:
                   indx interface_name  dmi_u dmi_g dmi_address
                   2    eth0            1     0     01005e000001
                   3    eth1            1     0     01005e000001
                   4    eth2            1     0     01005e000001

       /proc/net/igmp
              Internet Group Management Protocol.  Defined in
              /usr/src/linux/net/core/igmp.c.

       /proc/net/rarp
              This file uses the same format as the arp file and contains the
              current reverse mapping database used to provide rarp(8) reverse
              address lookup services.  If RARP is not configured into the kernel,
              this file will not be present.

       /proc/net/raw
              Holds a dump of the RAW socket table.  Much of the information is
              not of use apart from debugging.  The "sl" value is the kernel hash
              slot for the socket, the "local_address" is the local address and
              protocol number pair.  "St" is the internal status of the socket.
              The "tx_queue" and "rx_queue" are the outgoing and incoming data
              queue in terms of kernel memory usage.  The "tr", "tm->when", and
              "rexmits" fields are not used by RAW.  The "uid" field holds the
              effective UID of the creator of the socket.

       /proc/net/snmp
              This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP
              management information bases for an SNMP agent.

       /proc/net/tcp
              Holds a dump of the TCP socket table.  Much of the information is
              not of use apart from debugging.  The "sl" value is the kernel hash
              slot for the socket, the "local_address" is the local address and
              port number pair.  The "rem_address" is the remote address and port
              number pair (if connected).  "St" is the internal status of the
              socket.  The "tx_queue" and "rx_queue" are the outgoing and incoming
              data queue in terms of kernel memory usage.  The "tr", "tm->when",
              and "rexmits" fields hold internal information of the kernel socket
              state and are only useful for debugging.  The "uid" field holds the
              effective UID of the creator of the socket.

       /proc/net/udp
              Holds a dump of the UDP socket table.  Much of the information is
              not of use apart from debugging.  The "sl" value is the kernel hash
              slot for the socket, the "local_address" is the local address and
              port number pair.  The "rem_address" is the remote address and port
              number pair (if connected). "St" is the internal status of the
              socket.  The "tx_queue" and "rx_queue" are the outgoing and incoming
              data queue in terms of kernel memory usage.  The "tr", "tm->when",
              and "rexmits" fields are not used by UDP.  The "uid" field holds the
              effective UID of the creator of the socket.  The format is:

 sl  local_address rem_address   st tx_queue rx_queue tr rexmits  tm->when uid
  1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0
  1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0
  1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0

       /proc/net/unix
              Lists the UNIX domain sockets present within the system and their
              status.  The format is:
              Num RefCount Protocol Flags    Type St Path
               0: 00000002 00000000 00000000 0001 03
               1: 00000001 00000000 00010000 0001 01 /dev/printer

              Here "Num" is the kernel table slot number, "RefCount" is the number
              of users of the socket, "Protocol" is currently always 0, "Flags"
              represent the internal kernel flags holding the status of the
              socket.  Currently, type is always "1" (UNIX domain datagram sockets
              are not yet supported in the kernel).  "St" is the internal state of
              the socket and Path is the bound path (if any) of the socket.

       /proc/partitions
              Contains major and minor numbers of each partition as well as number
              of blocks and partition name.

       /proc/pci
              This is a listing of all PCI devices found during kernel
              initialization and their configuration.

              This file has been deprecated in favor of a new /proc interface for
              PCI (/proc/bus/pci).  It became optional in Linux 2.2 (available
              with CONFIG_PCI_OLD_PROC set at kernel compilation).  It became once
              more nonoptionally enabled in Linux 2.4.  Next, it was deprecated in
              Linux 2.6 (still available with CONFIG_PCI_LEGACY_PROC set), and
              finally removed altogether since Linux 2.6.17.

       /proc/scsi
              A directory with the scsi mid-level pseudo-file and various SCSI
              low-level driver directories, which contain a file for each SCSI
              host in this system, all of which give the status of some part of
              the SCSI IO subsystem.  These files contain ASCII structures and
              are, therefore, readable with cat(1).

              You can also write to some of the files to reconfigure the subsystem
              or switch certain features on or off.

       /proc/scsi/scsi
              This is a listing of all SCSI devices known to the kernel.  The
              listing is similar to the one seen during bootup.  scsi currently
              supports only the add-single-device command which allows root to add
              a hotplugged device to the list of known devices.

              The command

                  echo 'scsi add-single-device 1 0 5 0' > /proc/scsi/scsi

              will cause host scsi1 to scan on SCSI channel 0 for a device on ID 5
              LUN 0.  If there is already a device known on this address or the
              address is invalid, an error will be returned.

       /proc/scsi/[drivername]
              [drivername] can currently be NCR53c7xx, aha152x, aha1542, aha1740,
              aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16,
              qlogic, scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000.
              These directories show up for all drivers that registered at least
              one SCSI HBA.  Every directory contains one file per registered
              host.  Every host-file is named after the number the host was
              assigned during initialization.

              Reading these files will usually show driver and host configuration,
              statistics, etc.

              Writing to these files allows different things on different hosts.
              For example, with the latency and nolatency commands, root can
              switch on and off command latency measurement code in the eata_dma
              driver.  With the lockup and unlock commands, root can control bus
              lockups simulated by the scsi_debug driver.

       /proc/self
              This directory refers to the process accessing the /proc file
              system, and is identical to the /proc directory named by the process
              ID of the same process.

       /proc/slabinfo
              Information about kernel caches.  Since Linux 2.6.16 this file is
              only present if the CONFIG_SLAB kernel configuration option is
              enabled.  The columns in /proc/slabinfo are:

                  cache-name
                  num-active-objs
                  total-objs
                  object-size
                  num-active-slabs
                  total-slabs
                  num-pages-per-slab

              See slabinfo(5) for details.

       /proc/stat
              kernel/system statistics.  Varies with architecture.  Common entries
              include:

              cpu  3357 0 4313 1362393
                     The amount of time, measured in units of USER_HZ (1/100ths of
                     a second on most architectures, use sysconf(_SC_CLK_TCK) to
                     obtain the right value), that the system spent in user mode,
                     user mode with low priority (nice), system mode, and the idle
                     task, respectively.  The last value should be USER_HZ times
                     the second entry in the uptime pseudo-file.

                     In Linux 2.6 this line includes three additional columns:
                     iowait - time waiting for I/O to complete (since 2.5.41); irq
                     - time servicing interrupts (since 2.6.0-test4); softirq -
                     time servicing softirqs (since 2.6.0-test4).

                     Since Linux 2.6.11, there is an eighth column, steal - stolen
                     time, which is the time spent in other operating systems when
                     running in a virtualized environment

                     Since Linux 2.6.24, there is a ninth column, guest, which is
                     the time spent running a virtual CPU for guest operating
                     systems under the control of the Linux kernel.

              page 5741 1808
                     The number of pages the system paged in and the number that
                     were paged out (from disk).

              swap 1 0
                     The number of swap pages that have been brought in and out.

              intr 1462898
                     This line shows counts of interrupts serviced since boot
                     time, for each of the possible system interrupts.  The first
                     column is the total of all interrupts serviced; each
                     subsequent column is the total for a particular interrupt.

              disk_io: (2,0):(31,30,5764,1,2) (3,0):...
                     (major,disk_idx):(noinfo, read_io_ops, blks_read,
                     write_io_ops, blks_written)
                     (Linux 2.4 only)

              ctxt 115315
                     The number of context switches that the system underwent.

              btime 769041601
                     boot time, in seconds since the Epoch, 1970-01-01 00:00:00
                     +0000 (UTC).

              processes 86031
                     Number of forks since boot.

              procs_running 6
                     Number of processes in runnable state.  (Linux 2.5.45
                     onward.)

              procs_blocked 2
                     Number of processes blocked waiting for I/O to complete.
                     (Linux 2.5.45 onward.)

       /proc/swaps
              Swap areas in use.  See also swapon(8).

       /proc/sys
              This directory (present since 1.3.57) contains a number of files and
              subdirectories corresponding to kernel variables.  These variables
              can be read and sometimes modified using the /proc file system, and
              the (deprecated) sysctl(2) system call.

       /proc/sys/abi (since Linux 2.4.10)
              This directory may contain files with application binary
              information.  See the Linux kernel source file
              Documentation/sysctl/abi.txt for more information.

       /proc/sys/debug
              This directory may be empty.

       /proc/sys/dev
              This directory contains device-specific information (e.g.,
              dev/cdrom/info).  On some systems, it may be empty.

       /proc/sys/fs
              This directory contains the files and subdirectories for kernel
              variables related to file systems.

       /proc/sys/fs/binfmt_misc
              Documentation for files in this directory can be found in the Linux
              kernel sources in Documentation/binfmt_misc.txt.

       /proc/sys/fs/dentry-state (since Linux 2.2)
              This file contains information about the status of the directory
              cache (dcache).  The file contains six numbers, nr_dentry,
              nr_unused, age_limit (age in seconds), want_pages (pages requested
              by system) and two dummy values.

              * nr_dentry is the number of allocated dentries (dcache entries).
                This field is unused in Linux 2.2.

              * nr_unused is the number of unused dentries.

              * age_limit is the age in seconds after which dcache entries can be
                reclaimed when memory is short.

              * want_pages is nonzero when the kernel has called
                shrink_dcache_pages() and the dcache isn't pruned yet.

       /proc/sys/fs/dir-notify-enable
              This file can be used to disable or enable the dnotify interface
              described in fcntl(2) on a system-wide basis.  A value of 0 in this
              file disables the interface, and a value of 1 enables it.

       /proc/sys/fs/dquot-max
              This file shows the maximum number of cached disk quota entries.  On
              some (2.4) systems, it is not present.  If the number of free cached
              disk quota entries is very low and you have some awesome number of
              simultaneous system users, you might want to raise the limit.

       /proc/sys/fs/dquot-nr
              This file shows the number of allocated disk quota entries and the
              number of free disk quota entries.

       /proc/sys/fs/epoll (since Linux 2.6.28)
              This directory contains the file max_user_watches, which can be used
              to limit the amount of kernel memory consumed by the epoll
              interface.  For further details, see epoll(7).

       /proc/sys/fs/file-max
              This file defines a system-wide limit on the number of open files
              for all processes.  (See also setrlimit(2), which can be used by a
              process to set the per-process limit, RLIMIT_NOFILE, on the number
              of files it may open.)  If you get lots of error messages about
              running out of file handles, try increasing this value:

                  echo 100000 > /proc/sys/fs/file-max

              The kernel constant NR_OPEN imposes an upper limit on the value that
              may be placed in file-max.

              If you increase /proc/sys/fs/file-max, be sure to increase
              /proc/sys/fs/inode-max to 3-4 times the new value of
              /proc/sys/fs/file-max, or you will run out of inodes.

              Privileged processes (CAP_SYS_ADMIN) can override the file-max
              limit.

       /proc/sys/fs/file-nr
              This (read-only) file gives the number of files presently opened.
              It contains three numbers: the number of allocated file handles; the
              number of free file handles; and the maximum number of file handles.
              The kernel allocates file handles dynamically, but it doesn't free
              them again.  If the number of allocated files is close to the
              maximum, you should consider increasing the maximum.  When the
              number of free file handles is large, you've encountered a peak in
              your usage of file handles and you probably don't need to increase
              the maximum.

       /proc/sys/fs/inode-max
              This file contains the maximum number of in-memory inodes.  On some
              (2.4) systems, it may not be present.  This value should be 3-4
              times larger than the value in file-max, since stdin, stdout and
              network sockets also need an inode to handle them.  When you
              regularly run out of inodes, you need to increase this value.

       /proc/sys/fs/inode-nr
              This file contains the first two values from inode-state.

       /proc/sys/fs/inode-state
              This file contains seven numbers: nr_inodes, nr_free_inodes,
              preshrink, and four dummy values.  nr_inodes is the number of inodes
              the system has allocated.  This can be slightly more than inode-max
              because Linux allocates them one page full at a time.
              nr_free_inodes represents the number of free inodes.  preshrink is
              nonzero when the nr_inodes > inode-max and the system needs to prune
              the inode list instead of allocating more.

       /proc/sys/fs/inotify (since Linux 2.6.13)
              This directory contains files max_queued_events, max_user_instances,
              and max_user_watches, that can be used to limit the amount of kernel
              memory consumed by the inotify interface.  For further details, see
              inotify(7).

       /proc/sys/fs/lease-break-time
              This file specifies the grace period that the kernel grants to a
              process holding a file lease (fcntl(2)) after it has sent a signal
              to that process notifying it that another process is waiting to open
              the file.  If the lease holder does not remove or downgrade the
              lease within this grace period, the kernel forcibly breaks the
              lease.

       /proc/sys/fs/leases-enable
              This file can be used to enable or disable file leases (fcntl(2)) on
              a system-wide basis.  If this file contains the value 0, leases are
              disabled.  A nonzero value enables leases.

       /proc/sys/fs/mqueue (since Linux 2.6.6)
              This directory contains files msg_max, msgsize_max, and queues_max,
              controlling the resources used by POSIX message queues.  See
              mq_overview(7) for details.

       /proc/sys/fs/overflowgid and /proc/sys/fs/overflowuid
              These files allow you to change the value of the fixed UID and GID.
              The default is 65534.  Some file systems only support 16-bit UIDs
              and GIDs, although in Linux UIDs and GIDs are 32 bits.  When one of
              these file systems is mounted with writes enabled, any UID or GID
              that would exceed 65535 is translated to the overflow value before
              being written to disk.

       /proc/sys/fs/pipe-max-size (since Linux 2.6.35)
              The value in this file defines an upper limit for raising the
              capacity of a pipe using the fcntl(2) F_SETPIPE_SZ operation.  This
              limit applies only to unprivileged processes.  The default value for
              this file is 1,048,576.  The value assigned to this file may be
              rounded upward, to reflect the value actually employed for a
              convenient implementation.  To determine the rounded-up value,
              display the contents of this file after assigning a value to it.
              The minimum value that can be assigned to this file is the system
              page size.

       /proc/sys/fs/protected_hardlinks (since Linux 3.6)
              When the value in this file is 0, no restrictions are placed on the
              creation of hard links (i.e., this is the historical behaviour
              before Linux 3.6).  When the value in this file is 1, a hard link
              can be created to a target file only if one of the following
              conditions is true:

              *  The caller has the CAP_FOWNER capability.

              *  The file system UID of the process creating the link matches the
                 owner (UID) of the target file (as described in credentials(7), a
                 process's file system UID is normally the same as its effective
                 UID).

              *  All of the following conditions are true:

                  +o  the target is a regular file;

                  +o  the target file does not have its set-user-ID permission bit
                     enabled;

                  +o  the target file does not have both its set-group-ID and
                     group-executable permission bits enabled; and

                  +o  the caller has permission to read and write the target file
                     (either via the file's permissions mask or because it has
                     suitable capabilities).

              The default value in this file is 0.  Setting the value to 1
              prevents a longstanding class of security issues caused by hard-
              link-based time-of-check, time-of-use races, most commonly seen in
              world-writable directories such as /tmp.  The common method of
              exploiting this flaw is to cross privilege boundaries when following
              a given hard link (i.e., a root process follows a hard link created
              by another user).  Additionally, on systems without separated
              partitions, this stops unauthorized users from "pinning" vulnerable
              set-user-ID and set-group-ID files against being upgraded by the
              administrator, or linking to special files.

       /proc/sys/fs/protected_symlinks (since Linux 3.6)
              When the value in this file is 0, no restrictions are placed on
              following symbolic links (i.e., this is the historical behaviour
              before Linux 3.6).  When the value in this file is 1, symbolic links
              are followed only in the following circumstances:

              *  the file system UID of the process following the link matches the
                 owner (UID) of the symbolic link (as described in credentials(7),
                 a process's file system UID is normally the same as its effective
                 UID);

              *  the link is not in a sticky world-writable directory; or

              *  the symbolic link and and its parent directory have the same
                 owner (UID)

              A system call that fails to follow a symbolic link because of the
              above restrictions returns the error EACCES in errno.

              The default value in this file is 0.  Setting the value to 1 avoids
              a longstanding class of security issues based on time-of-check,
              time-of-use races when accessing symbolic links.

       /proc/sys/fs/suid_dumpable (since Linux 2.6.13)
              The value in this file determines whether core dump files are
              produced for set-user-ID or otherwise protected/tainted binaries.
              Three different integer values can be specified:

              0 (default) This provides the traditional (pre-Linux 2.6.13)
              behavior.  A core dump will not be produced for a process which has
              changed credentials (by calling seteuid(2), setgid(2), or similar,
              or by executing a set-user-ID or set-group-ID program) or whose
              binary does not have read permission enabled.

              1 ("debug") All processes dump core when possible.  The core dump is
              owned by the file system user ID of the dumping process and no
              security is applied.  This is intended for system debugging
              situations only.  Ptrace is unchecked.

              2 ("suidsafe") Any binary which normally would not be dumped (see
              "0" above) is dumped readable by root only.  This allows the user to
              remove the core dump file but not to read it.  For security reasons
              core dumps in this mode will not overwrite one another or other
              files.  This mode is appropriate when administrators are attempting
              to debug problems in a normal environment.

       /proc/sys/fs/super-max
              This file controls the maximum number of superblocks, and thus the
              maximum number of mounted file systems the kernel can have.  You
              only need to increase super-max if you need to mount more file
              systems than the current value in super-max allows you to.

       /proc/sys/fs/super-nr
              This file contains the number of file systems currently mounted.

       /proc/sys/kernel
              This directory contains files controlling a range of kernel
              parameters, as described below.

       /proc/sys/kernel/acct
              This file contains three numbers: highwater, lowwater, and
              frequency.  If BSD-style process accounting is enabled these values
              control its behavior.  If free space on file system where the log
              lives goes below lowwater percent accounting suspends.  If free
              space gets above highwater percent accounting resumes.  frequency
              determines how often the kernel checks the amount of free space
              (value is in seconds).  Default values are 4, 2 and 30.  That is,
              suspend accounting if 2% or less space is free; resume it if 4% or
              more space is free; consider information about amount of free space
              valid for 30 seconds.

       /proc/sys/kernel/cap-bound (from Linux 2.2 to 2.6.24)
              This file holds the value of the kernel capability bounding set
              (expressed as a signed decimal number).  This set is ANDed against
              the capabilities permitted to a process during execve(2).  Starting
              with Linux 2.6.25, the system-wide capability bounding set
              disappeared, and was replaced by a per-thread bounding set; see
              capabilities(7).

       /proc/sys/kernel/core_pattern
              See core(5).

       /proc/sys/kernel/core_uses_pid
              See core(5).

       /proc/sys/kernel/ctrl-alt-del
              This file controls the handling of Ctrl-Alt-Del from the keyboard.
              When the value in this file is 0, Ctrl-Alt-Del is trapped and sent
              to the init(8) program to handle a graceful restart.  When the value
              is greater than zero, Linux's reaction to a Vulcan Nerve Pinch (tm)
              will be an immediate reboot, without even syncing its dirty buffers.
              Note: when a program (like dosemu) has the keyboard in "raw" mode,
              the ctrl-alt-del is intercepted by the program before it ever
              reaches the kernel tty layer, and it's up to the program to decide
              what to do with it.

       /proc/sys/kernel/hotplug
              This file contains the path for the hotplug policy agent.  The
              default value in this file is /sbin/hotplug.

       /proc/sys/kernel/domainname and /proc/sys/kernel/hostname
              can be used to set the NIS/YP domainname and the hostname of your
              box in exactly the same way as the commands domainname(1) and
              hostname(1), that is:

                  # echo 'darkstar' > /proc/sys/kernel/hostname
                  # echo 'mydomain' > /proc/sys/kernel/domainname

              has the same effect as

                  # hostname 'darkstar'
                  # domainname 'mydomain'

              Note, however, that the classic darkstar.frop.org has the hostname
              "darkstar" and DNS (Internet Domain Name Server) domainname
              "frop.org", not to be confused with the NIS (Network Information
              Service) or YP (Yellow Pages) domainname.  These two domain names
              are in general different.  For a detailed discussion see the
              hostname(1) man page.

       /proc/sys/kernel/htab-reclaim
              (PowerPC only) If this file is set to a nonzero value, the PowerPC
              htab (see kernel file Documentation/powerpc/ppc_htab.txt) is pruned
              each time the system hits the idle loop.

       /proc/sys/kernel/kptr_restrict (since Linux 2.6.38)
              The value in this file determines whether kernel addresses are
              exposed via /proc files and other interfaces.  A value of 0 in this
              file imposes no restrictions.  If the value is 1, kernel pointers
              printed using the %pK format specifier will be replaced with zeros
              unless the user has the CAP_SYSLOG capability.  If the value is 2,
              kernel pointers printed using the %pK format specifier will be
              replaced with zeros regardless of the user's capabilities.  The
              initial default value for this file was 1, but the default was
              changed to 0 in Linux 2.6.39.

       /proc/sys/kernel/l2cr
              (PowerPC only) This file contains a flag that controls the L2 cache
              of G3 processor boards.  If 0, the cache is disabled.  Enabled if
              nonzero.

       /proc/sys/kernel/modprobe
              This file contains the path for the kernel module loader.  The
              default value is /sbin/modprobe.  The file is only present if the
              kernel is built with the CONFIG_MODULES (CONFIG_KMOD in Linux 2.6.26
              and earlier) option enabled.  It is described by the Linux kernel
              source file Documentation/kmod.txt (only present in kernel 2.4 and
              earlier).

       /proc/sys/kernel/modules_disabled (since Linux 2.6.31)
              A toggle value indicating if modules are allowed to be loaded in an
              otherwise modular kernel.  This toggle defaults to off (0), but can
              be set true (1).  Once true, modules can be neither loaded nor
              unloaded, and the toggle cannot be set back to false.  The file is
              only present if the kernel is built with the CONFIG_MODULES option
              enabled.

       /proc/sys/kernel/msgmax
              This file defines a system-wide limit specifying the maximum number
              of bytes in a single message written on a System V message queue.

       /proc/sys/kernel/msgmni
              This file defines the system-wide limit on the number of message
              queue identifiers.  (This file is only present in Linux 2.4 onward.)

       /proc/sys/kernel/msgmnb
              This file defines a system-wide parameter used to initialize the
              msg_qbytes setting for subsequently created message queues.  The
              msg_qbytes setting specifies the maximum number of bytes that may be
              written to the message queue.

       /proc/sys/kernel/ostype and /proc/sys/kernel/osrelease
              These files give substrings of /proc/version.

       /proc/sys/kernel/overflowgid and /proc/sys/kernel/overflowuid
              These files duplicate the files /proc/sys/fs/overflowgid and
              /proc/sys/fs/overflowuid.

       /proc/sys/kernel/panic
              This file gives read/write access to the kernel variable
              panic_timeout.  If this is zero, the kernel will loop on a panic; if
              nonzero it indicates that the kernel should autoreboot after this
              number of seconds.  When you use the software watchdog device
              driver, the recommended setting is 60.

       /proc/sys/kernel/panic_on_oops (since Linux 2.5.68)
              This file controls the kernel's behavior when an oops or BUG is
              encountered.  If this file contains 0, then the system tries to
              continue operation.  If it contains 1, then the system delays a few
              seconds (to give klogd time to record the oops output) and then
              panics.  If the /proc/sys/kernel/panic file is also nonzero then the
              machine will be rebooted.

       /proc/sys/kernel/pid_max (since Linux 2.5.34)
              This file specifies the value at which PIDs wrap around (i.e., the
              value in this file is one greater than the maximum PID).  The
              default value for this file, 32768, results in the same range of
              PIDs as on earlier kernels.  On 32-bit platforms, 32768 is the
              maximum value for pid_max.  On 64-bit systems, pid_max can be set to
              any value up to 2^22 (PID_MAX_LIMIT, approximately 4 million).

       /proc/sys/kernel/powersave-nap (PowerPC only)
              This file contains a flag.  If set, Linux-PPC will use the "nap"
              mode of powersaving, otherwise the "doze" mode will be used.

       /proc/sys/kernel/printk
              The four values in this file are console_loglevel,
              default_message_loglevel, minimum_console_level, and
              default_console_loglevel.  These values influence printk() behavior
              when printing or logging error messages.  See syslog(2) for more
              info on the different loglevels.  Messages with a higher priority
              than console_loglevel will be printed to the console.  Messages
              without an explicit priority will be printed with priority
              default_message_level.  minimum_console_loglevel is the minimum
              (highest) value to which console_loglevel can be set.
              default_console_loglevel is the default value for console_loglevel.

       /proc/sys/kernel/pty (since Linux 2.6.4)
              This directory contains two files relating to the number of UNIX 98
              pseudoterminals (see pts(4)) on the system.

       /proc/sys/kernel/pty/max
              This file defines the maximum number of pseudoterminals.

       /proc/sys/kernel/pty/nr
              This read-only file indicates how many pseudoterminals are currently
              in use.

       /proc/sys/kernel/random
              This directory contains various parameters controlling the operation
              of the file /dev/random.  See random(4) for further information.

       /proc/sys/kernel/real-root-dev
              This file is documented in the Linux kernel source file
              Documentation/initrd.txt.

       /proc/sys/kernel/reboot-cmd (Sparc only)
              This file seems to be a way to give an argument to the SPARC
              ROM/Flash boot loader.  Maybe to tell it what to do after rebooting?

       /proc/sys/kernel/rtsig-max
              (Only in kernels up to and including 2.6.7; see setrlimit(2)) This
              file can be used to tune the maximum number of POSIX real-time
              (queued) signals that can be outstanding in the system.

       /proc/sys/kernel/rtsig-nr
              (Only in kernels up to and including 2.6.7.)  This file shows the
              number POSIX real-time signals currently queued.

       /proc/sys/kernel/sem (since Linux 2.4)
              This file contains 4 numbers defining limits for System V IPC
              semaphores.  These fields are, in order:

              SEMMSL  The maximum semaphores per semaphore set.

              SEMMNS  A system-wide limit on the number of semaphores in all
                      semaphore sets.

              SEMOPM  The maximum number of operations that may be specified in a
                      semop(2) call.

              SEMMNI  A system-wide limit on the maximum number of semaphore
                      identifiers.

       /proc/sys/kernel/sg-big-buff
              This file shows the size of the generic SCSI device (sg) buffer.
              You can't tune it just yet, but you could change it at compile time
              by editing include/scsi/sg.h and changing the value of SG_BIG_BUFF.
              However, there shouldn't be any reason to change this value.

       /proc/sys/kernel/shmall
              This file contains the system-wide limit on the total number of
              pages of System V shared memory.

       /proc/sys/kernel/shmmax
              This file can be used to query and set the run-time limit on the
              maximum (System V IPC) shared memory segment size that can be
              created.  Shared memory segments up to 1GB are now supported in the
              kernel.  This value defaults to SHMMAX.

       /proc/sys/kernel/shmmni
              (available in Linux 2.4 and onward) This file specifies the system-
              wide maximum number of System V shared memory segments that can be
              created.

       /proc/sys/kernel/sysrq
              This file controls the functions allowed to be invoked by the SysRq
              key.  By default, the file contains 1 meaning that every possible
              SysRq request is allowed (in older kernel versions, SysRq was
              disabled by default, and you were required to specifically enable it
              at run-time, but this is not the case any more).  Possible values in
              this file are:

                 0 - disable sysrq completely
                 1 - enable all functions of sysrq
                >1 - bitmask of allowed sysrq functions, as follows:
                        2 - enable control of console logging level
                        4 - enable control of keyboard (SAK, unraw)
                        8 - enable debugging dumps of processes etc.
                       16 - enable sync command
                       32 - enable remount read-only
                       64 - enable signalling of processes (term, kill, oom-kill)
                      128 - allow reboot/poweroff
                      256 - allow nicing of all real-time tasks

              This file is only present if the CONFIG_MAGIC_SYSRQ kernel
              configuration option is enabled.  For further details see the Linux
              kernel source file Documentation/sysrq.txt.

       /proc/sys/kernel/version
              This file contains a string like:

                  #5 Wed Feb 25 21:49:24 MET 1998

              The "#5" means that this is the fifth kernel built from this source
              base and the date behind it indicates the time the kernel was built.

       /proc/sys/kernel/threads-max (since Linux 2.3.11)
              This file specifies the system-wide limit on the number of threads
              (tasks) that can be created on the system.

       /proc/sys/kernel/zero-paged (PowerPC only)
              This file contains a flag.  When enabled (nonzero), Linux-PPC will
              pre-zero pages in the idle loop, possibly speeding up
              get_free_pages.

       /proc/sys/net
              This directory contains networking stuff.  Explanations for some of
              the files under this directory can be found in tcp(7) and ip(7).

       /proc/sys/net/core/somaxconn
              This file defines a ceiling value for the backlog argument of
              listen(2); see the listen(2) manual page for details.

       /proc/sys/proc
              This directory may be empty.

       /proc/sys/sunrpc
              This directory supports Sun remote procedure call for network file
              system (NFS).  On some systems, it is not present.

       /proc/sys/vm
              This directory contains files for memory management tuning, buffer
              and cache management.

       /proc/sys/vm/drop_caches (since Linux 2.6.16)
              Writing to this file causes the kernel to drop clean caches,
              dentries and inodes from memory, causing that memory to become free.

              To free pagecache, use echo 1 > /proc/sys/vm/drop_caches; to free
              dentries and inodes, use echo 2 > /proc/sys/vm/drop_caches; to free
              pagecache, dentries and inodes, use echo 3 >
              /proc/sys/vm/drop_caches.

              Because this is a nondestructive operation and dirty objects are not
              freeable, the user should run sync(8) first.

       /proc/sys/vm/legacy_va_layout (since Linux 2.6.9)
              If nonzero, this disables the new 32-bit memory-mapping layout; the
              kernel will use the legacy (2.4) layout for all processes.

       /proc/sys/vm/memory_failure_early_kill (since Linux 2.6.32)
              Control how to kill processes when an uncorrected memory error
              (typically a 2-bit error in a memory module) that cannot be handled
              by the kernel is detected in the background by hardware.  In some
              cases (like the page still having a valid copy on disk), the kernel
              will handle the failure transparently without affecting any
              applications.  But if there is no other up-to-date copy of the data,
              it will kill processes to prevent any data corruptions from
              propagating.

              The file has one of the following values:

              1:  Kill all processes that have the corrupted-and-not-reloadable
                  page mapped as soon as the corruption is detected.  Note this is
                  not supported for a few types of pages, like kernel internally
                  allocated data or the swap cache, but works for the majority of
                  user pages.

              0:  Only unmap the corrupted page from all processes and only kill a
                  process who tries to access it.

              The kill is performed using a SIGBUS signal with si_code set to
              BUS_MCEERR_AO.  Processes can handle this if they want to; see
              sigaction(2) for more details.

              This feature is only active on architectures/platforms with advanced
              machine check handling and depends on the hardware capabilities.

              Applications can override the memory_failure_early_kill setting
              individually with the prctl(2) PR_MCE_KILL operation.

              Only present if the kernel was configured with
              CONFIG_MEMORY_FAILURE.

       /proc/sys/vm/memory_failure_recovery (since Linux 2.6.32)
              Enable memory failure recovery (when supported by the platform)

              1:  Attempt recovery.

              0:  Always panic on a memory failure.

              Only present if the kernel was configured with
              CONFIG_MEMORY_FAILURE.

       /proc/sys/vm/oom_dump_tasks (since Linux 2.6.25)
              Enables a system-wide task dump (excluding kernel threads) to be
              produced when the kernel performs an OOM-killing.  The dump includes
              the following information for each task (thread, process): thread
              ID, real user ID, thread group ID (process ID), virtual memory size,
              resident set size, the CPU that the task is scheduled on, oom_adj
              score (see the description of /proc/[pid]/oom_adj), and command
              name.  This is helpful to determine why the OOM-killer was invoked
              and to identify the rogue task that caused it.

              If this contains the value zero, this information is suppressed.  On
              very large systems with thousands of tasks, it may not be feasible
              to dump the memory state information for each one.  Such systems
              should not be forced to incur a performance penalty in OOM
              situations when the information may not be desired.

              If this is set to nonzero, this information is shown whenever the
              OOM-killer actually kills a memory-hogging task.

              The default value is 0.

       /proc/sys/vm/oom_kill_allocating_task (since Linux 2.6.24)
              This enables or disables killing the OOM-triggering task in out-of-
              memory situations.

              If this is set to zero, the OOM-killer will scan through the entire
              tasklist and select a task based on heuristics to kill.  This
              normally selects a rogue memory-hogging task that frees up a large
              amount of memory when killed.

              If this is set to nonzero, the OOM-killer simply kills the task that
              triggered the out-of-memory condition.  This avoids a possibly
              expensive tasklist scan.

              If /proc/sys/vm/panic_on_oom is nonzero, it takes precedence over
              whatever value is used in /proc/sys/vm/oom_kill_allocating_task.

              The default value is 0.

       /proc/sys/vm/overcommit_memory
              This file contains the kernel virtual memory accounting mode.
              Values are:

                     0: heuristic overcommit (this is the default)
                     1: always overcommit, never check
                     2: always check, never overcommit

              In mode 0, calls of mmap(2) with MAP_NORESERVE are not checked, and
              the default check is very weak, leading to the risk of getting a
              process "OOM-killed".  Under Linux 2.4 any nonzero value implies
              mode 1.  In mode 2 (available since Linux 2.6), the total virtual
              address space on the system is limited to (SS + RAM*(r/100)), where
              SS is the size of the swap space, and RAM is the size of the
              physical memory, and r is the contents of the file
              /proc/sys/vm/overcommit_ratio.

       /proc/sys/vm/overcommit_ratio
              See the description of /proc/sys/vm/overcommit_memory.

       /proc/sys/vm/panic_on_oom (since Linux 2.6.18)
              This enables or disables a kernel panic in an out-of-memory
              situation.

              If this file is set to the value 0, the kernel's OOM-killer will
              kill some rogue process.  Usually, the OOM-killer is able to kill a
              rogue process and the system will survive.

              If this file is set to the value 1, then the kernel normally panics
              when out-of-memory happens.  However, if a process limits
              allocations to certain nodes using memory policies (mbind(2)
              MPOL_BIND) or cpusets (cpuset(7)) and those nodes reach memory
              exhaustion status, one process may be killed by the OOM-killer.  No
              panic occurs in this case: because other nodes' memory may be free,
              this means the system as a whole may not have reached an out-of-
              memory situation yet.

              If this file is set to the value 2, the kernel always panics when an
              out-of-memory condition occurs.

              The default value is 0.  1 and 2 are for failover of clustering.
              Select either according to your policy of failover.

       /proc/sys/vm/swappiness
              The value in this file controls how aggressively the kernel will
              swap memory pages.  Higher values increase aggressiveness, lower
              values decrease aggressiveness.  The default value is 60.

       /proc/sysrq-trigger (since Linux 2.4.21)
              Writing a character to this file triggers the same SysRq function as
              typing ALT-SysRq-<character> (see the description of
              /proc/sys/kernel/sysrq).  This file is normally only writable by
              root.  For further details see the Linux kernel source file
              Documentation/sysrq.txt.

       /proc/sysvipc
              Subdirectory containing the pseudo-files msg, sem and shm.  These
              files list the System V Interprocess Communication (IPC) objects
              (respectively: message queues, semaphores, and shared memory) that
              currently exist on the system, providing similar information to that
              available via ipcs(1).  These files have headers and are formatted
              (one IPC object per line) for easy understanding.  svipc(7) provides
              further background on the information shown by these files.

       /proc/tty
              Subdirectory containing the pseudo-files and subdirectories for tty
              drivers and line disciplines.

       /proc/uptime
              This file contains two numbers: the uptime of the system (seconds),
              and the amount of time spent in idle process (seconds).

       /proc/version
              This string identifies the kernel version that is currently running.
              It includes the contents of /proc/sys/kernel/ostype,
              /proc/sys/kernel/osrelease and /proc/sys/kernel/version.  For
              example:
            Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994

       /proc/vmstat (since Linux 2.6)
              This file displays various virtual memory statistics.

       /proc/zoneinfo (since Linux 2.6.13)
              This file display information about memory zones.  This is useful
              for analyzing virtual memory behavior.

NOTES top

       Many strings (i.e., the environment and command line) are in the internal
       format, with subfields terminated by null bytes ('\0'), so you may find
       that things are more readable if you use od -c or tr "\000" "\n" to read
       them.  Alternatively, echo `cat <file>` works well.

       This manual page is incomplete, possibly inaccurate, and is the kind of
       thing that needs to be updated very often.

SEE ALSO top

       cat(1), dmesg(1), find(1), free(1), ps(1), tr(1), uptime(1), chroot(2),
       mmap(2), readlink(2), syslog(2), slabinfo(5), hier(7), time(7), arp(8),
       hdparm(8), ifconfig(8), init(8), lsmod(8), lspci(8), mount(8), netstat(8),
       procinfo(8), route(8)

       The Linux kernel source files: Documentation/filesystems/proc.txt and
       Documentation/sysctl/vm.txt.

COLOPHON top

       This page is part of release 3.45 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                               2012-11-24                             PROC(5)


process_vm_readv(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PROCESS_VM_READV(2)          Linux Programmer's Manual         PROCESS_VM_READV(2)

NAME top

       process_vm_readv, process_vm_writev - transfer data between process address
       spaces

SYNOPSIS top

       #include <sys/uio.h>

       ssize_t process_vm_readv(pid_t pid,
                                const struct iovec *local_iov,
                                unsigned long liovcnt,
                                const struct iovec *remote_iov,
                                unsigned long riovcnt,
                                unsigned long flags);

       ssize_t process_vm_writev(pid_t pid,
                                 const struct iovec *local_iov,
                                 unsigned long liovcnt,
                                 const struct iovec *remote_iov,
                                 unsigned long riovcnt,
                                 unsigned long flags);

DESCRIPTION top

       These system calls transfer data between the address space of the calling
       process ("the local process") and the process identified by pid ("the
       remote process").  The data moves directly between the address spaces of
       the two processes, without passing through kernel space.

       The process_vm_readv() system call transfers data from the remote process
       to the local process.  The data to be transferred is identified by
       remote_iov and riovcnt: remote_iov is a pointer to an array describing
       address ranges in the process pid, and riovcnt specifies the number of
       elements in remote_iov.  The data is transferred to the locations specified
       by local_iov and liovcnt: local_iov is a pointer to an array describing
       address ranges in the calling process, and liovcnt specifies the number of
       elements in local_iov.

       The process_vm_writev() system call is the converse of
       process_vm_readv()--it transfers data from the local process to the remote
       process.  Other than the direction of the transfer, the arguments liovcnt,
       local_iov, riovcnt, and remote_iov have the same meaning as for
       process_vm_readv().

       The local_iov and remote_iov arguments point 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 */
           };

       Buffers are processed in array order.  This means that process_vm_readv()
       completely fills local_iov[0] before proceeding to local_iov[1], and so on.
       Likewise, remote_iov[0] is completely read before proceeding to
       remote_iov[1], and so on.

       Similarly, process_vm_writev() writes out the entire contents of
       local_iov[0] before proceeding to local_iov[1], and it completely fills
       remote_iov[0] before proceeding to remote_iov[1].

       The lengths of remote_iov[i].iov_len and local_iov[i].iov_len do not have
       to be the same.  Thus, it is possible to split a single local buffer into
       multiple remote buffers, or vice versa.

       The flags argument is currently unused and must be set to 0.

       The values specified in the liovcnt and riovcnt arguments must be less than
       or equal to IOV_MAX (defined in <limits.h> or accessible via the call
       sysconf(_SC_IOV_MAX)).

       The count arguments and local_iov are checked before doing any transfers.
       If the counts are too big, or local_iov is invalid, or the addresses refer
       to regions that are inaccessible to the local process, none of the vectors
       will be processed and an error will be returned immediately.

       Note, however, that these system calls do not check the memory regions in
       the remote process until just before doing the read/write.  Consequently, a
       partial read/write (see RETURN VALUE) may result if one of the remote_iov
       elements points to an invalid memory region in the remote process.  No
       further reads/writes will be attempted beyond that point.  Keep this in
       mind when attempting to read data of unknown length (such as C strings that
       are null-terminated) from a remote process, by avoiding spanning memory
       pages (typically 4KiB) in a single remote iovec element.  (Instead, split
       the remote read into two remote_iov elements and have them merge back into
       a single write local_iov entry.  The first read entry goes up to the page
       boundary, while the second starts on the next page boundary.)

       In order to read from or write to another process, either the caller must
       have the capability CAP_SYS_PTRACE, or the real user ID, effective user ID,
       and saved set-user-ID of the remote process must match the real user ID of
       the caller and the real group ID, effective group ID, and saved set-group-
       ID of the remote process must match the real group ID of the caller.  (The
       permission required is exactly the same as that required to perform a
       ptrace(2) PTRACE_ATTACH on the remote process.)

RETURN VALUE top

       On success, process_vm_readv() returns the number of bytes read and
       process_vm_writev() returns the number of bytes written.  This return value
       may be less than the total number of requested bytes, if a partial
       read/write occurred.  (Partial transfers apply at the granularity of iovec
       elements.  These system calls won't perform a partial transfer that splits
       a single iovec element.)  The caller should check the return value to
       determine whether a partial read/write occurred.

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

ERRORS top

       EINVAL The sum of the iov_len values of either local_iov or remote_iov
              overflows a ssize_t value.

       EINVAL flags is not 0.

       EINVAL liovcnt or riovcnt is too large.

       EFAULT The memory described by local_iov is outside the caller's accessible
              address space.

       EFAULT The memory described by remote_iov is outside the accessible address
              space of the process pid.

       ENOMEM Could not allocate memory for internal copies of the iovec
              structures.

       EPERM  The caller does not have permission to access the address space of
              the process pid.

       ESRCH  No process with ID pid exists.

VERSIONS top

       These system calls were added in Linux 3.2.  Support is provided in glibc
       since version 2.15.

CONFORMING TO top

       These system calls are nonstandard Linux extensions.

NOTES top

       The data transfers performed by process_vm_readv() and process_vm_writev()
       are not guaranteed to be atomic in any way.

       These system calls were designed to permit fast message passing by allowing
       messages to be exchanged with a single copy operation (rather than the
       double copy that would be required when using, for example, shared memory
       or pipes).

EXAMPLE top

       The following code sample demonstrates the use of process_vm_readv().  It
       reads 20 bytes at the address 0x10000 from the process with PID 10 and
       writes the first 10 bytes into buf1 and the second 10 bytes into buf2.

       #include <sys/uio.h>

       int
       main(void)
       {
           struct iovec local[2];
           struct iovec remote[1];
           char buf1[10];
           char buf2[10];
           ssize_t nread;
           pid_t pid = 10;             /* PID of remote process */

           local[0].iov_base = buf1;
           local[0].iov_len = 10;
           local[1].iov_base = buf2;
           local[1].iov_len = 10;
           remote[0].iov_base = (void *) 0x10000;
           remote[1].iov_len = 20;

           nread = process_vm_readv(pid, local, 2, remote, 1, 0);
           if (nread != 20)
               return 1;
           else
               return 0;
       }

SEE ALSO top

       readv(2), writev(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-25                 PROCESS_VM_READV(2)


profil(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PROFIL(3)                    Linux Programmer's Manual                   PROFIL(3)

NAME top

       profil - execution time profile

SYNOPSIS top

       #include <unistd.h>

       int  profil(unsigned short *buf, size_t bufsiz, size_t offset, unsigned int
       scale);

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

       profil(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       This routine provides a means to find out in what areas your program spends
       most of its time.  The argument buf points to bufsiz bytes of core.  Every
       virtual 10 milliseconds, the user's program counter (PC) is examined:
       offset is subtracted and the result is multiplied by scale and divided by
       65536.  If the resulting value is less than bufsiz, then the corresponding
       entry in buf is incremented.  If buf is NULL, profiling is disabled.

RETURN VALUE top

       Zero is always returned.

CONFORMING TO top

       Similar to a call in SVr4 (but not POSIX.1-2001).

BUGS top

       profil() cannot be used on a program that also uses ITIMER_PROF interval
       timers (see setitimer(2)).

       True kernel profiling provides more accurate results.  Libc 4.4 contained a
       kernel patch providing a system call profil.

SEE ALSO top

       gprof(1), setitimer(2), sigaction(2), signal(2)

COLOPHON top

       This page is part of release 3.45 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-26                           PROFIL(3)


program_invocation_name(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

INVOCATION_NAME(3)           Linux Programmer's Manual          INVOCATION_NAME(3)

NAME top

       program_invocation_name,  program_invocation_short_name  - obtain name used
       to invoke calling program

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <errno.h>

       extern char *program_invocation_name;
       extern char *program_invocation_short_name;

DESCRIPTION top

       program_invocation_name contains the name that was used to invoke the
       calling program.  This is the same as the value of argv[0] in main(), with
       the difference that the scope of program_invocation_name is global.

       program_invocation_short_name contains the basename component of name that
       was used to invoke the calling program.  That is, it is the same value as
       program_invocation_name, with all text up to and including the final slash
       (/), if any, removed.

       These variables are automatically initialized by the glibc run-time startup
       code.

CONFORMING TO top

       These variables are GNU extensions, and should not be used in programs
       intended to be portable.

NOTES top

       The Linux-specific /proc/[number]/cmdline file provides access to similar
       information.

SEE ALSO top

       proc(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2006-04-29                  INVOCATION_NAME(3)


protocols(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

PROTOCOLS(5)                 Linux Programmer's Manual                PROTOCOLS(5)

NAME top

       protocols - protocols definition file

DESCRIPTION top

       This file is a plain ASCII file, describing the various DARPA internet
       protocols that are available from the TCP/IP subsystem.  It should be
       consulted instead of using the numbers in the ARPA include files, or, even
       worse, just guessing them.  These numbers will occur in the protocol field
       of any IP header.

       Keep this file untouched since changes would result in incorrect IP
       packages.  Protocol numbers and names are specified by the IANA (Internet
       Assigned Numbers Authority).

       Each line is of the following format:

              protocol number aliases ...

       where the fields are delimited by spaces or tabs.  Empty lines are ignored.
       If a line contains a hash mark (#), the hash mark and the part of the line
       following it are ignored.

       The field descriptions are:

       protocol
              the native name for the protocol.  For example ip, tcp, or udp.

       number the official number for this protocol as it will appear within the
              IP header.

       aliases
              optional aliases for the protocol.

       This file might be distributed over a network using a network-wide naming
       service like Yellow Pages/NIS or BIND/Hesiod.

FILES top

       /etc/protocols
              The protocols definition file.

SEE ALSO top

       getprotoent(3)

       <http://www.iana.org/assignments/protocol-numbers>

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                        PROTOCOLS(5)


psignal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PSIGNAL(3)                   Linux Programmer's Manual                  PSIGNAL(3)

NAME top

       psignal, psiginfo - print signal message

SYNOPSIS top

       #include <signal.h>

       void psignal(int sig, const char *s);
       void psiginfo(const siginfo_t *pinfo, const char *s);

       extern const char *const sys_siglist[];

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

       psignal(): _SVID_SOURCE || _BSD_SOURCE
       psiginfo(): _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
       sys_siglist: _BSD_SOURCE

DESCRIPTION top

       The psignal() function displays a message on stderr consisting of the
       string s, a colon, a space, a string describing the signal number sig, and
       a trailing newline.  If the string s is NULL or empty, the colon and space
       are omitted.  If sig is invalid, the message displayed will indicate an
       unknown signal.

       The psiginfo() function is like psignal(), except that it displays
       information about the signal described by pinfo, which should point to a
       valid siginfo_t structure.  As well as the signal description, psiginfo()
       displays information about the origin of the signal, and other information
       relevant to the signal (e.g., the relevant memory address for hardware-
       generated signals, the child process ID for SIGCHLD, and the user ID and
       process ID of the sender, for signals set using kill(2) or sigqueue(3)).

       The array sys_siglist holds the signal description strings indexed by
       signal number.

RETURN VALUE top

       The psignal() and psiginfo() functions return no value.

VERSIONS top

       The psiginfo() function was added to glibc in version 2.10.

CONFORMING TO top

       POSIX.1-2008, 4.3BSD.

BUGS top

       In glibc versions up to 2.12, psiginfo() had the following bugs:

       *  In some circumstances, a trailing newline is not printed.

       *  Additional details are not displayed for real-time signals.

SEE ALSO top

       sigaction(2), perror(3), strsignal(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-10-06                          PSIGNAL(3)


pthreads(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREADS(7)                  Linux Programmer's Manual                 PTHREADS(7)

NAME top

       pthreads - POSIX threads

DESCRIPTION top

       POSIX.1 specifies a set of interfaces (functions, header files) for
       threaded programming commonly known as POSIX threads, or Pthreads.  A
       single process can contain multiple threads, all of which are executing the
       same program.  These threads share the same global memory (data and heap
       segments), but each thread has its own stack (automatic variables).

       POSIX.1 also requires that threads share a range of other attributes (i.e.,
       these attributes are process-wide rather than per-thread):

       -  process ID

       -  parent process ID

       -  process group ID and session ID

       -  controlling terminal

       -  user and group IDs

       -  open file descriptors

       -  record locks (see fcntl(2))

       -  signal dispositions

       -  file mode creation mask (umask(2))

       -  current directory (chdir(2)) and root directory (chroot(2))

       -  interval timers (setitimer(2)) and POSIX timers (timer_create(2))

       -  nice value (setpriority(2))

       -  resource limits (setrlimit(2))

       -  measurements of the consumption of CPU time (times(2)) and resources
          (getrusage(2))

       As well as the stack, POSIX.1 specifies that various other attributes are
       distinct for each thread, including:

       -  thread ID (the pthread_t data type)

       -  signal mask (pthread_sigmask(3))

       -  the errno variable

       -  alternate signal stack (sigaltstack(2))

       -  real-time scheduling policy and priority (sched_setscheduler(2) and
          sched_setparam(2))

       The following Linux-specific features are also per-thread:

       -  capabilities (see capabilities(7))

       -  CPU affinity (sched_setaffinity(2))

Pthreads function return values

       Most pthreads functions return 0 on success, and an error number of
       failure.  Note that the pthreads functions do not set errno.  For each of
       the pthreads functions that can return an error, POSIX.1-2001 specifies
       that the function can never fail with the error EINTR.

Thread IDs

       Each of the threads in a process has a unique thread identifier (stored in
       the type pthread_t).  This identifier is returned to the caller of
       pthread_create(3), and a thread can obtain its own thread identifier using
       pthread_self(3).  Thread IDs are only guaranteed to be unique within a
       process.  A thread ID may be reused after a terminated thread has been
       joined, or a detached thread has terminated.  In all pthreads functions
       that accept a thread ID as an argument, that ID by definition refers to a
       thread in the same process as the caller.

Thread-safe functions

       A thread-safe function is one that can be safely (i.e., it will deliver the
       same results regardless of whether it is) called from multiple threads at
       the same time.

       POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the
       standard shall be thread-safe, except for the following functions:

           asctime()
           basename()
           catgets()
           crypt()
           ctermid() if passed a non-NULL argument
           ctime()
           dbm_clearerr()
           dbm_close()
           dbm_delete()
           dbm_error()
           dbm_fetch()
           dbm_firstkey()
           dbm_nextkey()
           dbm_open()
           dbm_store()
           dirname()
           dlerror()
           drand48()
           ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
           encrypt()
           endgrent()
           endpwent()
           endutxent()
           fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
           ftw()
           gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
           getc_unlocked()
           getchar_unlocked()
           getdate()
           getenv()
           getgrent()
           getgrgid()
           getgrnam()
           gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
           gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
           gethostent()
           getlogin()
           getnetbyaddr()
           getnetbyname()
           getnetent()
           getopt()
           getprotobyname()
           getprotobynumber()
           getprotoent()
           getpwent()
           getpwnam()
           getpwuid()
           getservbyname()
           getservbyport()
           getservent()
           getutxent()
           getutxid()
           getutxline()
           gmtime()
           hcreate()
           hdestroy()
           hsearch()
           inet_ntoa()
           l64a()
           lgamma()
           lgammaf()
           lgammal()
           localeconv()
           localtime()
           lrand48()
           mrand48()
           nftw()
           nl_langinfo()
           ptsname()
           putc_unlocked()
           putchar_unlocked()
           putenv()
           pututxline()
           rand()
           readdir()
           setenv()
           setgrent()
           setkey()
           setpwent()
           setutxent()
           strerror()
           strsignal() [Added in POSIX.1-2008]
           strtok()
           system() [Added in POSIX.1-2008]
           tmpnam() if passed a non-NULL argument
           ttyname()
           unsetenv()
           wcrtomb() if its final argument is NULL
           wcsrtombs() if its final argument is NULL
           wcstombs()
           wctomb()

Async-cancel-safe functions

       An async-cancel-safe function is one that can be safely called in an
       application where asynchronous cancelability is enabled (see
       pthread_setcancelstate(3)).

       Only the following functions are required to be async-cancel-safe by
       POSIX.1-2001 and POSIX.1-2008:

           pthread_cancel()
           pthread_setcancelstate()
           pthread_setcanceltype()

Cancellation Points

       POSIX.1 specifies that certain functions must, and certain other functions
       may, be cancellation points.  If a thread is cancelable, its cancelability
       type is deferred, and a cancellation request is pending for the thread,
       then the thread is canceled when it calls a function that is a cancellation
       point.

       The following functions are required to be cancellation points by
       POSIX.1-2001 and/or POSIX.1-2008:

           accept()
           aio_suspend()
           clock_nanosleep()
           close()
           connect()
           creat()
           fcntl() F_SETLKW
           fdatasync()
           fsync()
           getmsg()
           getpmsg()
           lockf() F_LOCK
           mq_receive()
           mq_send()
           mq_timedreceive()
           mq_timedsend()
           msgrcv()
           msgsnd()
           msync()
           nanosleep()
           open()
           openat() [Added in POSIX.1-2008]
           pause()
           poll()
           pread()
           pselect()
           pthread_cond_timedwait()
           pthread_cond_wait()
           pthread_join()
           pthread_testcancel()
           putmsg()
           putpmsg()
           pwrite()
           read()
           readv()
           recv()
           recvfrom()
           recvmsg()
           select()
           sem_timedwait()
           sem_wait()
           send()
           sendmsg()
           sendto()
           sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
           sigsuspend()
           sigtimedwait()
           sigwait()
           sigwaitinfo()
           sleep()
           system()
           tcdrain()
           usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
           wait()
           waitid()
           waitpid()
           write()
           writev()

       The following functions may be cancellation points according to
       POSIX.1-2001 and/or POSIX.1-2008:

           access()
           asctime()
           asctime_r()
           catclose()
           catgets()
           catopen()
           chmod() [Added in POSIX.1-2008]
           chown() [Added in POSIX.1-2008]
           closedir()
           closelog()
           ctermid()
           ctime()
           ctime_r()
           dbm_close()
           dbm_delete()
           dbm_fetch()
           dbm_nextkey()
           dbm_open()
           dbm_store()
           dlclose()
           dlopen()
           dprintf() [Added in POSIX.1-2008]
           endgrent()
           endhostent()
           endnetent()
           endprotoent()
           endpwent()
           endservent()
           endutxent()
           faccessat() [Added in POSIX.1-2008]
           fchmod() [Added in POSIX.1-2008]
           fchmodat() [Added in POSIX.1-2008]
           fchown() [Added in POSIX.1-2008]
           fchownat() [Added in POSIX.1-2008]
           fclose()
           fcntl() (for any value of cmd argument)
           fflush()
           fgetc()
           fgetpos()
           fgets()
           fgetwc()
           fgetws()
           fmtmsg()
           fopen()
           fpathconf()
           fprintf()
           fputc()
           fputs()
           fputwc()
           fputws()
           fread()
           freopen()
           fscanf()
           fseek()
           fseeko()
           fsetpos()
           fstat()
           fstatat() [Added in POSIX.1-2008]
           ftell()
           ftello()
           ftw()
           futimens() [Added in POSIX.1-2008]
           fwprintf()
           fwrite()
           fwscanf()
           getaddrinfo()
           getc()
           getc_unlocked()
           getchar()
           getchar_unlocked()
           getcwd()
           getdate()
           getdelim() [Added in POSIX.1-2008]
           getgrent()
           getgrgid()
           getgrgid_r()
           getgrnam()
           getgrnam_r()
           gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)]
           gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)]
           gethostent()
           gethostid()
           gethostname()
           getline() [Added in POSIX.1-2008]
           getlogin()
           getlogin_r()
           getnameinfo()
           getnetbyaddr()
           getnetbyname()
           getnetent()
           getopt() (if opterr is nonzero)
           getprotobyname()
           getprotobynumber()
           getprotoent()
           getpwent()
           getpwnam()
           getpwnam_r()
           getpwuid()
           getpwuid_r()
           gets()
           getservbyname()
           getservbyport()
           getservent()
           getutxent()
           getutxid()
           getutxline()
           getwc()
           getwchar()
           getwd() [SUSv3 only (function removed in POSIX.1-2008)]
           glob()
           iconv_close()
           iconv_open()
           ioctl()
           link()
           linkat() [Added in POSIX.1-2008]
           lio_listio() [Added in POSIX.1-2008]
           localtime()
           localtime_r()
           lockf() [Added in POSIX.1-2008]
           lseek()
           lstat()
           mkdir() [Added in POSIX.1-2008]
           mkdirat() [Added in POSIX.1-2008]
           mkdtemp() [Added in POSIX.1-2008]
           mkfifo() [Added in POSIX.1-2008]
           mkfifoat() [Added in POSIX.1-2008]
           mknod() [Added in POSIX.1-2008]
           mknodat() [Added in POSIX.1-2008]
           mkstemp()
           mktime()
           nftw()
           opendir()
           openlog()
           pathconf()
           pclose()
           perror()
           popen()
           posix_fadvise()
           posix_fallocate()
           posix_madvise()
           posix_openpt()
           posix_spawn()
           posix_spawnp()
           posix_trace_clear()
           posix_trace_close()
           posix_trace_create()
           posix_trace_create_withlog()
           posix_trace_eventtypelist_getnext_id()
           posix_trace_eventtypelist_rewind()
           posix_trace_flush()
           posix_trace_get_attr()
           posix_trace_get_filter()
           posix_trace_get_status()
           posix_trace_getnext_event()
           posix_trace_open()
           posix_trace_rewind()
           posix_trace_set_filter()
           posix_trace_shutdown()
           posix_trace_timedgetnext_event()
           posix_typed_mem_open()
           printf()
           psiginfo() [Added in POSIX.1-2008]
           psignal() [Added in POSIX.1-2008]
           pthread_rwlock_rdlock()
           pthread_rwlock_timedrdlock()
           pthread_rwlock_timedwrlock()
           pthread_rwlock_wrlock()
           putc()
           putc_unlocked()
           putchar()
           putchar_unlocked()
           puts()
           pututxline()
           putwc()
           putwchar()
           readdir()
           readdir_r()
           readlink() [Added in POSIX.1-2008]
           readlinkat() [Added in POSIX.1-2008]
           remove()
           rename()
           renameat() [Added in POSIX.1-2008]
           rewind()
           rewinddir()
           scandir() [Added in POSIX.1-2008]
           scanf()
           seekdir()
           semop()
           setgrent()
           sethostent()
           setnetent()
           setprotoent()
           setpwent()
           setservent()
           setutxent()
           sigpause() [Added in POSIX.1-2008]
           stat()
           strerror()
           strerror_r()
           strftime()
           symlink()
           symlinkat() [Added in POSIX.1-2008]
           sync()
           syslog()
           tmpfile()
           tmpnam()
           ttyname()
           ttyname_r()
           tzset()
           ungetc()
           ungetwc()
           unlink()
           unlinkat() [Added in POSIX.1-2008]
           utime() [Added in POSIX.1-2008]
           utimensat() [Added in POSIX.1-2008]
           utimes() [Added in POSIX.1-2008]
           vdprintf() [Added in POSIX.1-2008]
           vfprintf()
           vfwprintf()
           vprintf()
           vwprintf()
           wcsftime()
           wordexp()
           wprintf()
           wscanf()

       An implementation may also mark other functions not specified in the
       standard as cancellation points.  In particular, an implementation is
       likely to mark any nonstandard function that may block as a cancellation
       point.  (This includes most functions that can touch files.)

Compiling on Linux

       On Linux, programs that use the Pthreads API should be compiled using cc
       -pthread.

Linux Implementations of POSIX Threads

       Over time, two threading implementations have been provided by the GNU C
       library on Linux:

       LinuxThreads
              This is the original Pthreads implementation.  Since glibc 2.4, this
              implementation is no longer supported.

       NPTL (Native POSIX Threads Library)
              This is the modern Pthreads implementation.  By comparison with
              LinuxThreads, NPTL provides closer conformance to the requirements
              of the POSIX.1 specification and better performance when creating
              large numbers of threads.  NPTL is available since glibc 2.3.2, and
              requires features that are present in the Linux 2.6 kernel.

       Both of these are so-called 1:1 implementations, meaning that each thread
       maps to a kernel scheduling entity.  Both threading implementations employ
       the Linux clone(2) system call.  In NPTL, thread synchronization primitives
       (mutexes, thread joining, and so on) are implemented using the Linux
       futex(2) system call.

LinuxThreads

       The notable features of this implementation are the following:

       -  In addition to the main (initial) thread, and the threads that the
          program creates using pthread_create(3), the implementation creates a
          "manager" thread.  This thread handles thread creation and termination.
          (Problems can result if this thread is inadvertently killed.)

       -  Signals are used internally by the implementation.  On Linux 2.2 and
          later, the first three real-time signals are used (see also signal(7)).
          On older Linux kernels, SIGUSR1 and SIGUSR2 are used.  Applications must
          avoid the use of whichever set of signals is employed by the
          implementation.

       -  Threads do not share process IDs.  (In effect, LinuxThreads threads are
          implemented as processes which share more information than usual, but
          which do not share a common process ID.)  LinuxThreads threads
          (including the manager thread) are visible as separate processes using
          ps(1).

       The LinuxThreads implementation deviates from the POSIX.1 specification in
       a number of ways, including the following:

       -  Calls to getpid(2) return a different value in each thread.

       -  Calls to getppid(2) in threads other than the main thread return the
          process ID of the manager thread; instead getppid(2) in these threads
          should return the same value as getppid(2) in the main thread.

       -  When one thread creates a new child process using fork(2), any thread
          should be able to wait(2) on the child.  However, the implementation
          only allows the thread that created the child to wait(2) on it.

       -  When a thread calls execve(2), all other threads are terminated (as
          required by POSIX.1).  However, the resulting process has the same PID
          as the thread that called execve(2): it should have the same PID as the
          main thread.

       -  Threads do not share user and group IDs.  This can cause complications
          with set-user-ID programs and can cause failures in Pthreads functions
          if an application changes its credentials using seteuid(2) or similar.

       -  Threads do not share a common session ID and process group ID.

       -  Threads do not share record locks created using fcntl(2).

       -  The information returned by times(2) and getrusage(2) is per-thread
          rather than process-wide.

       -  Threads do not share semaphore undo values (see semop(2)).

       -  Threads do not share interval timers.

       -  Threads do not share a common nice value.

       -  POSIX.1 distinguishes the notions of signals that are directed to the
          process as a whole and signals that are directed to individual threads.
          According to POSIX.1, a process-directed signal (sent using kill(2), for
          example) should be handled by a single, arbitrarily selected thread
          within the process.  LinuxThreads does not support the notion of
          process-directed signals: signals may only be sent to specific threads.

       -  Threads have distinct alternate signal stack settings.  However, a new
          thread's alternate signal stack settings are copied from the thread that
          created it, so that the threads initially share an alternate signal
          stack.  (A new thread should start with no alternate signal stack
          defined.  If two threads handle signals on their shared alternate signal
          stack at the same time, unpredictable program failures are likely to
          occur.)

NPTL

       With NPTL, all of the threads in a process are placed in the same thread
       group; all members of a thread group share the same PID.  NPTL does not
       employ a manager thread.  NPTL makes internal use of the first two real-
       time signals (see also signal(7)); these signals cannot be used in
       applications.

       NPTL still has at least one nonconformance with POSIX.1:

       -  Threads do not share a common nice value.

       Some NPTL nonconformances only occur with older kernels:

       -  The information returned by times(2) and getrusage(2) is per-thread
          rather than process-wide (fixed in kernel 2.6.9).

       -  Threads do not share resource limits (fixed in kernel 2.6.10).

       -  Threads do not share interval timers (fixed in kernel 2.6.12).

       -  Only the main thread is permitted to start a new session using setsid(2)
          (fixed in kernel 2.6.16).

       -  Only the main thread is permitted to make the process into a process
          group leader using setpgid(2) (fixed in kernel 2.6.16).

       -  Threads have distinct alternate signal stack settings.  However, a new
          thread's alternate signal stack settings are copied from the thread that
          created it, so that the threads initially share an alternate signal
          stack (fixed in kernel 2.6.16).

       Note the following further points about the NPTL implementation:

       -  If the stack size soft resource limit (see the description of
          RLIMIT_STACK in setrlimit(2)) is set to a value other than unlimited,
          then this value defines the default stack size for new threads.  To be
          effective, this limit must be set before the program is executed,
          perhaps using the ulimit -s shell built-in command (limit stacksize in
          the C shell).

Determining the Threading Implementation

       Since glibc 2.3.2, the getconf(1) command can be used to determine the
       system's threading implementation, for example:

           bash$ getconf GNU_LIBPTHREAD_VERSION
           NPTL 2.3.4

       With older glibc versions, a command such as the following should be
       sufficient to determine the default threading implementation:

           bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \
                           egrep -i 'threads|nptl'
                   Native POSIX Threads Library by Ulrich Drepper et al

Selecting the Threading Implementation: LD_ASSUME_KERNEL

       On systems with a glibc that supports both LinuxThreads and NPTL (i.e.,
       glibc 2.3.x), the LD_ASSUME_KERNEL environment variable can be used to
       override the dynamic linker's default choice of threading implementation.
       This variable tells the dynamic linker to assume that it is running on top
       of a particular kernel version.  By specifying a kernel version that does
       not provide the support required by NPTL, we can force the use of
       LinuxThreads.  (The most likely reason for doing this is to run a (broken)
       application that depends on some nonconformant behavior in LinuxThreads.)
       For example:

           bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \
                           awk '{print $3}' ) | egrep -i 'threads|ntpl'
                   linuxthreads-0.10 by Xavier Leroy

SEE ALSO top

       clone(2), futex(2), gettid(2), proc(5), futex(7), sigevent(7), signal(7),

       Various Pthreads manual pages, for example: pthread_attr_init(3),
       pthread_atfork(3), pthread_cancel(3), pthread_cleanup_push(3),
       pthread_cond_signal(3), pthread_cond_wait(3), pthread_create(3),
       pthread_detach(3), pthread_equal(3), pthread_exit(3),
       pthread_key_create(3), pthread_kill(3), pthread_mutex_lock(3),
       pthread_mutex_unlock(3), pthread_once(3), pthread_setcancelstate(3),
       pthread_setcanceltype(3), pthread_setspecific(3), pthread_sigmask(3),
       pthread_sigqueue(3), and pthread_testcancel(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-14                         PTHREADS(7)


pthread_attr_init(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_INIT(3)         Linux Programmer's Manual        PTHREAD_ATTR_INIT(3)

NAME top

       pthread_attr_init,  pthread_attr_destroy  -  initialize  and destroy thread
       attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_init(pthread_attr_t *attr);
       int pthread_attr_destroy(pthread_attr_t *attr);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_init() function initializes the thread attributes object
       pointed to by attr with default attribute values.  After this call,
       individual attributes of the object can be set using various related
       functions (listed under SEE ALSO), and then the object can be used in one
       or more pthread_create(3) calls that create threads.

       Calling pthread_attr_init() on a thread attributes object that has already
       been initialized results in undefined behavior.

       When a thread attributes object is no longer required, it should be
       destroyed using the pthread_attr_destroy() function.  Destroying a thread
       attributes object has no effect on threads that were created using that
       object.

       Once a thread attributes object has been destroyed, it can be reinitialized
       using pthread_attr_init().  Any other use of a destroyed thread attributes
       object has undefined results.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       POSIX.1-2001 documents an ENOMEM error for pthread_attr_init(); on Linux
       these functions always succeed (but portable and future-proof applications
       should nevertheless handle a possible error return).

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The pthread_attr_t type should be treated as opaque: any access to the
       object other than via pthreads functions is nonportable and produces
       undefined results.

EXAMPLE top

       The program below optionally makes use of pthread_attr_init() and various
       related functions to initialize a thread attributes object that is used to
       create a single thread.  Once created, the thread uses the
       pthread_getattr_np(3) function (a nonstandard GNU extension) to retrieve
       the thread's attributes, and then displays those attributes.

       If the program is run with no command-line argument, then it passes NULL as
       the attr argument of pthread_create(3), so that the thread is created with
       default attributes.  Running the program on Linux/x86-32 with the NPTL
       threading implementation, we see the following:

           $ ulimit -s       # No stack imit ==> default stack size is 2MB
           unlimited
           $ ./a.out
           Thread attributes:
                   Detach state        = PTHREAD_CREATE_JOINABLE
                   Scope               = PTHREAD_SCOPE_SYSTEM
                   Inherit scheduler   = PTHREAD_INHERIT_SCHED
                   Scheduling policy   = SCHED_OTHER
                   Scheduling priority = 0
                   Guard size          = 4096 bytes
                   Stack address       = 0x40196000
                   Stack size          = 0x201000 bytes

       When we supply a stack size as a command-line argument, the program
       initializes a thread attributes object, sets various attributes in that
       object, and passes a pointer to the object in the call to
       pthread_create(3).  Running the program on Linux/x86-32 with the NPTL
       threading implementation, we see the following:

           $ ./a.out 0x3000000
           posix_memalign() allocated at 0x40197000
           Thread attributes:
                   Detach state        = PTHREAD_CREATE_DETACHED
                   Scope               = PTHREAD_SCOPE_SYSTEM
                   Inherit scheduler   = PTHREAD_EXPLICIT_SCHED
                   Scheduling policy   = SCHED_OTHER
                   Scheduling priority = 0
                   Guard size          = 0 bytes
                   Stack address       = 0x40197000
                   Stack size          = 0x3000000 bytes

Program source

       #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
       #include <pthread.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void
       display_pthread_attr(pthread_attr_t *attr, char *prefix)
       {
           int s, i;
           size_t v;
           void *stkaddr;
           struct sched_param sp;

           s = pthread_attr_getdetachstate(attr, &i);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getdetachstate");
           printf("%sDetach state        = %s\n", prefix,
                   (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
                   (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
                   "???");

           s = pthread_attr_getscope(attr, &i);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getscope");
           printf("%sScope               = %s\n", prefix,
                   (i == PTHREAD_SCOPE_SYSTEM)  ? "PTHREAD_SCOPE_SYSTEM" :
                   (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
                   "???");

           s = pthread_attr_getinheritsched(attr, &i);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getinheritsched");
           printf("%sInherit scheduler   = %s\n", prefix,
                   (i == PTHREAD_INHERIT_SCHED)  ? "PTHREAD_INHERIT_SCHED" :
                   (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
                   "???");

           s = pthread_attr_getschedpolicy(attr, &i);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getschedpolicy");
           printf("%sScheduling policy   = %s\n", prefix,
                   (i == SCHED_OTHER) ? "SCHED_OTHER" :
                   (i == SCHED_FIFO)  ? "SCHED_FIFO" :
                   (i == SCHED_RR)    ? "SCHED_RR" :
                   "???");

           s = pthread_attr_getschedparam(attr, &sp);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getschedparam");
           printf("%sScheduling priority = %d\n", prefix, sp.sched_priority);

           s = pthread_attr_getguardsize(attr, &v);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getguardsize");
           printf("%sGuard size          = %d bytes\n", prefix, v);

           s = pthread_attr_getstack(attr, &stkaddr, &v);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getstack");
           printf("%sStack address       = %p\n", prefix, stkaddr);
           printf("%sStack size          = 0x%x bytes\n", prefix, v);
       }

       static void *
       thread_start(void *arg)
       {
           int s;
           pthread_attr_t gattr;

           /* pthread_getattr_np() is a non-standard GNU extension that
              retrieves the attributes of the thread specified in its
              first argument */

           s = pthread_getattr_np(pthread_self(), &gattr);
           if (s != 0)
               handle_error_en(s, "pthread_getattr_np");

           printf("Thread attributes:\n");
           display_pthread_attr(&gattr, "\t");

           exit(EXIT_SUCCESS);         /* Terminate all threads */
       }

       int
       main(int argc, char *argv[])
       {
           pthread_t thr;
           pthread_attr_t attr;
           pthread_attr_t *attrp;      /* NULL or &attr */
           int s;

           attrp = NULL;

           /* If a command-line argument was supplied, use it to set the
              stack-size attribute and set a few other thread attributes,
              and set attrp pointing to thread attributes object */

           if (argc > 1) {
               int stack_size;
               void *sp;

               attrp = &attr;

               s = pthread_attr_init(&attr);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_init");

               s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setdetachstate");

               s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setinheritsched");

               stack_size = strtoul(argv[1], NULL, 0);

               s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
               if (s != 0)
                   handle_error_en(s, "posix_memalign");

               printf("posix_memalign() allocated at %p\n", sp);

               s = pthread_attr_setstack(&attr, sp, stack_size);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setstack");
           }

           s = pthread_create(&thr, attrp, &thread_start, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           if (attrp != NULL) {
               s = pthread_attr_destroy(attrp);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_destroy");
           }

           pause();    /* Terminates when other thread calls exit() */
       }

SEE ALSO top

       pthread_attr_setaffinity_np(3), pthread_attr_setdetachstate(3),
       pthread_attr_setguardsize(3), pthread_attr_setinheritsched(3),
       pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
       pthread_attr_setscope(3), pthread_attr_setstack(3),
       pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3),
       pthread_create(3), pthread_getattr_np(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                PTHREAD_ATTR_INIT(3)


pthread_attr_setaffinity_np(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETAFFINITY_NP(3)Linux Programmer's ManuaPlTHREAD_ATTR_SETAFFINITY_NP(3)

NAME top

       pthread_attr_setaffinity_np,   pthread_attr_getaffinity_np  -  set/get  CPU
       affinity attribute in thread attributes object

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <pthread.h>

       int pthread_attr_setaffinity_np(pthread_attr_t *attr,
                          size_t cpusetsize, const cpu_set_t *cpuset);
       int pthread_attr_getaffinity_np(pthread_attr_t *attr,
                          size_t cpusetsize, cpu_set_t *cpuset);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setaffinity_np() function sets the CPU affinity mask
       attribute of the thread attributes object referred to by attr to the value
       specified in cpuset.  This attribute determines the CPU affinity mask of a
       thread created using the thread attributes object attr.

       The pthread_attr_getaffinity_np() function returns the CPU affinity mask
       attribute of the thread attributes object referred to by attr in the buffer
       pointed to by cpuset.

       The argument cpusetsize is the length (in bytes) of the buffer pointed to
       by cpuset.  Typically, this argument would be specified as
       sizeof(cpu_set_t).

       For more details on CPU affinity masks, see sched_setaffinity(2).  For a
       description of a set of macros that can be used to manipulate and inspect
       CPU sets, see CPU_SET(3).

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       EINVAL (pthread_attr_setaffinity_np()) cpuset specified a CPU that was
              outside the set supported by the kernel.  (The kernel configuration
              option CONFIG_NR_CPUS defines the range of the set supported by the
              kernel data type used to represent CPU sets.)

       EINVAL (pthread_attr_getaffinity_np()) A CPU in the affinity mask of the
              thread attributes object referred to by attr lies outside the range
              specified by cpusetsize (i.e., cpuset/cpusetsize is too small).

       ENOMEM (pthread_attr_setaffinity_np()) Could not allocate memory.

VERSIONS top

       These functions are provided by glibc since version 2.3.4.

CONFORMING TO top

       These functions are nonstandard GNU extensions; hence the suffix "_np"
       (nonportable) in the names.

NOTES top

       In glibc 2.3.3 only, versions of these functions were provided that did not
       have a cpusetsize argument.  Instead the CPU set size given to the
       underlying system calls was always sizeof(cpu_set_t).

SEE ALSO top

       sched_setaffinity(2), pthread_attr_init(3), pthread_setaffinity_np(3),
       cpuset(7), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10      PTHREAD_ATTR_SETAFFINITY_NP(3)


pthread_attr_setdetachstate(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETDETACHSTATE(3)Linux Programmer's ManuaPlTHREAD_ATTR_SETDETACHSTATE(3)

NAME top

       pthread_attr_setdetachstate,  pthread_attr_getdetachstate  - set/get detach
       state attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);
       int pthread_attr_getdetachstate(pthread_attr_t *attr, int *detachstate);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setdetachstate() function sets the detach state attribute
       of the thread attributes object referred to by attr to the value specified
       in detachstate.  The detach state attribute determines whether a thread
       created using the thread attributes object attr will be created in a
       joinable or a detached state.

       The following values may be specified in detachstate:

       PTHREAD_CREATE_DETACHED
              Threads that are created using attr will be created in a detached
              state.

       PTHREAD_CREATE_JOINABLE
              Threads that are created using attr will be created in a joinable
              state.

       The default setting of the detach state attribute in a newly initialized
       thread attributes object is PTHREAD_CREATE_JOINABLE.

       The pthread_attr_getdetachstate() returns the detach state attribute of the
       thread attributes object attr in the buffer pointed to by detachstate.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       pthread_attr_setdetachstate() can fail with the following error:

       EINVAL An invalid value was specified in detachstate.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       See pthread_create(3) for more details on detached and joinable threads.

       A thread that is created in a joinable state should eventually either be
       joined using pthread_join(3) or detached using pthread_detach(3); see
       pthread_create(3).

       It is an error to specify the thread ID of a thread that was created in a
       detached state in a later call to pthread_detach(3) or pthread_join(3).

EXAMPLE top

       See pthread_attr_init(3).

SEE ALSO top

       pthread_attr_init(3), pthread_create(3), pthread_detach(3),
       pthread_join(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-03      PTHREAD_ATTR_SETDETACHSTATE(3)


pthread_attr_setguardsize(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETGUARDSIZE(3) Linux Programmer's ManualPTHREAD_ATTR_SETGUARDSIZE(3)

NAME top

       pthread_attr_setguardsize,  pthread_attr_getguardsize  - set/get guard size
       attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize);
       int pthread_attr_getguardsize(pthread_attr_t *attr, size_t *guardsize);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setguardsize() function sets the guard size attribute of
       the thread attributes object referred to by attr to the value specified in
       guardsize.

       If guardsize is greater than 0, then for each new thread created using attr
       the system allocates an additional region of at least guardsize bytes at
       the end of the thread's stack to act as the guard area for the stack (but
       see BUGS).

       If guardsize is 0, then new threads created with attr will not have a guard
       area.

       The default guard size is the same as the system page size.

       If the stack address attribute has been set in attr (using
       pthread_attr_setstack(3) or pthread_attr_setstackaddr(3)), meaning that the
       caller is allocating the thread's stack, then the guard size attribute is
       ignored (i.e., no guard area is created by the system): it is the
       application's responsibility to handle stack overflow (perhaps by using
       mprotect(2) to manually define a guard area at the end of the stack that it
       has allocated).

       The pthread_attr_getguardsize() function returns the guard size attribute
       of the thread attributes object referred to by attr in the buffer pointed
       to by guardsize.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       POSIX.1-2001 documents an EINVAL error if attr or guardsize is invalid.  On
       Linux these functions always succeed (but portable and future-proof
       applications should nevertheless handle a possible error return).

VERSIONS top

       These functions are provided by glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       A guard area consists of virtual memory pages that are protected to prevent
       read and write access.  If a thread overflows its stack into the guard
       area, then, on most hard architectures, it receives a SIGSEGV signal, thus
       notifying it of the overflow.  Guard areas start on page boundaries, and
       the guard size is internally rounded up to the system page size when
       creating a thread.  (Nevertheless, pthread_attr_getguardsize() returns the
       guard size that was set by pthread_attr_setguardsize().)

       Setting a guard size of 0 may be useful to save memory in an application
       that creates many threads and knows that stack overflow can never occur.

       Choosing a guard size larger than the default size may be necessary for
       detecting stack overflows if a thread allocates large data structures on
       the stack.

BUGS top

       As at glibc 2.8, the NPTL threading implementation includes the guard area
       within the stack size allocation, rather than allocating extra space at the
       end of the stack, as POSIX.1 requires.  (This can result in an EINVAL error
       from pthread_create(3) if the guard size value is too large, leaving no
       space for the actual stack.)

       The obsolete LinuxThreads implementation did the right thing, allocating
       extra space at the end of the stack for the guard area.

EXAMPLE top

       See pthread_getattr_np(3).

SEE ALSO top

       mmap(2), mprotect(2), pthread_attr_init(3), pthread_attr_setstack(3),
       pthread_attr_setstacksize(3), pthread_create(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-10-24        PTHREAD_ATTR_SETGUARDSIZE(3)


pthread_attr_setinheritsched(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETINHERITSCHED(3L)inux Programmer's ManuPaTlHREAD_ATTR_SETINHERITSCHED(3)

NAME top

       pthread_attr_setinheritsched,    pthread_attr_getinheritsched   -   set/get
       inherit scheduler attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setinheritsched(pthread_attr_t *attr,
                                        int inheritsched);
       int pthread_attr_getinheritsched(pthread_attr_t *attr,
                                        int *inheritsched);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setinheritsched() function sets the inherit scheduler
       attribute of the thread attributes object referred to by attr to the value
       specified in inheritsched.  The inherit scheduler attribute determines
       whether a thread created using the thread attributes object attr will
       inherit its scheduling attributes from the calling thread or whether it
       will take them from attr.

       The following values may be specified in inheritsched:

       PTHREAD_INHERIT_SCHED
              Threads that are created using attr inherit scheduling attributes
              from the creating thread; the scheduling attributes in attr are
              ignored.

       PTHREAD_EXPLICIT_SCHED
              Threads that are created using attr take their scheduling attributes
              from the values specified by the attributes object.

       The default setting of the inherit scheduler attribute in a newly
       initialized thread attributes object is PTHREAD_INHERIT_SCHED.

       The pthread_attr_getinheritsched() returns the inherit scheduler attribute
       of the thread attributes object attr in the buffer pointed to by
       inheritsched.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       pthread_attr_setinheritsched() can fail with the following error:

       EINVAL Invalid value in inheritsched.

       POSIX.1-2001 also documents an optional ENOTSUP error ("attempt was made to
       set the attribute to an unsupported value") for
       pthread_attr_setinheritsched().

CONFORMING TO top

       POSIX.1-2001.

BUGS top

       As at glibc 2.8, if a thread attributes object is initialized using
       pthread_attr_init(3), then the scheduling policy of the attributes object
       is set to SCHED_OTHER and the scheduling priority is set to 0.  However, if
       the inherit scheduler attribute is then set to PTHREAD_EXPLICIT_SCHED, then
       a thread created using the attribute object wrongly inherits its scheduling
       attributes from the creating thread.  This bug does not occur if either the
       scheduling policy or scheduling priority attribute is explicitly set in the
       thread attributes object before calling pthread_create(3).

EXAMPLE top

       See pthread_setschedparam(3).

SEE ALSO top

       sched_setscheduler(2), pthread_attr_init(3), pthread_attr_setschedparam(3),
       pthread_attr_setschedpolicy(3), pthread_create(3),
       pthread_setschedparam(3), pthread_setschedprio(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-15     PTHREAD_ATTR_SETINHERITSCHED(3)


pthread_attr_setschedparam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETSCHEDPARAM(3)Linux Programmer's ManualPTHREAD_ATTR_SETSCHEDPARAM(3)

NAME top

       pthread_attr_setschedparam, pthread_attr_getschedparam - set/get scheduling
       parameter attributes in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setschedparam(pthread_attr_t *attr,
                                      const struct sched_param *param);
       int pthread_attr_getschedparam(pthread_attr_t *attr,
                                      struct sched_param *param);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setschedparam() function sets the scheduling parameter
       attributes of the thread attributes object referred to by attr to the
       values specified in the buffer pointed to by param.  These attributes
       determine the scheduling parameters of a thread created using the thread
       attributes object attr.

       The pthread_attr_getschedparam() returns the scheduling parameter
       attributes of the thread attributes object attr in the buffer pointed to by
       param.

       Scheduling parameters are maintained in the following structure:

           struct sched_param {
               int sched_priority;     /* Scheduling priority */
           };

       As can be seen, only one scheduling parameter is supported.  For details of
       the permitted ranges for scheduling priorities in each scheduling policy,
       see sched_setscheduler(2).

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       POSIX.1 documents EINVAL and ENOTSUP errors for
       pthread_attr_setschedparam().  On Linux these functions always succeed (but
       portable and future-proof applications should nevertheless handle a
       possible error return).

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       See pthread_attr_setschedpolicy(3) for a list of the thread scheduling
       policies supported on Linux.

EXAMPLE top

       See pthread_setschedparam(3).

SEE ALSO top

       sched_get_priority_min(2), sched_setscheduler(2), pthread_attr_init(3),
       pthread_attr_setinheritsched(3), pthread_attr_setschedpolicy(3),
       pthread_create(3), pthread_setschedparam(3), pthread_setschedprio(3),
       pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-15       PTHREAD_ATTR_SETSCHEDPARAM(3)


pthread_attr_setschedpolicy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETSCHEDPOLICY(3)Linux Programmer's ManuaPlTHREAD_ATTR_SETSCHEDPOLICY(3)

NAME top

       pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - set/get schedul-
       ing policy attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
       int pthread_attr_getschedpolicy(pthread_attr_t *attr, int *policy);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setschedpolicy() function sets the scheduling policy
       attribute of the thread attributes object referred to by attr to the value
       specified in policy.  This attribute determines the scheduling policy of a
       thread created using the thread attributes object attr.

       The supported values for policy are SCHED_FIFO, SCHED_RR, and SCHED_OTHER,
       with the semantics described in sched_setscheduler(2).

       The pthread_attr_getschedpolicy() returns the scheduling policy attribute
       of the thread attributes object attr in the buffer pointed to by policy.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       pthread_attr_setschedpolicy() can fail with the following error:

       EINVAL Invalid value in policy.

       POSIX.1-2001 also documents an optional ENOTSUP error ("attempt was made to
       set the attribute to an unsupported value") for
       pthread_attr_setschedpolicy().

CONFORMING TO top

       POSIX.1-2001.

EXAMPLE top

       See pthread_setschedparam(3).

SEE ALSO top

       sched_setscheduler(2), pthread_attr_init(3),
       pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3),
       pthread_create(3), pthread_setschedparam(3), pthread_setschedprio(3),
       pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-03      PTHREAD_ATTR_SETSCHEDPOLICY(3)


pthread_attr_setscope(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETSCOPE(3)     Linux Programmer's Manual    PTHREAD_ATTR_SETSCOPE(3)

NAME top

       pthread_attr_setscope,  pthread_attr_getscope  -  set/get  contention scope
       attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setscope(pthread_attr_t *attr, int scope);
       int pthread_attr_getscope(pthread_attr_t *attr, int *scope);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setscope() function sets the contention scope attribute of
       the thread attributes object referred to by attr to the value specified in
       scope.  The contention scope attribute defines the set of threads against
       which a thread competes for resources such as the CPU.  POSIX.1-2001
       specifies two possible values for scope:

       PTHREAD_SCOPE_SYSTEM
              The thread competes for resources with all other threads in all
              processes on the system that are in the same scheduling allocation
              domain (a group of one or more processors).  PTHREAD_SCOPE_SYSTEM
              threads are scheduled relative to one another according to their
              scheduling policy and priority.

       PTHREAD_SCOPE_PROCESS
              The thread competes for resources with all other threads in the same
              process that were also created with the PTHREAD_SCOPE_PROCESS
              contention scope.  PTHREAD_SCOPE_PROCESS threads are scheduled
              relative to other threads in the process according to their
              scheduling policy and priority.  POSIX.1-2001 leaves it unspecified
              how these threads contend with other threads in other process on the
              system or with other threads in the same process that were created
              with the PTHREAD_SCOPE_SYSTEM contention scope.

       POSIX.1-2001 only requires that an implementation support one of these
       contention scopes, but permits both to be supported.  Linux supports
       PTHREAD_SCOPE_SYSTEM, but not PTHREAD_SCOPE_PROCESS.

       The pthread_attr_getscope() function returns the contention scope attribute
       of the thread attributes object referred to by attr in the buffer pointed
       to by scope.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       pthread_attr_setscope() can fail with the following errors:

       EINVAL An invalid value was specified in scope.

       ENOTSUP
              scope specified the value PTHREAD_SCOPE_PROCESS, which is not
              supported on Linux.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The PTHREAD_SCOPE_SYSTEM contention scope typically indicates that a user-
       space thread is bound directly to a single kernel-scheduling entity.  This
       is the case on Linux for the obsolete LinuxThreads implementation and the
       modern NPTL implementation, which are both 1:1 threading implementations.

       POSIX.1-2001 specifies that the default contention scope is implementation-
       defined.

SEE ALSO top

       pthread_attr_init(3), pthread_attr_setaffinity_np(3),
       pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3),
       pthread_attr_setschedpolicy(3), pthread_create(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-10-24            PTHREAD_ATTR_SETSCOPE(3)


pthread_attr_setstack(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETSTACK(3)     Linux Programmer's Manual    PTHREAD_ATTR_SETSTACK(3)

NAME top

       pthread_attr_setstack,  pthread_attr_getstack - set/get stack attributes in
       thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setstack(pthread_attr_t *attr,
                                 void *stackaddr, size_t stacksize);
       int pthread_attr_getstack(pthread_attr_t *attr,
                                 void **stackaddr, size_t *stacksize);

       Compile and link with -pthread.

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

       pthread_attr_getstack(), pthread_attr_setstack():
           _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       The pthread_attr_setstack() function sets the stack address and stack size
       attributes of the thread attributes object referred to by attr to the
       values specified in stackaddr and stacksize, respectively.  These
       attributes specify the location and size of the stack that should be used
       by a thread that is created using the thread attributes object attr.

       stackaddr should point to the lowest addressable byte of a buffer of
       stacksize bytes that was allocated by the caller.  The pages of the
       allocated buffer should be both readable and writable.

       The pthread_attr_getstack() function returns the stack address and stack
       size attributes of the thread attributes object referred to by attr in the
       buffers pointed to by stackaddr and stacksize, respectively.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       pthread_attr_setstack() can fail with the following error:

       EINVAL stacksize is less than PTHREAD_STACK_MIN (16384) bytes.  On some
              systems, this error may also occur if stackaddr or
              stackaddr + stacksize is not suitably aligned.

       POSIX.1-2001 also documents an EACCES error if the stack area described by
       stackaddr and stacksize is not both readable and writable by the caller.

VERSIONS top

       These functions are provided by glibc since version 2.2.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       These functions are provided for applications that must ensure that a
       thread's stack is placed in a particular location.  For most applications,
       this is not necessary, and the use of these functions should be avoided.
       (Use pthread_attr_setstacksize(3) if an application simply requires a stack
       size other than the default.)

       When an application employs pthread_attr_setstack(), it takes over the
       responsibility of allocating the stack.  Any guard size value that was set
       using pthread_attr_setguardsize(3) is ignored.  If deemed necessary, it is
       the application's responsibility to allocate a guard area (one or more
       pages protected against reading and writing) to handle the possibility of
       stack overflow.

       The address specified in stackaddr should be suitably aligned: for full
       portability, align it on a page boundary (sysconf(_SC_PAGESIZE)).
       posix_memalign(3) may be useful for allocation.  Probably, stacksize should
       also be a multiple of the system page size.

       If attr is used to create multiple threads, then the caller must change the
       stack address attribute between calls to pthread_create(3); otherwise, the
       threads will attempt to use the same memory area for their stacks, and
       chaos will ensue.

EXAMPLE top

       See pthread_attr_init(3).

SEE ALSO top

       mmap(2), mprotect(2), posix_memalign(3), pthread_attr_init(3),
       pthread_attr_setguardsize(3), pthread_attr_setstackaddr(3),
       pthread_attr_setstacksize(3), pthread_create(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-10-24            PTHREAD_ATTR_SETSTACK(3)


pthread_attr_setstackaddr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETSTACKADDR(3) Linux Programmer's ManualPTHREAD_ATTR_SETSTACKADDR(3)

NAME top

       pthread_attr_setstackaddr,   pthread_attr_getstackaddr   -   set/get  stack
       address attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr);
       int pthread_attr_getstackaddr(pthread_attr_t *attr, void **stackaddr);

       Compile and link with -pthread.

DESCRIPTION top

       These functions are obsolete: do not use them.  Use
       pthread_attr_setstack(3) and pthread_attr_getstack(3) instead.

       The pthread_attr_setstackaddr() function sets the stack address attribute
       of the thread attributes object referred to by attr to the value specified
       in stackaddr.  This attribute specifies the location of the stack that
       should be used by a thread that is created using the thread attributes
       object attr.

       stackaddr should point to a buffer of at least PTHREAD_STACK_MIN bytes that
       was allocated by the caller.  The pages of the allocated buffer should be
       both readable and writable.

       The pthread_attr_getstackaddr() function returns the stack address
       attribute of the thread attributes object referred to by attr in the buffer
       pointed to by stackaddr.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       No errors are defined (but applications should nevertheless handle a
       possible error return).

VERSIONS top

       These functions are provided by glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001 specifies these functions but marks them as obsolete.
       POSIX.1-2008 removes the specification of these functions.

NOTES top

       Do not use these functions!  They cannot be portably used, since they
       provide no way of specifying the direction of growth or the range of the
       stack.  For example, on architectures with a stack that grows downward,
       stackaddr specifies the next address past the highest address of the
       allocated stack area.  However, on architectures with a stack that grows
       upward, stackaddr specifies the lowest address in the allocated stack area.
       By contrast, the stackaddr used by pthread_attr_setstack(3) and
       pthread_attr_getstack(3), is always a pointer to the lowest address in the
       allocated stack area (and the stacksize argument specifies the range of the
       stack).

SEE ALSO top

       pthread_attr_init(3), pthread_attr_setstack(3),
       pthread_attr_setstacksize(3), pthread_create(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-10-24        PTHREAD_ATTR_SETSTACKADDR(3)


pthread_attr_setstacksize(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_ATTR_SETSTACKSIZE(3) Linux Programmer's ManualPTHREAD_ATTR_SETSTACKSIZE(3)

NAME top

       pthread_attr_setstacksize,  pthread_attr_getstacksize  - set/get stack size
       attribute in thread attributes object

SYNOPSIS top

       #include <pthread.h>

       int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize);
       int pthread_attr_getstacksize(pthread_attr_t *attr, size_t *stacksize);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_attr_setstacksize() function sets the stack size attribute of
       the thread attributes object referred to by attr to the value specified in
       stacksize.

       The stack size attribute determines the minimum size (in bytes) that will
       be allocated for threads created using the thread attributes object attr.

       The pthread_attr_getstacksize() function returns the stack size attribute
       of the thread attributes object referred to by attr in the buffer pointed
       to by stacksize.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       pthread_attr_setstacksize() can fail with the following error:

       EINVAL The stack size is less than PTHREAD_STACK_MIN (16384) bytes.

       On some systems, pthread_attr_setstacksize() can fail with the error EINVAL
       if stacksize is not a multiple of the system page size.

VERSIONS top

       These functions are provided by glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       For details on the default stack size of new threads, see
       pthread_create(3).

       A thread's stack size is fixed at the time of thread creation.  Only the
       main thread can dynamically grow its stack.

       The pthread_attr_setstack(3) function allows an application to set both the
       size and location of a caller-allocated stack that is to be used by a
       thread.

BUGS top

       As at glibc 2.8, if the specified stacksize is not a multiple of
       STACK_ALIGN (16 bytes on most architectures), it may be rounded downward,
       in violation of POSIX.1-2001, which says that the allocated stack will be
       at least stacksize bytes.

EXAMPLE top

       See pthread_create(3).

SEE ALSO top

       getrlimit(2), pthread_attr_init(3), pthread_attr_setguardsize(3),
       pthread_attr_setstack(3), pthread_create(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-15        PTHREAD_ATTR_SETSTACKSIZE(3)


pthread_cancel(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_CANCEL(3)            Linux Programmer's Manual           PTHREAD_CANCEL(3)

NAME top

       pthread_cancel - send a cancellation request to a thread

SYNOPSIS top

       #include <pthread.h>

       int pthread_cancel(pthread_t thread);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_cancel() function sends a cancellation request to the thread
       thread.  Whether and when the target thread reacts to the cancellation
       request depends on two attributes that are under the control of that
       thread: its cancelability state and type.

       A thread's cancelability state, determined by pthread_setcancelstate(3),
       can be enabled (the default for new threads) or disabled.  If a thread has
       disabled cancellation, then a cancellation request remains queued until the
       thread enables cancellation.  If a thread has enabled cancellation, then
       its cancelability type determines when cancellation occurs.

       A thread's cancellation type, determined by pthread_setcanceltype(3), may
       be either asynchronous or deferred (the default for new threads).
       Asynchronous cancelability means that the thread can be canceled at any
       time (usually immediately, but the system does not guarantee this).
       Deferred cancelability means that cancellation will be delayed until the
       thread next calls a function that is a cancellation point.  A list of
       functions that are or may be cancellation points is provided in
       pthreads(7).

       When a cancellation requested is acted on, the following steps occur for
       thread (in this order):

       1. Cancellation clean-up handlers are popped (in the reverse of the order
          in which they were pushed) and called.  (See pthread_cleanup_push(3).)

       2. Thread-specific data destructors are called, in an unspecified order.
          (See pthread_key_create(3).)

       3. The thread is terminated.  (See pthread_exit(3).)

       The above steps happen asynchronously with respect to the pthread_cancel()
       call; the return status of pthread_cancel() merely informs the caller
       whether the cancellation request was successfully queued.

       After a canceled thread has terminated, a join with that thread using
       pthread_join(3) obtains PTHREAD_CANCELED as the thread's exit status.
       (Joining with a thread is the only way to know that cancellation has
       completed.)

RETURN VALUE top

       On success, pthread_cancel() returns 0; on error, it returns a nonzero
       error number.

ERRORS top

       ESRCH  No thread with the ID thread could be found.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       On Linux, cancellation is implemented using signals.  Under the NPTL
       threading implementation, the first real-time signal (i.e., signal 32) is
       used for this purpose.  On LinuxThreads, the second real-time signal is
       used, if real-time signals are available, otherwise SIGUSR2 is used.

EXAMPLE top

       The program below creates a thread and then cancels it.  The main thread
       joins with the canceled thread to check that its exit status was
       PTHREAD_CANCELED.  The following shell session shows what happens when we
       run the program:

           $ ./a.out
           thread_func(): started; cancellation disabled
           main(): sending cancellation request
           thread_func(): about to enable cancellation
           main(): thread was canceled

Program source

       #include <pthread.h>
       #include <stdio.h>
       #include <errno.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void *
       thread_func(void *ignored_argument)
       {
           int s;

           /* Disable cancellation for a while, so that we don't
              immediately react to a cancellation request */

           s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_setcancelstate");

           printf("thread_func(): started; cancellation disabled\n");
           sleep(5);
           printf("thread_func(): about to enable cancellation\n");

           s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_setcancelstate");

           /* sleep() is a cancellation point */

           sleep(1000);        /* Should get canceled while we sleep */

           /* Should never get here */

           printf("thread_func(): not canceled!\n");
           return NULL;
       }

       int
       main(void)
       {
           pthread_t thr;
           void *res;
           int s;

           /* Start a thread and then send it a cancellation request */

           s = pthread_create(&thr, NULL, &thread_func, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           sleep(2);           /* Give thread a chance to get started */

           printf("main(): sending cancellation request\n");
           s = pthread_cancel(thr);
           if (s != 0)
               handle_error_en(s, "pthread_cancel");

           /* Join with thread to see what its exit status was */

           s = pthread_join(thr, &res);
           if (s != 0)
               handle_error_en(s, "pthread_join");

           if (res == PTHREAD_CANCELED)
               printf("main(): thread was canceled\n");
           else
               printf("main(): thread wasn't canceled (shouldn't happen!)\n");
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       pthread_cleanup_push(3), pthread_create(3), pthread_exit(3),
       pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3),
       pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-17                   PTHREAD_CANCEL(3)


pthread_cleanup_push(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_CLEANUP_PUSH(3)      Linux Programmer's Manual     PTHREAD_CLEANUP_PUSH(3)

NAME top

       pthread_cleanup_push,  pthread_cleanup_pop  - push and pop thread cancella-
       tion clean-up handlers

SYNOPSIS top

       #include <pthread.h>

       void pthread_cleanup_push(void (*routine)(void *),
                                 void *arg);
       void pthread_cleanup_pop(int execute);

       Compile and link with -pthread.

DESCRIPTION top

       These functions manipulate the calling thread's stack of thread-
       cancellation clean-up handlers.  A clean-up handler is a function that is
       automatically executed when a thread is canceled (or in various other
       circumstances described below); it might, for example, unlock a mutex so
       that it becomes available to other threads in the process.

       The pthread_cleanup_push() function pushes routine onto the top of the
       stack of clean-up handlers.  When routine is later invoked, it will be
       given arg as its argument.

       The pthread_cleanup_pop() function removes the routine at the top of the
       stack of clean-up handlers, and optionally executes it if execute is
       nonzero.

       A cancellation clean-up handler is popped from the stack and executed in
       the following circumstances:

       1. When a thread is canceled, all of the stacked clean-up handlers are
          popped and executed in the reverse of the order in which they were
          pushed onto the stack.

       2. When a thread terminates by calling pthread_exit(3), all clean-up
          handlers are executed as described in the preceding point.  (Clean-up
          handlers are not called if the thread terminates by performing a return
          from the thread start function.)

       3. When a thread calls pthread_cleanup_pop() with a nonzero execute
          argument, the top-most clean-up handler is popped and executed.

       POSIX.1 permits pthread_cleanup_push() and pthread_cleanup_pop() to be
       implemented as macros that expand to text containing '{' and '}',
       respectively.  For this reason, the caller must ensure that calls to these
       functions are paired within the same function, and at the same lexical
       nesting level.  (In other words, a clean-up handler is only established
       during the execution of a specified section of code.)

       Calling longjmp(3) (siglongjmp(3)) produces undefined results if any call
       has been made to pthread_cleanup_push() or pthread_cleanup_pop() without
       the matching call of the pair since the jump buffer was filled by setjmp(3)
       (sigsetjmp(3)).  Likewise, calling longjmp(3) (siglongjmp(3)) from inside a
       clean-up handler produces undefined results unless the jump buffer was also
       filled by setjmp(3) (sigsetjmp(3)) inside the handler.

RETURN VALUE top

       These functions do not return a value.

ERRORS top

       There are no errors.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       On Linux, the pthread_cleanup_push() and pthread_cleanup_pop() functions
       are implemented as macros that expand to text containing '{' and '}',
       respectively.  This means that variables declared within the scope of
       paired calls to these functions will only be visible within that scope.

       POSIX.1 says that the effect of using return, break, continue, or goto to
       prematurely leave a block bracketed pthread_cleanup_push() and
       pthread_cleanup_pop() is undefined.  Portable applications should avoid
       doing this.

EXAMPLE top

       The program below provides a simple example of the use of the functions
       described in this page.  The program creates a thread that executes a loop
       bracketed by pthread_cleanup_push() and pthread_cleanup_pop().  This loop
       increments a global variable, cnt, once each second.  Depending on what
       command-line arguments are supplied, the main thread sends the other thread
       a cancellation request, or sets a global variable that causes the other
       thread to exit its loop and terminate normally (by doing a return).

       In the following shell session, the main thread sends a cancellation
       request to the other thread:

           $ ./a.out
           New thread started
           cnt = 0
           cnt = 1
           Canceling thread
           Called clean-up handler
           Thread was canceled; cnt = 0

       From the above, we see that the thread was canceled, and that the
       cancellation clean-up handler was called and it reset the value of the
       global variable cnt to 0.

       In the next run, the main program sets a global variable that causes other
       thread to terminate normally:

           $ ./a.out x
           New thread started
           cnt = 0
           cnt = 1
           Thread terminated normally; cnt = 2

       From the above, we see that the clean-up handler was not executed (because
       cleanup_pop_arg was 0), and therefore the value of cnt was not reset.

       In the next run, the main program sets a global variable that causes the
       other thread to terminate normally, and supplies a nonzero value for
       cleanup_pop_arg:

           $ ./a.out x 1
           New thread started
           cnt = 0
           cnt = 1
           Called clean-up handler
           Thread terminated normally; cnt = 0

       In the above, we see that although the thread was not canceled, the clean-
       up handler was executed, because the argument given to
       pthread_cleanup_pop() was nonzero.

Program source

       #include <pthread.h>
       #include <sys/types.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static int done = 0;
       static int cleanup_pop_arg = 0;
       static int cnt = 0;

       static void
       cleanup_handler(void *arg)
       {
           printf("Called clean-up handler\n");
           cnt = 0;
       }

       static void *
       thread_start(void *arg)
       {
           time_t start, curr;

           printf("New thread started\n");

           pthread_cleanup_push(cleanup_handler, NULL);

           curr = start = time(NULL);

           while (!done) {
               pthread_testcancel();           /* A cancellation point */
               if (curr < time(NULL)) {
                   curr = time(NULL);
                   printf("cnt = %d\n", cnt);  /* A cancellation point */
                   cnt++;
               }
           }

           pthread_cleanup_pop(cleanup_pop_arg);
           return NULL;
       }

       int
       main(int argc, char *argv[])
       {
           pthread_t thr;
           int s;
           void *res;

           s = pthread_create(&thr, NULL, thread_start, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           sleep(2);           /* Allow new thread to run a while */

           if (argc > 1) {
               if (argc > 2)
                   cleanup_pop_arg = atoi(argv[2]);
               done = 1;

           } else {
               printf("Canceling thread\n");
               s = pthread_cancel(thr);
               if (s != 0)
                   handle_error_en(s, "pthread_cancel");
           }

           s = pthread_join(thr, &res);
           if (s != 0)
               handle_error_en(s, "pthread_join");

           if (res == PTHREAD_CANCELED)
               printf("Thread was canceled; cnt = %d\n", cnt);
           else
               printf("Thread terminated normally; cnt = %d\n", cnt);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       pthread_cancel(3), pthread_cleanup_push_defer_np(3),
       pthread_setcancelstate(3), pthread_testcancel(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-24             PTHREAD_CLEANUP_PUSH(3)


pthread_cleanup_push_defer_np(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_CLEANUP_PUSH_DEFER_NP(L3i)nux Programmer's ManPuTaHlREAD_CLEANUP_PUSH_DEFER_NP(3)

NAME top

       pthread_cleanup_push_defer_np,  pthread_cleanup_pop_restore_np  -  push and
       pop thread cancellation clean-up handlers while saving cancelability type

SYNOPSIS top

       #include <pthread.h>

       void pthread_cleanup_push_defer_np(void (*routine)(void *),
                                          void *arg);
       void pthread_cleanup_pop_restore_np(int execute);

       Compile and link with -pthread.

DESCRIPTION top

       These functions are the same as pthread_cleanup_push(3) and
       pthread_cleanup_pop(3), except for the differences noted on this page.

       Like pthread_cleanup_push(3), pthread_cleanup_push_defer_np() pushes
       routine onto the thread's stack of cancellation clean-up handlers.  In
       addition, it also saves the thread's current cancelability type, and sets
       the cancelability type to "deferred" (see pthread_setcanceltype(3)); this
       ensures that cancellation clean-up will occur even if the thread's
       cancelability type was "asynchronous" before the call.

       Like pthread_cleanup_pop(3), pthread_cleanup_pop_restore_np() pops the top-
       most clean-up handler from the thread's stack of cancellation clean-up
       handlers.  In addition, it restores the thread's cancelability type to its
       value at the time of the matching pthread_cleanup_push_defer_np().

       The caller must ensure that calls to these functions are paired within the
       same function, and at the same lexical nesting level.  Other restrictions
       apply, as described in pthread_cleanup_push(3).

       This sequence of calls:

           pthread_cleanup_push_defer_np(routine, arg);
           pthread_cleanup_pop_restore_np(execute);

       is equivalent to (but shorter and more efficient than):

           int oldtype;

           pthread_cleanup_push(routine, arg);
           pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
           ...
           pthread_setcanceltype(oldtype, NULL);
           pthread_cleanup_pop(execute);

CONFORMING TO top

       These functions are nonstandard GNU extensions; hence the suffix "_np"
       (nonportable) in the names.

SEE ALSO top

       pthread_cancel(3), pthread_cleanup_push(3), pthread_setcancelstate(3),
       pthread_testcancel(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-04    PTHREAD_CLEANUP_PUSH_DEFER_NP(3)


pthread_create(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_CREATE(3)            Linux Programmer's Manual           PTHREAD_CREATE(3)

NAME top

       pthread_create - create a new thread

SYNOPSIS top

       #include <pthread.h>

       int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
                          void *(*start_routine) (void *), void *arg);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_create() function starts a new thread in the calling process.
       The new thread starts execution by invoking start_routine(); arg is passed
       as the sole argument of start_routine().

       The new thread terminates in one of the following ways:

       * It calls pthread_exit(3), specifying an exit status value that is
         available to another thread in the same process that calls
         pthread_join(3).

       * It returns from start_routine().  This is equivalent to calling
         pthread_exit(3) with the value supplied in the return statement.

       * It is canceled (see pthread_cancel(3)).

       * Any of the threads in the process calls exit(3), or the main thread
         performs a return from main().  This causes the termination of all
         threads in the process.

       The attr argument points to a pthread_attr_t structure whose contents are
       used at thread creation time to determine attributes for the new thread;
       this structure is initialized using pthread_attr_init(3) and related
       functions.  If attr is NULL, then the thread is created with default
       attributes.

       Before returning, a successful call to pthread_create() stores the ID of
       the new thread in the buffer pointed to by thread; this identifier is used
       to refer to the thread in subsequent calls to other pthreads functions.

       The new thread inherits a copy of the creating thread's signal mask
       (pthread_sigmask(3)).  The set of pending signals for the new thread is
       empty (sigpending(2)).  The new thread does not inherit the creating
       thread's alternate signal stack (sigaltstack(2)).

       The new thread inherits the calling thread's floating-point environment
       (fenv(3)).

       The initial value of the new thread's CPU-time clock is 0 (see
       pthread_getcpuclockid(3)).

Linux-specific details

       The new thread inherits copies of the calling thread's capability sets (see
       capabilities(7)) and CPU affinity mask (see sched_setaffinity(2)).

RETURN VALUE top

       On success, pthread_create() returns 0; on error, it returns an error
       number, and the contents of *thread are undefined.

ERRORS top

       EAGAIN Insufficient resources to create another thread, or a system-imposed
              limit on the number of threads was encountered.  The latter case may
              occur in two ways: the RLIMIT_NPROC soft resource limit (set via
              setrlimit(2)), which limits the number of process for a real user
              ID, was reached; or the kernel's system-wide limit on the number of
              threads, /proc/sys/kernel/threads-max, was reached.

       EINVAL Invalid settings in attr.

       EPERM  No permission to set the scheduling policy and parameters specified
              in attr.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       See pthread_self(3) for further information on the thread ID returned in
       *thread by pthread_create().  Unless real-time scheduling policies are
       being employed, after a call to pthread_create(), it is indeterminate which
       thread--the caller or the new thread--will next execute.

       A thread may either be joinable or detached.  If a thread is joinable, then
       another thread can call pthread_join(3) to wait for the thread to terminate
       and fetch its exit status.  Only when a terminated joinable thread has been
       joined are the last of its resources released back to the system.  When a
       detached thread terminates, its resources are automatically released back
       to the system: it is not possible to join with the thread in order to
       obtain its exit status.  Making a thread detached is useful for some types
       of daemon threads whose exit status the application does not need to care
       about.  By default, a new thread is created in a joinable state, unless
       attr was set to create the thread in a detached state (using
       pthread_attr_setdetachstate(3)).

       On Linux/x86-32, the default stack size for a new thread is 2 megabytes.
       Under the NPTL threading implementation, if the RLIMIT_STACK soft resource
       limit at the time the program started has any value other than "unlimited",
       then it determines the default stack size of new threads.  Using
       pthread_attr_setstacksize(3), the stack size attribute can be explicitly
       set in the attr argument used to create a thread, in order to obtain a
       stack size other than the default.

BUGS top

       In the obsolete LinuxThreads implementation, each of the threads in a
       process has a different process ID.  This is in violation of the POSIX
       threads specification, and is the source of many other nonconformances to
       the standard; see pthreads(7).

EXAMPLE top

       The program below demonstrates the use of pthread_create(), as well as a
       number of other functions in the pthreads API.

       In the following run, on a system providing the NPTL threading
       implementation, the stack size defaults to the value given by the "stack
       size" resource limit:

           $ ulimit -s
           8192            # The stack size limit is 8 MB (0x80000 bytes)
           $ ./a.out hola salut servus
           Thread 1: top of stack near 0xb7dd03b8; argv_string=hola
           Thread 2: top of stack near 0xb75cf3b8; argv_string=salut
           Thread 3: top of stack near 0xb6dce3b8; argv_string=servus
           Joined with thread 1; returned value was HOLA
           Joined with thread 2; returned value was SALUT
           Joined with thread 3; returned value was SERVUS

       In the next run, the program explicitly sets a stack size of 1MB (using
       pthread_attr_setstacksize(3)) for the created threads:

           $ ./a.out -s 0x100000 hola salut servus
           Thread 1: top of stack near 0xb7d723b8; argv_string=hola
           Thread 2: top of stack near 0xb7c713b8; argv_string=salut
           Thread 3: top of stack near 0xb7b703b8; argv_string=servus
           Joined with thread 1; returned value was HOLA
           Joined with thread 2; returned value was SALUT
           Joined with thread 3; returned value was SERVUS

Program source

       #include <pthread.h>
       #include <string.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>
       #include <ctype.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

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

       struct thread_info {    /* Used as argument to thread_start() */
           pthread_t thread_id;        /* ID returned by pthread_create() */
           int       thread_num;       /* Application-defined thread # */
           char     *argv_string;      /* From command-line argument */
       };

       /* Thread start function: display address near top of our stack,
          and return upper-cased copy of argv_string */

       static void *
       thread_start(void *arg)
       {
           struct thread_info *tinfo = arg;
           char *uargv, *p;

           printf("Thread %d: top of stack near %p; argv_string=%s\n",
                   tinfo->thread_num, &p, tinfo->argv_string);

           uargv = strdup(tinfo->argv_string);
           if (uargv == NULL)
               handle_error("strdup");

           for (p = uargv; *p != '\0'; p++)
               *p = toupper(*p);

           return uargv;
       }

       int
       main(int argc, char *argv[])
       {
           int s, tnum, opt, num_threads;
           struct thread_info *tinfo;
           pthread_attr_t attr;
           int stack_size;
           void *res;

           /* The "-s" option specifies a stack size for our threads */

           stack_size = -1;
           while ((opt = getopt(argc, argv, "s:")) != -1) {
               switch (opt) {
               case 's':
                   stack_size = strtoul(optarg, NULL, 0);
                   break;

               default:
                   fprintf(stderr, "Usage: %s [-s stack-size] arg...\n",
                           argv[0]);
                   exit(EXIT_FAILURE);
               }
           }

           num_threads = argc - optind;

           /* Initialize thread creation attributes */

           s = pthread_attr_init(&attr);
           if (s != 0)
               handle_error_en(s, "pthread_attr_init");

           if (stack_size > 0) {
               s = pthread_attr_setstacksize(&attr, stack_size);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setstacksize");
           }

           /* Allocate memory for pthread_create() arguments */

           tinfo = calloc(num_threads, sizeof(struct thread_info));
           if (tinfo == NULL)
               handle_error("calloc");

           /* Create one thread for each command-line argument */

           for (tnum = 0; tnum < num_threads; tnum++) {
               tinfo[tnum].thread_num = tnum + 1;
               tinfo[tnum].argv_string = argv[optind + tnum];

               /* The pthread_create() call stores the thread ID into
                  corresponding element of tinfo[] */

               s = pthread_create(&tinfo[tnum].thread_id, &attr,
                                  &thread_start, &tinfo[tnum]);
               if (s != 0)
                   handle_error_en(s, "pthread_create");
           }

           /* Destroy the thread attributes object, since it is no
              longer needed */

           s = pthread_attr_destroy(&attr);
           if (s != 0)
               handle_error_en(s, "pthread_attr_destroy");

           /* Now join with each thread, and display its returned value */

           for (tnum = 0; tnum < num_threads; tnum++) {
               s = pthread_join(tinfo[tnum].thread_id, &res);
               if (s != 0)
                   handle_error_en(s, "pthread_join");

               printf("Joined with thread %d; returned value was %s\n",
                       tinfo[tnum].thread_num, (char *) res);
               free(res);      /* Free memory allocated by thread */
           }

           free(tinfo);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getrlimit(2), pthread_attr_init(3), pthread_cancel(3), pthread_detach(3),
       pthread_equal(3), pthread_exit(3), pthread_getattr_np(3), pthread_join(3),
       pthread_self(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-03                   PTHREAD_CREATE(3)


pthread_detach(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_DETACH(3)            Linux Programmer's Manual           PTHREAD_DETACH(3)

NAME top

       pthread_detach - detach a thread

SYNOPSIS top

       #include <pthread.h>

       int pthread_detach(pthread_t thread);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_detach() function marks the thread identified by thread as
       detached.  When a detached thread terminates, its resources are
       automatically released back to the system without the need for another
       thread to join with the terminated thread.

       Attempting to detach an already detached thread results in unspecified
       behavior.

RETURN VALUE top

       On success, pthread_detach() returns 0; on error, it returns an error
       number.

ERRORS top

       EINVAL thread is not a joinable thread.

       ESRCH  No thread with the ID thread could be found.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Once a thread has been detached, it can't be joined with pthread_join(3) or
       be made joinable again.

       A new thread can be created in a detached state using
       pthread_attr_setdetachstate(3) to set the detached attribute of the attr
       argument of pthread_create(3).

       The detached attribute merely determines the behavior of the system when
       the thread terminates; it does not prevent the thread from being terminated
       if the process terminates using exit(3) (or equivalently, if the main
       thread returns).

       Either pthread_join(3) or pthread_detach() should be called for each thread
       that an application creates, so that system resources for the thread can be
       released.  (But note that the resources of all threads are freed when the
       process terminates.)

EXAMPLE top

       The following statement detaches the calling thread:

           pthread_detach(pthread_self());

SEE ALSO top

       pthread_attr_setdetachstate(3), pthread_cancel(3), pthread_create(3),
       pthread_exit(3), pthread_join(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                   PTHREAD_DETACH(3)


pthread_equal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_EQUAL(3)             Linux Programmer's Manual            PTHREAD_EQUAL(3)

NAME top

       pthread_equal - compare thread IDs

SYNOPSIS top

       #include <pthread.h>

       int pthread_equal(pthread_t t1, pthread_t t2);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_equal() function compares two thread identifiers.

RETURN VALUE top

       If the two thread IDs are equal, pthread_equal() returns a nonzero value;
       otherwise, it returns 0.

ERRORS top

       This function always succeeds.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The pthread_equal() function is necessary because thread IDs should be
       considered opaque: there is no portable way for applications to directly
       compare two pthread_t values.

SEE ALSO top

       pthread_create(3), pthread_self(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-03-30                    PTHREAD_EQUAL(3)


pthread_exit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_EXIT(3)              Linux Programmer's Manual             PTHREAD_EXIT(3)

NAME top

       pthread_exit - terminate calling thread

SYNOPSIS top

       #include <pthread.h>

       void pthread_exit(void *retval);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_exit() function terminates the calling thread and returns a
       value via retval that (if the thread is joinable) is available to another
       thread in the same process that calls pthread_join(3).

       Any clean-up handlers established by pthread_cleanup_push(3) that have not
       yet been popped, are popped (in the reverse of the order in which they were
       pushed) and executed.  If the thread has any thread-specific data, then,
       after the clean-up handlers have been executed, the corresponding
       destructor functions are called, in an unspecified order.

       When a thread terminates, process-shared resources (e.g., mutexes,
       condition variables, semaphores, and file descriptors) are not released,
       and functions registered using atexit(3) are not called.

       After the last thread in a process terminates, the process terminates as by
       calling exit(3) with an exit status of zero; thus, process-shared resources
       are released and functions registered using atexit(3) are called.

RETURN VALUE top

       This function does not return to the caller.

ERRORS top

       This function always succeeds.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Performing a return from the start function of any thread other than the
       main thread results in an implicit call to pthread_exit(), using the
       function's return value as the thread's exit status.

       To allow other threads to continue execution, the main thread should
       terminate by calling pthread_exit() rather than exit(3).

       The value pointed to by retval should not be located on the calling
       thread's stack, since the contents of that stack are undefined after the
       thread terminates.

BUGS top

       Currently, there are limitations in the kernel implementation logic for
       wait(2)ing on a stopped thread group with a dead thread group leader.  This
       can manifest in problems such as a locked terminal if a stop signal is sent
       to a foreground process whose thread group leader has already called
       pthread_exit().

SEE ALSO top

       pthread_create(3), pthread_join(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-03-30                     PTHREAD_EXIT(3)


pthread_setaffinity_np(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SETAFFINITY_NP(3)    Linux Programmer's Manual   PTHREAD_SETAFFINITY_NP(3)

NAME top

       pthread_setaffinity_np,  pthread_getaffinity_np - set/get CPU affinity of a
       thread

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <pthread.h>

       int pthread_setaffinity_np(pthread_t thread, size_t cpusetsize,
                                  const cpu_set_t *cpuset);
       int pthread_getaffinity_np(pthread_t thread, size_t cpusetsize,
                                  cpu_set_t *cpuset);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_setaffinity_np() function sets the CPU affinity mask of the
       thread thread to the CPU set pointed to by cpuset.  If the call is
       successful, and the thread is not currently running on one of the CPUs in
       cpuset, then it is migrated to one of those CPUs.

       The pthread_getaffinity_np() function returns the CPU affinity mask of the
       thread thread in the buffer pointed to by cpuset.

       For more details on CPU affinity masks, see sched_setaffinity(2).  For a
       description of a set of macros that can be used to manipulate and inspect
       CPU sets, see CPU_SET(3).

       The argument cpusetsize is the length (in bytes) of the buffer pointed to
       by cpuset.  Typically, this argument would be specified as
       sizeof(cpu_set_t).  (It may be some other value, if using the macros
       described in CPU_SET(3) for dynamically allocating a CPU set.)

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       EFAULT A supplied memory address was invalid.

       EINVAL (pthread_setaffinity_np()) The affinity bit mask mask contains no
              processors that are currently physically on the system and permitted
              to the thread according to any restrictions that may be imposed by
              the "cpuset" mechanism described in cpuset(7).

       EINVAL (pthread_setaffinity_np()) cpuset specified a CPU that was outside
              the set supported by the kernel.  (The kernel configuration option
              CONFIG_NR_CPUS defines the range of the set supported by the kernel
              data type used to represent CPU sets.)

       EINVAL (pthread_getaffinity_np()) cpusetsize is smaller than the size of
              the affinity mask used by the kernel.

       ESRCH  No thread with the ID thread could be found.

VERSIONS top

       These functions are provided by glibc since version 2.3.4.

CONFORMING TO top

       These functions are nonstandard GNU extensions; hence the suffix "_np"
       (nonportable) in the names.

NOTES top

       After a call to pthread_setaffinity_np(), the set of CPUs on which the
       thread will actually run is the intersection of the set specified in the
       cpuset argument and the set of CPUs actually present on the system.  The
       system may further restrict the set of CPUs on which the thread runs if the
       "cpuset" mechanism described in cpuset(7) is being used.  These
       restrictions on the actual set of CPUs on which the thread will run are
       silently imposed by the kernel.

       These functions are implemented on top of the sched_setaffinity(2) and
       sched_getaffinity(2) system calls.

       In glibc 2.3.3 only, versions of these functions were provided that did not
       have a cpusetsize argument.  Instead the CPU set size given to the
       underlying system calls was always sizeof(cpu_set_t).

       A new thread created by pthread_create(3) inherits a copy of its creator's
       CPU affinity mask.

EXAMPLE top

       In the following program, the main thread uses pthread_setaffinity_np() to
       set its CPU affinity mask to include CPUs 0 to 7 (which may not all be
       available on the system), and then calls pthread_getaffinity_np() to check
       the resulting CPU affinity mask of the thread.

       #define _GNU_SOURCE
       #include <pthread.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <errno.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       int
       main(int argc, char *argv[])
       {
           int s, j;
           cpu_set_t cpuset;
           pthread_t thread;

           thread = pthread_self();

           /* Set affinity mask to include CPUs 0 to 7 */

           CPU_ZERO(&cpuset);
           for (j = 0; j < 8; j++)
               CPU_SET(j, &cpuset);

           s = pthread_setaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
           if (s != 0)
               handle_error_en(s, "pthread_setaffinity_np");

           /* Check the actual affinity mask assigned to the thread */

           s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
           if (s != 0)
               handle_error_en(s, "pthread_getaffinity_np");

           printf("Set returned by pthread_getaffinity_np() contained:\n");
           for (j = 0; j < CPU_SETSIZE; j++)
               if (CPU_ISSET(j, &cpuset))
                   printf("    CPU %d\n", j);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       sched_setaffinity(2), sched_setscheduler(2),
       pthread_attr_setaffinity_np(3), pthread_self(3), sched_getcpu(3),
       cpuset(7), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10           PTHREAD_SETAFFINITY_NP(3)


pthread_getattr_np(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_GETATTR_NP(3)        Linux Programmer's Manual       PTHREAD_GETATTR_NP(3)

NAME top

       pthread_getattr_np - get attributes of created thread

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <pthread.h>

       int pthread_getattr_np(pthread_t thread, pthread_attr_t *attr);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_getattr_np() function initializes the thread attributes object
       referred to by attr so that it contains actual attribute values describing
       the running thread thread.

       The returned attribute values may differ from the corresponding attribute
       values passed in the attr object that was used to create the thread using
       pthread_create(3).  In particular, the following attributes may differ:

       * the detach state, since a joinable thread may have detached itself after
         creation;

       * the stack size, which the implementation may align to a suitable
         boundary.

       * and the guard size, which the implementation may round upward to a
         multiple of the page size, or ignore (i.e., treat as 0), if the
         application is allocating its own stack.

       Furthermore, if the stack address attribute was not set in the thread
       attributes object used to create the thread, then the returned thread
       attributes object will report the actual stack address that the
       implementation selected for the thread.

       When the thread attributes object returned by pthread_getattr_np() is no
       longer required, it should be destroyed using pthread_attr_destroy(3).

RETURN VALUE top

       On success, this function returns 0; on error, it returns a nonzero error
       number.

ERRORS top

       ENOMEM Insufficient memory.

       In addition, if thread refers to the main thread, then pthread_getattr_np()
       can fail because of errors from various underlying calls: fopen(3), if
       /proc/self/maps can't be opened; and getrlimit(2), if the RLIMIT_STACK
       resource limit is not supported.

VERSIONS top

       This function is available in glibc since version 2.2.3.

CONFORMING TO top

       This function is a nonstandard GNU extension; hence the suffix "_np"
       (nonportable) in the name.

EXAMPLE top

       The program below demonstrates the use of pthread_getattr_np().  The
       program creates a thread that then uses pthread_getattr_np() to retrieve
       and display its guard size, stack address, and stack size attributes.
       Command-line arguments can be used to set these attributes to values other
       than the default when creating the thread.  The shell sessions below
       demonstrate the use of the program.

       In the first run, on an x86-32 system, a thread is created using default
       attributes:

           $ ulimit -s      # No stack limit ==> default stack size is 2MB
           unlimited
           $ ./a.out
           Attributes of created thread:
                   Guard size          = 4096 bytes
                   Stack address       = 0x40196000 (EOS = 0x40397000)
                   Stack size          = 0x201000 (2101248) bytes

       In the following run, we see that if a guard size is specified, it is
       rounded up to the next multiple of the system page size (4096 bytes on
       x86-32):

           $ ./a.out -g 4097
           Thread attributes object after initializations:
                   Guard size          = 4097 bytes
                   Stack address       = (nil)
                   Stack size          = 0x0 (0) bytes

           Attributes of created thread:
                   Guard size          = 8192 bytes
                   Stack address       = 0x40196000 (EOS = 0x40397000)
                   Stack size          = 0x201000 (2101248) bytes

       In the last run, the program manually allocates a stack for the thread.  In
       this case, the guard size attribute is ignored.

           $ ./a.out -g 4096 -s 0x8000 -a
           Allocated thread stack at 0x804d000

           Thread attributes object after initializations:
                   Guard size          = 4096 bytes
                   Stack address       = 0x804d000 (EOS = 0x8055000)
                   Stack size          = 0x8000 (32768) bytes

           Attributes of created thread:
                   Guard size          = 0 bytes
                   Stack address       = 0x804d000 (EOS = 0x8055000)
                   Stack size          = 0x8000 (32768) bytes

Program source

       #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
       #include <pthread.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void
       display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
       {
           int s;
           size_t stack_size, guard_size;
           void *stack_addr;

           s = pthread_attr_getguardsize(attr, &guard_size);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getguardsize");
           printf("%sGuard size          = %d bytes\n", prefix, guard_size);

           s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
           if (s != 0)
               handle_error_en(s, "pthread_attr_getstack");
           printf("%sStack address       = %p", prefix, stack_addr);
           if (stack_size > 0)
               printf(" (EOS = %p)", (char *) stack_addr + stack_size);
           printf("\n");
           printf("%sStack size          = 0x%x (%d) bytes\n",
                   prefix, stack_size, stack_size);
       }

       static void
       display_thread_attributes(pthread_t thread, char *prefix)
       {
           int s;
           pthread_attr_t attr;

           s = pthread_getattr_np(thread, &attr);
           if (s != 0)
               handle_error_en(s, "pthread_getattr_np");

           display_stack_related_attributes(&attr, prefix);

           s = pthread_attr_destroy(&attr);
           if (s != 0)
               handle_error_en(s, "pthread_attr_destroy");
       }

       static void *           /* Start function for thread we create */
       thread_start(void *arg)
       {
           printf("Attributes of created thread:\n");
           display_thread_attributes(pthread_self(), "\t");

           exit(EXIT_SUCCESS);         /* Terminate all threads */
       }

       static void
       usage(char *pname, char *msg)
       {
           if (msg != NULL)
               fputs(msg, stderr);
           fprintf(stderr, "Usage: %s [-s stack-size [-a]]"
                   " [-g guard-size]\n", pname);
           fprintf(stderr, "\t\t-a means program should allocate stack\n");
           exit(EXIT_FAILURE);
       }

       static pthread_attr_t *   /* Get thread attributes from command line */
       get_thread_attributes_from_cl(int argc, char *argv[],
                                     pthread_attr_t *attrp)
       {
           int s, opt, allocate_stack;
           long stack_size, guard_size;
                   void *stack_addr;
           pthread_attr_t *ret_attrp = NULL;   /* Set to attrp if we initialize
                                                  a thread attributes object */
           allocate_stack = 0;
           stack_size = -1;
           guard_size = -1;

           while ((opt = getopt(argc, argv, "ag:s:")) != -1) {
               switch (opt) {
               case 'a':   allocate_stack = 1;                     break;
               case 'g':   guard_size = strtoul(optarg, NULL, 0);  break;
               case 's':   stack_size = strtoul(optarg, NULL, 0);  break;
               default:    usage(argv[0], NULL);
               }
           }

           if (allocate_stack && stack_size == -1)
               usage(argv[0], "Specifying -a without -s makes no sense\n");

           if (argc > optind)
               usage(argv[0], "Extraneous command-line arguments\n");

           if (stack_size >= 0 || guard_size > 0) {
               ret_attrp = attrp;

               s = pthread_attr_init(attrp);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_init");
           }

           if (stack_size >= 0) {
               if (!allocate_stack) {
                   s = pthread_attr_setstacksize(attrp, stack_size);
                   if (s != 0)
                       handle_error_en(s, "pthread_attr_setstacksize");
               } else {
                   s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
                                      stack_size);
                   if (s != 0)
                       handle_error_en(s, "posix_memalign");
                   printf("Allocated thread stack at %p\n\n", stack_addr);

                   s = pthread_attr_setstack(attrp, stack_addr, stack_size);
                   if (s != 0)
                       handle_error_en(s, "pthread_attr_setstacksize");
               }
           }

           if (guard_size >= 0) {
               s = pthread_attr_setguardsize(attrp, guard_size);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setstacksize");
           }

           return ret_attrp;
       }

       int
       main(int argc, char *argv[])
       {
           int s;
           pthread_t thr;
           pthread_attr_t attr;
           pthread_attr_t *attrp = NULL;    /* Set to &attr if we initialize
                                               a thread attributes object */

           attrp = get_thread_attributes_from_cl(argc, argv, &attr);

           if (attrp != NULL) {
               printf("Thread attributes object after initializations:\n");
               display_stack_related_attributes(attrp, "\t");
               printf("\n");
           }

           s = pthread_create(&thr, attrp, &thread_start, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           if (attrp != NULL) {
               s = pthread_attr_destroy(attrp);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_destroy");
           }

           pause();    /* Terminates when other thread calls exit() */
       }

SEE ALSO top

       pthread_attr_getaffinity_np(3), pthread_attr_getdetachstate(3),
       pthread_attr_getguardsize(3), pthread_attr_getinheritsched(3),
       pthread_attr_getschedparam(3), pthread_attr_getschedpolicy(3),
       pthread_attr_getscope(3), pthread_attr_getstack(3),
       pthread_attr_getstackaddr(3), pthread_attr_getstacksize(3),
       pthread_attr_init(3), pthread_create(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10               PTHREAD_GETATTR_NP(3)


pthread_setconcurrency(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SETCONCURRENCY(3)    Linux Programmer's Manual   PTHREAD_SETCONCURRENCY(3)

NAME top

       pthread_setconcurrency,  pthread_getconcurrency  -  set/get the concurrency
       level

SYNOPSIS top

       #include <pthread.h>

       int pthread_setconcurrency(int new_level);
       int pthread_getconcurrency(void);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_setconcurrency() function informs the implementation of the
       application's desired concurrency level, specified in new_level.  The
       implementation only takes this as a hint: POSIX.1 does not specify the
       level of concurrency that should be provided as a result of calling
       pthread_setconcurrency().

       Specifying new_level as 0 instructs the implementation to manage the
       concurrency level as it deems appropriate.

       pthread_getconcurrency() returns the current value of the concurrency level
       for this process.

RETURN VALUE top

       On success, pthread_setconcurrency() returns 0; on error, it returns a
       nonzero error number.

       pthread_getconcurrency() always succeeds, returning the concurrency level
       set by a previous call to pthread_setconcurrency(), or 0, if
       pthread_setconcurrency() has not previously been called.

ERRORS top

       pthread_setconcurrency() can fail with the following error:

       EINVAL new_level is negative.

       POSIX.1-2001 also documents an EAGAIN error ("the value specified by
       new_level would cause a system resource to be exceeded").

VERSIONS top

       These functions are available in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The default concurrency level is 0.

       Concurrency levels are only meaningful for M:N threading implementations,
       where at any moment a subset of a process's set of user-level threads may
       be bound to a smaller number of kernel-scheduling entities.  Setting the
       concurrency level allows the application to give the system a hint as to
       the number of kernel-scheduling entities that should be provided for
       efficient execution of the application.

       Both LinuxThreads and NPTL are 1:1 threading implementations, so setting
       the concurrency level has no meaning.  In other words, on Linux these
       functions merely exist for compatibility with other systems, and they have
       no effect on the execution of a program.

SEE ALSO top

       pthread_attr_setscope(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-04-10           PTHREAD_SETCONCURRENCY(3)


pthread_getcpuclockid(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_GETCPUCLOCKID(3)     Linux Programmer's Manual    PTHREAD_GETCPUCLOCKID(3)

NAME top

       pthread_getcpuclockid - retrieve ID of a thread's CPU time clock

SYNOPSIS top

       #include <pthread.h>
       #include <time.h>

       int pthread_getcpuclockid(pthread_t thread, clockid_t *[22mclock_id);[0m

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_getcpuclockid() function returns the clock ID for the CPU time
       clock of the thread thread.

RETURN VALUE top

       On success, this function returns 0; on error, it returns a nonzero error
       number.

ERRORS top

       ENOENT Per-thread CPU time clocks are not supported by the system.

       ESRCH  No thread with the ID thread could be found.

VERSIONS top

       This function is available in glibc since version 2.2.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       When thread refers to the calling thread, this function returns an
       identifier that refers to the same clock manipulated by clock_gettime(2)
       and clock_settime(2) when given the clock ID CLOCK_THREAD_CPUTIME_ID.

EXAMPLE top

       The program below creates a thread and then uses clock_gettime(2) to
       retrieve the total process CPU time, and the per-thread CPU time consumed
       by the two threads.  The following shell session shows an example run:
           $ ./a.out
           Main thread sleeping
           Subthread starting infinite loop
           Main thread consuming some CPU time...
           Process total CPU time:    1.368
           Main thread CPU time:      0.376
           Subthread CPU time:        0.992

Program source

       /* Link with "-lrt" */

       #include <time.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <pthread.h>
       #include <string.h>
       #include <errno.h>

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

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void *
       thread_start(void *arg)
       {
           printf("Subthread starting infinite loop\n");
           for (;;)
               continue;
       }

       static void
       pclock(char *msg, clockid_t cid)
       {
           struct timespec ts;

           printf("%s", msg);
           if (clock_gettime(cid, &ts) == -1)
               handle_error("clock_gettime");
           printf("%4ld.%03ld\n", ts.tv_sec, ts.tv_nsec / 1000000);
       }

       int
       main(int argc, char *argv[])
       {
           pthread_t thread;
           clockid_t cid;
           int j, s;

           s = pthread_create(&thread, NULL, thread_start, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           printf("Main thread sleeping\n");
           sleep(1);

           printf("Main thread consuming some CPU time...\n");
           for (j = 0; j < 2000000; j++)
               getppid();

           pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);

           s = pthread_getcpuclockid(pthread_self(), &cid);
           if (s != 0)
               handle_error_en(s, "pthread_getcpuclockid");
           pclock("Main thread CPU time:   ", cid);

           /* The preceding 4 lines of code could have been replaced by:
              pclock("Main thread CPU time:   ", CLOCK_THREAD_CPUTIME_ID); */

           s = pthread_getcpuclockid(thread, &cid);
           if (s != 0)
               handle_error_en(s, "pthread_getcpuclockid");
           pclock("Subthread CPU time: 1    ", cid);

           exit(EXIT_SUCCESS);         /* Terminates both threads */
       }

SEE ALSO top

       clock_gettime(2), clock_settime(2), timer_create(2),
       clock_getcpuclockid(3), pthread_self(3), pthreads(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-08            PTHREAD_GETCPUCLOCKID(3)


pthread_setschedparam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SETSCHEDPARAM(3)     Linux Programmer's Manual    PTHREAD_SETSCHEDPARAM(3)

NAME top

       pthread_setschedparam,  pthread_getschedparam  -  set/get scheduling policy
       and parameters of a thread

SYNOPSIS top

       #include <pthread.h>

       pthread_setschedparam(pthread_t thread, int policy,
                             const struct sched_param *param);
       pthread_getschedparam(pthread_t thread, int *policy,
                             struct sched_param *param);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_setschedparam() function sets the scheduling policy and
       parameters of the thread thread.

       policy specifies the new scheduling policy for thread.  The supported
       values for policy, and their semantics, are described in
       sched_setscheduler(2).

       The structure pointed to by param specifies the new scheduling parameters
       for thread.  Scheduling parameters are maintained in the following
       structure:

           struct sched_param {
               int sched_priority;     /* Scheduling priority */
           };

       As can be seen, only one scheduling parameter is supported.  For details of
       the permitted ranges for scheduling priorities in each scheduling policy,
       see sched_setscheduler(2).

       The pthread_getschedparam() function returns the scheduling policy and
       parameters of the thread thread, in the buffers pointed to by policy and
       param, respectively.  The returned priority value is that set by the most
       recent pthread_setschedparam(), pthread_setschedprio(3), or
       pthread_create(3) call that affected thread.  The returned priority does
       not reflect any temporary priority adjustments as a result of calls to any
       priority inheritance or priority ceiling functions (see, for example,
       pthread_mutexattr_setprioceiling(3) and pthread_mutexattr_setprotocol(3)).

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.  If pthread_setschedparam() fails, the scheduling policy and
       parameters of thread are not changed.

ERRORS top

       Both of these functions can fail with the following error:

       ESRCH  No thread with the ID thread could be found.

       pthread_setschedparam() may additionally fail with the following errors:

       EINVAL policy is not a recognized policy, or param does not make sense for
              the policy.

       EPERM  The caller does not have appropriate privileges to set the specified
              scheduling policy and parameters.

       POSIX.1-2001 also documents an ENOTSUP ("attempt was made to set the policy
       or scheduling parameters to an unsupported value") error for
       pthread_setschedparam().

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       For a description of the permissions required to, and the effect of,
       changing a thread's scheduling policy and priority, and details of the
       permitted ranges for priorities in each scheduling policy, see
       sched_setscheduler(2).

EXAMPLE top

       The program below demonstrates the use of pthread_setschedparam() and
       pthread_getschedparam(), as well as the use of a number of other
       scheduling-related pthreads functions.

       In the following run, the main thread sets its scheduling policy to
       SCHED_FIFO with a priority of 10, and initializes a thread attributes
       object with a scheduling policy attribute of SCHED_RR and a scheduling
       priority attribute of 20.  The program then sets (using
       pthread_attr_setinheritsched(3)) the inherit scheduler attribute of the
       thread attributes object to PTHREAD_EXPLICIT_SCHED, meaning that threads
       created using this attributes object should take their scheduling
       attributes from the thread attributes object.  The program then creates a
       thread using the thread attributes object, and that thread displays its
       scheduling policy and priority.

           $ su      # Need privilege to set real-time scheduling policies
           Password:
           # ./a.out -mf10 -ar20 -i e
           Scheduler settings of main thread
               policy=SCHED_FIFO, priority=10

           Scheduler settings in 'attr'
               policy=SCHED_RR, priority=20
               inheritsched is EXPLICIT

           Scheduler attributes of new thread
               policy=SCHED_RR, priority=20

       In the above output, one can see that the scheduling policy and priority
       were taken from the values specified in the thread attributes object.

       The next run is the same as the previous, except that the inherit scheduler
       attribute is set to PTHREAD_INHERIT_SCHED, meaning that threads created
       using the thread attributes object should ignore the scheduling attributes
       specified in the attributes object and instead take their scheduling
       attributes from the creating thread.

           # ./a.out -mf10 -ar20 -i i
           Scheduler settings of main thread
               policy=SCHED_FIFO, priority=10

           Scheduler settings in 'attr'
               policy=SCHED_RR, priority=20
               inheritsched is INHERIT

           Scheduler attributes of new thread
               policy=SCHED_FIFO, priority=10

       In the above output, one can see that the scheduling policy and priority
       were taken from the creating thread, rather than the thread attributes
       object.

       Note that if we had omitted the -i i option, the output would have been the
       same, since PTHREAD_INHERIT_SCHED is the default for the inherit scheduler
       attribute.

Program source

       /* pthreads_sched_test.c */

       #include <pthread.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void
       usage(char *prog_name, char *msg)
       {
           if (msg != NULL)
               fputs(msg, stderr);

           fprintf(stderr, "Usage: %s [options]\n", prog_name);
           fprintf(stderr, "Options are:\n");
       #define fpe(msg) fprintf(stderr, "\t%s", msg);          /* Shorter */
           fpe("-a<policy><prio> Set scheduling policy and priority in\n");
           fpe("                 thread attributes object\n");
           fpe("                 <policy> can be\n");
           fpe("                     f  SCHED_FIFO\n");
           fpe("                     r  SCHED_RR\n");
           fpe("                     o  SCHED_OTHER\n");
           fpe("-A               Use default thread attributes object\n");
           fpe("-i {e|s}         Set inherit scheduler attribute to\n");
           fpe("                 'explicit' or 'inherit'\n");
           fpe("-m<policy><prio> Set scheduling policy and priority on\n");
           fpe("                 main thread before pthread_create() call\n");
           exit(EXIT_FAILURE);
       }

       static int
       get_policy(char p, int *policy)
       {
           switch (p) {
           case 'f': *policy = SCHED_FIFO;     return 1;
           case 'r': *policy = SCHED_RR;       return 1;
           case 'o': *policy = SCHED_OTHER;    return 1;
           default:  return 0;
           }
       }

       static void
       display_sched_attr(int policy, struct sched_param *param)
       {
           printf("    policy=%s, priority=%d\n",
                   (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
                   (policy == SCHED_RR)    ? "SCHED_RR" :
                   (policy == SCHED_OTHER) ? "SCHED_OTHER" :
                   "???",
                   param->sched_priority);
       }

       static void
       display_thread_sched_attr(char *msg)
       {
           int policy, s;
           struct sched_param param;

           s = pthread_getschedparam(pthread_self(), &policy, &param);
           if (s != 0)
               handle_error_en(s, "pthread_getschedparam");

           printf("%s\n", msg);
           display_sched_attr(policy, &param);
       }

       static void *
       thread_start(void *arg)
       {
           display_thread_sched_attr("Scheduler attributes of new thread");

           return NULL;
       }

       int
       main(int argc, char *argv[])
       {
           int s, opt, inheritsched, use_null_attrib, policy;
           pthread_t thread;
           pthread_attr_t attr;
           pthread_attr_t *attrp;
           char *attr_sched_str, *main_sched_str, *inheritsched_str;
           struct sched_param param;

           /* Process command-line options */

           use_null_attrib = 0;
           attr_sched_str = NULL;
           main_sched_str = NULL;
           inheritsched_str = NULL;

           while ((opt = getopt(argc, argv, "a:Ai:m:")) != -1) {
               switch (opt) {
               case 'a': attr_sched_str = optarg;      break;
               case 'A': use_null_attrib = 1;          break;
               case 'i': inheritsched_str = optarg;    break;
               case 'm': main_sched_str = optarg;      break;
               default:  usage(argv[0], "Unrecognized option\n");
               }
           }

           if (use_null_attrib &&
                   (inheritsched_str != NULL || attr_sched_str != NULL))
               usage(argv[0], "Can't specify -A with -i or -a\n");

           /* Optionally set scheduling attributes of main thread,
              and display the attributes */

           if (main_sched_str != NULL) {
               if (!get_policy(main_sched_str[0], &policy))
                   usage(argv[0], "Bad policy for main thread (-s)\n");
               param.sched_priority = strtol(&main_sched_str[1], NULL, 0);

               s = pthread_setschedparam(pthread_self(), policy, &param);
               if (s != 0)
                   handle_error_en(s, "pthread_setschedparam");
           }

           display_thread_sched_attr("Scheduler settings of main thread");
           printf("\n");

           /* Initialize thread attributes object according to options */

           attrp = NULL;

           if (!use_null_attrib) {
               s = pthread_attr_init(&attr);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_init");
               attrp = &attr;
           }

           if (inheritsched_str != NULL) {
               if (inheritsched_str[0] == 'e')
                   inheritsched = PTHREAD_EXPLICIT_SCHED;
               else if (inheritsched_str[0] == 'i')
                   inheritsched = PTHREAD_INHERIT_SCHED;
               else
                   usage(argv[0], "Value for -i must be 'e' or 'i'\n");

               s = pthread_attr_setinheritsched(&attr, inheritsched);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setinheritsched");
           }

           if (attr_sched_str != NULL) {
               if (!get_policy(attr_sched_str[0], &policy))
                   usage(argv[0],
                           "Bad policy for 'attr' (-a)\n");
               param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);

               s = pthread_attr_setschedpolicy(&attr, policy);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setschedpolicy");
               s = pthread_attr_setschedparam(&attr, &param);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_setschedparam");
           }

           /* If we initialized a thread attributes object, display
              the scheduling attributes that were set in the object */

           if (attrp != NULL) {
               s = pthread_attr_getschedparam(&attr, &param);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_getschedparam");
               s = pthread_attr_getschedpolicy(&attr, &policy);
               if (s != 0)
                   handle_error_en(s, "pthread_attr_getschedpolicy");

               printf("Scheduler settings in 'attr'\n");
               display_sched_attr(policy, &param);

               s = pthread_attr_getinheritsched(&attr, &inheritsched);
               printf("    inheritsched is %s\n",
                       (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
                       (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
                       "???");
               printf("\n");
           }

           /* Create a thread that will display its scheduling attributes */

           s = pthread_create(&thread, attrp, &thread_start, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           /* Destroy unneeded thread attributes object */

           s = pthread_attr_destroy(&attr);
           if (s != 0)
               handle_error_en(s, "pthread_attr_destroy");

           s = pthread_join(thread, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_join");

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       getrlimit(2), sched_get_priority_min(2), sched_setscheduler(2),
       pthread_attr_init(3), pthread_attr_setinheritsched(3),
       pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
       pthread_create(3), pthread_self(3), pthread_setschedprio(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-17            PTHREAD_SETSCHEDPARAM(3)


pthread_join(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_JOIN(3)              Linux Programmer's Manual             PTHREAD_JOIN(3)

NAME top

       pthread_join - join with a terminated thread

SYNOPSIS top

       #include <pthread.h>

       int pthread_join(pthread_t thread, void **retval);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_join() function waits for the thread specified by thread to
       terminate.  If that thread has already terminated, then pthread_join()
       returns immediately.  The thread specified by thread must be joinable.

       If retval is not NULL, then pthread_join() copies the exit status of the
       target thread (i.e., the value that the target thread supplied to
       pthread_exit(3)) into the location pointed to by *retval.  If the target
       thread was canceled, then PTHREAD_CANCELED is placed in *retval.

       If multiple threads simultaneously try to join with the same thread, the
       results are undefined.  If the thread calling pthread_join() is canceled,
       then the target thread will remain joinable (i.e., it will not be
       detached).

RETURN VALUE top

       On success, pthread_join() returns 0; on error, it returns an error number.

ERRORS top

       EDEADLK
              A deadlock was detected (e.g., two threads tried to join with each
              other); or thread specifies the calling thread.

       EINVAL thread is not a joinable thread.

       EINVAL Another thread is already waiting to join with this thread.

       ESRCH  No thread with the ID thread could be found.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       After a successful call to pthread_join(), the caller is guaranteed that
       the target thread has terminated.

       Joining with a thread that has previously been joined results in undefined
       behavior.

       Failure to join with a thread that is joinable (i.e., one that is not
       detached), produces a "zombie thread".  Avoid doing this, since each zombie
       thread consumes some system resources, and when enough zombie threads have
       accumulated, it will no longer be possible to create new threads (or
       processes).

       There is no pthreads analog of waitpid(-1, &status, 0), that is, "join with
       any terminated thread".  If you believe you need this functionality, you
       probably need to rethink your application design.

       All of the threads in a process are peers: any thread can join with any
       other thread in the process.

EXAMPLE top

       See pthread_create(3).

SEE ALSO top

       pthread_cancel(3), pthread_create(3), pthread_detach(3), pthread_exit(3),
       pthread_tryjoin_np(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                     PTHREAD_JOIN(3)


pthread_kill(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_KILL(3)              Linux Programmer's Manual             PTHREAD_KILL(3)

NAME top

       pthread_kill - send a signal to a thread

SYNOPSIS top

       #include <signal.h>

       int pthread_kill(pthread_t thread, int sig);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_kill() function sends the signal sig to thread, a thread in the
       same process as the caller.  The signal is asynchronously directed to
       thread.

       If sig is 0, then no signal is sent, but error checking is still performed;
       this can be used to check for the existence of a thread ID.

RETURN VALUE top

       On success, pthread_kill() returns 0; on error, it returns an error number,
       and no signal is sent.

ERRORS top

       EINVAL An invalid signal was specified.

       ESRCH  No thread with the ID thread could be found.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Signal dispositions are process-wide: if a signal handler is installed, the
       handler will be invoked in the thread thread, but if the disposition of the
       signal is "stop", "continue", or "terminate", this action will affect the
       whole process.

SEE ALSO top

       kill(2), sigaction(2), sigpending(2), pthread_self(3), pthread_sigmask(3),
       raise(3), pthreads(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-19                     PTHREAD_KILL(3)


pthread_kill_other_threads_np(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_KILL_OTHER_THREADS_NP(L3i)nux Programmer's ManPuTaHlREAD_KILL_OTHER_THREADS_NP(3)

NAME top

       pthread_kill_other_threads_np - terminate all other threads in process

SYNOPSIS top

       #include <pthread.h>

       void pthread_kill_other_threads_np(void);

DESCRIPTION top

       pthread_kill_other_threads_np() only has an effect in the LinuxThreads
       threading implementation.  On that implementation, calling this function
       causes the immediate termination of all threads in the application, except
       the calling thread.  The cancellation state and cancellation type of the
       to-be-terminated threads are ignored, and the cleanup handlers are not
       called in those threads.

CONFORMING TO top

       This function is a nonstandard GNU extension; hence the suffix "_np"
       (nonportable) in the name.

NOTES top

       pthread_kill_other_threads_np() is intended to be called just before a
       thread calls execve(2) or a similar function.  This function is designed to
       address a limitation in the obsolete LinuxThreads implementation whereby
       the other threads of an application are not automatically terminated (as
       POSIX.1-2001 requires) during execve(2).

       In the NPTL threading implementation, pthread_kill_other_threads_np()
       exists, but does nothing.  (Nothing needs to be done, because the
       implementation does the right thing during an execve(2).)

SEE ALSO top

       execve(2), pthread_cancel(3), pthread_setcancelstate(3),
       pthread_setcanceltype(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-09    PTHREAD_KILL_OTHER_THREADS_NP(3)


pthread_self(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SELF(3)              Linux Programmer's Manual             PTHREAD_SELF(3)

NAME top

       pthread_self - obtain ID of the calling thread

SYNOPSIS top

       #include <pthread.h>

       pthread_t pthread_self(void);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_self() function returns the ID of the calling thread.  This is
       the same value that is returned in *thread in the pthread_create(3) call
       that created this thread.

RETURN VALUE top

       This function always succeeds, returning the calling thread's ID.

ERRORS top

       This function always succeeds.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       POSIX.1 allows an implementation wide freedom in choosing the type used to
       represent a thread ID; for example, representation using either an
       arithmetic type or a structure is permitted.  Therefore, variables of type
       pthread_t can't portably be compared using the C equality operator (==);
       use pthread_equal(3) instead.

       Thread identifiers should be considered opaque: any attempt to use a thread
       ID other than in pthreads calls is nonportable and can lead to unspecified
       results.

       Thread IDs are only guaranteed to be unique within a process.  A thread ID
       may be reused after a terminated thread has been joined, or a detached
       thread has terminated.

       The thread ID returned by pthread_self() is not the same thing as the
       kernel thread ID returned by a call to gettid(2).

SEE ALSO top

       pthread_create(3), pthread_equal(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-10-24                     PTHREAD_SELF(3)


pthread_setcancelstate(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SETCANCELSTATE(3)    Linux Programmer's Manual   PTHREAD_SETCANCELSTATE(3)

NAME top

       pthread_setcancelstate, pthread_setcanceltype - set cancelability state and
       type

SYNOPSIS top

       #include <pthread.h>

       int pthread_setcancelstate(int state, int *oldstate);
       int pthread_setcanceltype(int type, int *oldtype);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_setcancelstate() sets the cancelability state of the calling
       thread to the value given in state.  The previous cancelability state of
       the thread is returned in the buffer pointed to by oldstate.  The state
       argument must have one of the following values:

       PTHREAD_CANCEL_ENABLE
              The thread is cancelable.  This is the default cancelability state
              in all new threads, including the initial thread.  The thread's
              cancelability type determines when a cancelable thread will respond
              to a cancellation request.

       PTHREAD_CANCEL_DISABLE
              The thread is not cancelable.  If a cancellation request is
              received, it is blocked until cancelability is enabled.

       The pthread_setcanceltype() sets the cancelability type of the calling
       thread to the value given in type.  The previous cancelability type of the
       thread is returned in the buffer pointed to by oldtype.  The type argument
       must have one of the following values:

       PTHREAD_CANCEL_DEFERRED
              A cancellation request is deferred until the thread next calls a
              function that is a cancellation point (see pthreads(7)).  This is
              the default cancelability type in all new threads, including the
              initial thread.

       PTHREAD_CANCEL_ASYNCHRONOUS
              The thread can be canceled at any time.  (Typically, it will be
              canceled immediately upon receiving a cancellation request, but the
              system doesn't guarantee this.)

       The set-and-get operation performed by each of these functions is atomic
       with respect to other threads in the process calling the same function.

RETURN VALUE top

       On success, these functions return 0; on error, they return a nonzero error
       number.

ERRORS top

       The pthread_setcancelstate() can fail with the following error:

       EINVAL Invalid value for state.

       The pthread_setcanceltype() can fail with the following error:

       EINVAL Invalid value for type.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       For details of what happens when a thread is canceled, see
       pthread_cancel(3).

       Briefly disabling cancelability is useful if a thread performs some
       critical action that must not be interrupted by a cancellation request.
       Beware of disabling cancelability for long periods, or around operations
       that may block for long periods, since that will render the thread
       unresponsive to cancellation requests.

       Setting the cancelability type to PTHREAD_CANCEL_ASYNCHRONOUS is rarely
       useful.  Since the thread could be canceled at any time, it cannot safely
       reserve resources (e.g., allocating memory with malloc(3)), acquire
       mutexes, semaphores, or locks, and so on.  Reserving resources is unsafe
       because the application has no way of knowing what the state of these
       resources is when the thread is canceled; that is, did cancellation occur
       before the resources were reserved, while they were reserved, or after they
       were released?  Furthermore, some internal data structures (e.g., the
       linked list of free blocks managed by the malloc(3) family of functions)
       may be left in an inconsistent state if cancellation occurs in the middle
       of the function call.  Consequently, clean-up handlers cease to be useful.
       Functions that can be safely asynchronously canceled are called async-
       cancel-safe functions.  POSIX.1-2001 only requires that pthread_cancel(3),
       pthread_setcancelstate(), and pthread_setcanceltype() be async-cancel-safe.
       In general, other library functions can't be safely called from an
       asynchronously cancelable thread.  One of the few circumstances in which
       asynchronous cancelability is useful is for cancellation of a thread that
       is in a pure compute-bound loop.

       The Linux threading implementations permit the oldstate argument of
       pthread_setcancelstate() to be NULL, in which case the information about
       the previous cancelability state is not returned to the caller.  Many other
       implementations also permit a NULL oldstat argument, but POSIX.1-2001 does
       not specify this point, so portable applications should always specify a
       non-NULL value in oldstate.  A precisely analogous set of statements
       applies for the oldtype argument of pthread_setcanceltype().

EXAMPLE top

       See pthread_cancel(3).

SEE ALSO top

       pthread_cancel(3), pthread_cleanup_push(3), pthread_testcancel(3),
       pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-24           PTHREAD_SETCANCELSTATE(3)


pthread_setschedprio(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SETSCHEDPRIO(3)      Linux Programmer's Manual     PTHREAD_SETSCHEDPRIO(3)

NAME top

       pthread_setschedprio - set scheduling priority of a thread

SYNOPSIS top

       #include <pthread.h>

       pthread_setschedprio(pthread_t thread, int prio);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_setschedprio() function sets the scheduling priority of the
       thread thread to the value specified in prio.  (By contrast
       pthread_setschedparam(3) changes both the scheduling policy and priority of
       a thread.)

RETURN VALUE top

       On success, this function returns 0; on error, it returns a nonzero error
       number.  If pthread_setschedprio() fails, the scheduling priority of thread
       is not changed.

ERRORS top

       EINVAL prio is not valid for the scheduling policy of the specified thread.

       EPERM  The caller does not have appropriate privileges to set the specified
              priority.

       ESRCH  No thread with the ID thread could be found.

       POSIX.1-2001 also documents an ENOTSUP ("attempt was made to set the
       priority to an unsupported value") error for pthread_setschedparam(3).

VERSIONS top

       This function is available in glibc since version 2.3.4.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       For a description of the permissions required to, and the effect of,
       changing a thread's scheduling priority, and details of the permitted
       ranges for priorities in each scheduling policy, see sched_setscheduler(2).

SEE ALSO top

       getrlimit(2), sched_get_priority_min(2), sched_setscheduler(2),
       pthread_attr_init(3), pthread_attr_setinheritsched(3),
       pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
       pthread_create(3), pthread_self(3), pthread_setschedparam(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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-06             PTHREAD_SETSCHEDPRIO(3)


pthread_sigmask(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SIGMASK(3)           Linux Programmer's Manual          PTHREAD_SIGMASK(3)

NAME top

       pthread_sigmask - examine and change mask of blocked signals

SYNOPSIS top

       #include <signal.h>

       int pthread_sigmask(int how, const sigset_t *set, sigset_t *oldset);

       Compile and link with -pthread.

DESCRIPTION top

       The pthread_sigmask() function is just like sigprocmask(2), with the
       difference that its use in multithreaded programs is explicitly specified
       by POSIX.1-2001.  Other differences are noted in this page.

       For a description of the arguments and operation of this function, see
       sigprocmask(2).

RETURN VALUE top

       On success, pthread_sigmask() returns 0; on error, it returns an error
       number.

ERRORS top

       See sigprocmask(2).

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       A new thread inherits a copy of its creator's signal mask.

EXAMPLE top

       The program below blocks some signals in the main thread, and then creates
       a dedicated thread to fetch those signals via sigwait(3).  The following
       shell session demonstrates its use:

           $ ./a.out &
           [1] 5423
           $ kill -QUIT %1
           Signal handling thread got signal 3
           $ kill -USR1 %1
           Signal handling thread got signal 10
           $ kill -TERM %1
           [1]+  Terminated              ./a.out

Program source

       #include <pthread.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <signal.h>
       #include <errno.h>

       /* Simple error handling functions */

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void *
       sig_thread(void *arg)
       {
           sigset_t *set = arg;
           int s, sig;

           for (;;) {
               s = sigwait(set, &sig);
               if (s != 0)
                   handle_error_en(s, "sigwait");
               printf("Signal handling thread got signal %d\n", sig);
           }
       }

       int
       main(int argc, char *argv[])
       {
           pthread_t thread;
           sigset_t set;
           int s;

           /* Block SIGQUIT and SIGUSR1; other threads created by main()
              will inherit a copy of the signal mask. */

           sigemptyset(&set);
           sigaddset(&set, SIGQUIT);
           sigaddset(&set, SIGUSR1);
           s = pthread_sigmask(SIG_BLOCK, &set, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_sigmask");

           s = pthread_create(&thread, NULL, &sig_thread, (void *) &set);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           /* Main thread carries on to create other threads and/or do
              other work */

           pause();            /* Dummy pause so we can test program */
       }

SEE ALSO top

       sigaction(2), sigpending(2), sigprocmask(2), pthread_create(3),
       pthread_kill(3), sigsetops(3), pthreads(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-03                  PTHREAD_SIGMASK(3)


pthread_sigqueue(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_SIGQUEUE(3)          Linux Programmer's Manual         PTHREAD_SIGQUEUE(3)

NAME top

       pthread_sigqueue - queue a signal and data to a thread

SYNOPSIS top

       #include <pthread.h>

       int pthread_sigqueue(pthread_t *thread, int sig,
                            const union sigval value);

       Compile and link with -pthread.

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

       pthread_sigqueue(): _GNU_SOURCE

DESCRIPTION top

       The pthread_sigqueue() function performs a similar task to sigqueue(3),
       but, rather than sending a signal to a process, it sends a signal to a
       thread in the same process as the calling thread.

       The thread argument is the ID of a thread in the same process as the
       caller.  The sig argument specifies the signal to be sent.  The value
       argument specifies data to accompany the signal; see sigqueue(3) for
       details.

RETURN VALUE top

       On success, pthread_sigqueue() returns 0; on error, it returns an error
       number.

ERRORS top

       EAGAIN The limit of signals which may be queued has been reached.  (See
              signal(7) for further information.)

       EINVAL sig was invalid.

       ENOSYS pthread_sigqueue() is not supported on this system.

       ESRCH  thread is not valid.

VERSIONS top

       The pthread_sigqueue() function first appeared in glibc 2.11.

CONFORMING TO top

       This function is a GNU extension.

SEE ALSO top

       rt_tgsigqueueinfo(2), sigaction(2), pthread_sigmask(3), sigqueue(3),
       sigwait(3), pthreads(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-19                 PTHREAD_SIGQUEUE(3)


pthread_testcancel(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_TESTCANCEL(3)        Linux Programmer's Manual       PTHREAD_TESTCANCEL(3)

NAME top

       pthread_testcancel - request delivery of any pending cancellation request

SYNOPSIS top

       #include <pthread.h>

       void pthread_testcancel(void);

       Compile and link with -pthread.

DESCRIPTION top

       Calling pthread_testcancel() creates a cancellation point within the
       calling thread, so that a thread that is otherwise executing code that
       contains no cancellation points will respond to a cancellation request.

       If cancelability is disabled (using pthread_setcancelstate(3)), or no
       cancellation request is pending, then a call to pthread_testcancel(3) has
       no effect.

RETURN VALUE top

       This function does not return a value.  If the calling thread is canceled
       as a consequence of a call to this function, then the function does not
       return.

ERRORS top

       This function always succeeds.

CONFORMING TO top

       POSIX.1-2001.

EXAMPLE top

       See pthread_cleanup_push(3).

SEE ALSO top

       pthread_cancel(3), pthread_cleanup_push(3), pthread_setcancelstate(3),
       pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-14               PTHREAD_TESTCANCEL(3)


pthread_tryjoin_np(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_TRYJOIN_NP(3)        Linux Programmer's Manual       PTHREAD_TRYJOIN_NP(3)

NAME top

       pthread_tryjoin_np,  pthread_timedjoin_np  -  try to join with a terminated
       thread

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <pthread.h>

       int pthread_tryjoin_np(pthread_t thread, void **retval);

       int pthread_timedjoin_np(pthread_t thread, void **retval,
                                const struct timespec *abstime);

       Compile and link with -pthread.

DESCRIPTION top

       These functions operate in the same way as pthread_join(3), except for the
       differences described on this page.

       The pthread_tryjoin_np() function performs a nonblocking join with the
       thread thread, returning the exit status of the thread in *retval.  If
       thread has not yet terminated, then instead of blocking, as is done by
       pthread_join(3), the call returns an error.

       The pthread_timedjoin_np() function performs a join-with-timeout.  If
       thread has not yet terminated, then the call blocks until a maximum time,
       specified in abstime.  If the timeout expires before thread terminates, the
       call returns an error.  The abstime argument is a structure of the
       following form, specifying an absolute time measured since the Epoch (see
       time(2)):

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

RETURN VALUE top

       On success, these functions return 0; on error, they return an error
       number.

ERRORS top

       These functions can fail with the same errors as pthread_join(3).
       pthread_tryjoin_np() can in addition fail with the following error:

       EBUSY  thread had not yet terminated at the time of the call.

       pthread_timedjoin_np() can in addition fail with the following error:

       ETIMEDOUT
              The call timed out before thread terminated.

       pthread_timedjoin_np() never returns the error EINTR.

VERSIONS top

       These functions first appeared in glibc in version 2.3.3.

CONFORMING TO top

       These functions are nonstandard GNU extensions; hence the suffix "_np"
       (nonportable) in the names.

EXAMPLE top

       The following code waits to join for up to 5 seconds:

           struct timespec ts;
           int s;

           ...

           if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {
            /* Handle error */
           }

           ts.tv_sec += 5;

           s = pthread_timedjoin_np(thread, NULL, &ts);
           if (s != 0) {
               /* Handle error */
           }

SEE ALSO top

       clock_gettime(2), pthread_exit(3), pthread_join(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10               PTHREAD_TRYJOIN_NP(3)


pthread_yield(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTHREAD_YIELD(3)             Linux Programmer's Manual            PTHREAD_YIELD(3)

NAME top

       pthread_yield - yield the processor

SYNOPSIS top

       #include <pthread.h>

       int pthread_yield(void);

       Compile and link with -pthread.

DESCRIPTION top

       pthread_yield() causes the calling thread to relinquish the CPU.  The
       thread is placed at the end of the run queue for its static priority and
       another thread is scheduled to run.  For further details, see
       sched_yield(2)

RETURN VALUE top

       On success, pthread_yield() returns 0; on error, it returns an error
       number.

ERRORS top

       On Linux, this call always succeeds (but portable and future-proof
       applications should nevertheless handle a possible error return).

CONFORMING TO top

       This call is nonstandard, but present on several other systems.  Use the
       standardized sched_yield(2) instead.

NOTES top

       On Linux, this function is implemented as a call to sched_yield(2).

SEE ALSO top

       sched_setscheduler(2), sched_yield(2), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-04-10                    PTHREAD_YIELD(3)


pts(4) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTS(4)                       Linux Programmer's Manual                      PTS(4)

NAME top

       ptmx, pts - pseudoterminal master and slave

DESCRIPTION top

       The file /dev/ptmx is a character file with major number 5 and minor number
       2, usually of mode 0666 and owner.group of root.root.  It is used to create
       a pseudoterminal master and slave pair.

       When a process opens /dev/ptmx, it gets a file descriptor for a
       pseudoterminal master (PTM), and a pseudoterminal slave (PTS) device is
       created in the /dev/pts directory.  Each file descriptor obtained by
       opening /dev/ptmx is an independent PTM with its own associated PTS, whose
       path can be found by passing the descriptor to ptsname(3).

       Before opening the pseudoterminal slave, you must pass the master's file
       descriptor to grantpt(3) and unlockpt(3).

       Once both the pseudoterminal master and slave are open, the slave provides
       processes with an interface that is identical to that of a real terminal.

       Data written to the slave is presented on the master descriptor as input.
       Data written to the master is presented to the slave as input.

       In practice, pseudoterminals are used for implementing terminal emulators
       such as xterm(1), in which data read from the pseudoterminal master is
       interpreted by the application in the same way a real terminal would
       interpret the data, and for implementing remote-login programs such as
       sshd(8), in which data read from the pseudoterminal master is sent across
       the network to a client program that is connected to a terminal or terminal
       emulator.

       Pseudoterminals can also be used to send input to programs that normally
       refuse to read input from pipes (such as su(1), and passwd(1)).

FILES top

       /dev/ptmx, /dev/pts/*

NOTES top

       The Linux support for the above (known as UNIX 98 pseudoterminal naming) is
       done using the devpts file system, that should be mounted on /dev/pts.

       Before this UNIX 98 scheme, master pseudoterminals were called /dev/ptyp0,
       ...  and slave pseudoterminals /dev/ttyp0, ...  and one needed lots of
       preallocated device nodes.

SEE ALSO top

       getpt(3), grantpt(3), ptsname(3), unlockpt(3), pty(7)

COLOPHON top

       This page is part of release 3.45 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-09                              PTS(4)


ptrace(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

PTRACE(2)                    Linux Programmer's Manual                   PTRACE(2)

NAME top

       ptrace - process trace

SYNOPSIS top

       #include <sys/ptrace.h>

       long ptrace(enum __ptrace_request request, pid_t pid,
                   void *addr, void *data);

DESCRIPTION top

       The ptrace() system call provides a means by which one process (the
       "tracer") may observe and control the execution of another process (the
       "tracee"), and examine and change the tracee's memory and registers.  It is
       primarily used to implement breakpoint debugging and system call tracing.

       A tracee first needs to be attached to the tracer.  Attachment and
       subsequent commands are per thread: in a multithreaded process, every
       thread can be individually attached to a (potentially different) tracer, or
       left not attached and thus not debugged.  Therefore, "tracee" always means
       "(one) thread", never "a (possibly multithreaded) process".  Ptrace
       commands are always sent to a specific tracee using a call of the form

           ptrace(PTRACE_foo, pid, ...)

       where pid is the thread ID of the corresponding Linux thread.

       (Note that in this page, a "multithreaded process" means a thread group
       consisting of threads created using the clone(2) CLONE_THREAD flag.)

       A process can initiate a trace by calling fork(2) and having the resulting
       child do a PTRACE_TRACEME, followed (typically) by an execve(2).
       Alternatively, one process may commence tracing another process using
       PTRACE_ATTACH.

       While being traced, the tracee will stop each time a signal is delivered,
       even if the signal is being ignored.  (An exception is SIGKILL, which has
       its usual effect.)  The tracer will be notified at its next call to
       waitpid(2) (or one of the related "wait" system calls); that call will
       return a status value containing information that indicates the cause of
       the stop in the tracee.  While the tracee is stopped, the tracer can use
       various ptrace requests to inspect and modify the tracee.  The tracer then
       causes the tracee to continue, optionally ignoring the delivered signal (or
       even delivering a different signal instead).

       If the PTRACE_O_TRACEEXEC option is not in effect, all successful calls to
       execve(2) by the traced process will cause it to be sent a SIGTRAP signal,
       giving the parent a chance to gain control before the new program begins
       execution.

       When the tracer is finished tracing, it can cause the tracee to continue
       executing in a normal, untraced mode via PTRACE_DETACH.

       The value of request determines the action to be performed:

       PTRACE_TRACEME
              Indicate that this process is to be traced by its parent.  A process
              probably shouldn't make this request if its parent isn't expecting
              to trace it.  (pid, addr, and data are ignored.)

       The PTRACE_TRACEME request is used only by the tracee; the remaining
       requests are used only by the tracer.  In the following requests, pid
       specifies the thread ID of the tracee to be acted on.  For requests other
       than PTRACE_ATTACH and PTRACE_KILL, the tracee must be stopped.

       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
              Read a word at the address addr in the tracee's memory, returning
              the word as the result of the ptrace() call.  Linux does not have
              separate text and data address spaces, so these two requests are
              currently equivalent.  (data is ignored.)

       PTRACE_PEEKUSER
              Read a word at offset addr in the tracee's USER area, which holds
              the registers and other information about the process (see
              <sys/user.h>).  The word is returned as the result of the ptrace()
              call.  Typically, the offset must be word-aligned, though this might
              vary by architecture.  See NOTES.  (data is ignored.)

       PTRACE_POKETEXT, PTRACE_POKEDATA
              Copy the word data to the address addr in the tracee's memory.  As
              for PTRACE_PEEKTEXT and PTRACE_PEEKDATA, these two requests are
              currently equivalent.

       PTRACE_POKEUSER
              Copy the word data to offset addr in the tracee's USER area.  As for
              PTRACE_PEEKUSER, the offset must typically be word-aligned.  In
              order to maintain the integrity of the kernel, some modifications to
              the USER area are disallowed.

       PTRACE_GETREGS, PTRACE_GETFPREGS
              Copy the tracee's general-purpose or floating-point registers,
              respectively, to the address data in the tracer.  See <sys/user.h>
              for information on the format of this data.  (addr is ignored.)
              Note that SPARC systems have the meaning of data and addr reversed;
              that is, data is ignored and the registers are copied to the address
              addr.  PTRACE_GETREGS and PTRACE_GETFPREGS are not present on all
              architectures.

       PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
              Retrieve information about the signal that caused the stop.  Copy a
              siginfo_t structure (see sigaction(2)) from the tracee to the
              address data in the tracer.  (addr is ignored.)

       PTRACE_SETREGS, PTRACE_SETFPREGS
              Copy the tracee's general-purpose or floating-point registers,
              respectively, from the address data in the tracer.  As for
              PTRACE_POKEUSER, some general-purpose register modifications may be
              disallowed.  (addr is ignored.)  Note that SPARC systems have the
              meaning of data and addr reversed; that is, data is ignored and the
              registers are copied from the address addr.  PTRACE_SETREGS and
              PTRACE_SETFPREGS are not present on all architectures.

       PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
              Set signal information: copy a siginfo_t structure from the address
              data in the tracer to the tracee.  This will affect only signals
              that would normally be delivered to the tracee and were caught by
              the tracer.  It may be difficult to tell these normal signals from
              synthetic signals generated by ptrace() itself.  (addr is ignored.)

       PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
              Set ptrace options from data.  (addr is ignored.)  data is
              interpreted as a bit mask of options, which are specified by the
              following flags:

              PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
                     When delivering system call traps, set bit 7 in the signal
                     number (i.e., deliver SIGTRAP|0x80).  This makes it easy for
                     the tracer to distinguish normal traps from those caused by a
                     system call.  (PTRACE_O_TRACESYSGOOD may not work on all
                     architectures.)

              PTRACE_O_TRACEFORK (since Linux 2.5.46)
                     Stop the tracee at the next fork(2) and automatically start
                     tracing the newly forked process, which will start with a
                     SIGSTOP.  A waitpid(2) by the tracer will return a status
                     value such that

                       status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))

                     The PID of the new process can be retrieved with
                     PTRACE_GETEVENTMSG.

              PTRACE_O_TRACEVFORK (since Linux 2.5.46)
                     Stop the tracee at the next vfork(2) and automatically start
                     tracing the newly vforked process, which will start with a
                     SIGSTOP.  A waitpid(2) by the tracer will return a status
                     value such that

                       status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))

                     The PID of the new process can be retrieved with
                     PTRACE_GETEVENTMSG.

              PTRACE_O_TRACECLONE (since Linux 2.5.46)
                     Stop the tracee at the next clone(2) and automatically start
                     tracing the newly cloned process, which will start with a
                     SIGSTOP.  A waitpid(2) by the tracer will return a status
                     value such that

                       status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))

                     The PID of the new process can be retrieved with
                     PTRACE_GETEVENTMSG.

                     This option may not catch clone(2) calls in all cases.  If
                     the tracee calls clone(2) with the CLONE_VFORK flag,
                     PTRACE_EVENT_VFORK will be delivered instead if
                     PTRACE_O_TRACEVFORK is set; otherwise if the tracee calls
                     clone(2) with the exit signal set to SIGCHLD,
                     PTRACE_EVENT_FORK will be delivered if PTRACE_O_TRACEFORK is
                     set.

              PTRACE_O_TRACEEXEC (since Linux 2.5.46)
                     Stop the tracee at the next execve(2).  A waitpid(2) by the
                     tracer will return a status value such that

                       status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))

                     If the execing thread is not a thread group leader, the
                     thread ID is reset to thread group leader's ID before this
                     stop.  Since Linux 3.0, the former thread ID can be retrieved
                     with PTRACE_GETEVENTMSG.

              PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
                     Stop the tracee at the completion of the next vfork(2).  A
                     waitpid(2) by the tracer will return a status value such that

                       status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))

                     The PID of the new process can (since Linux 2.6.18) be
                     retrieved with PTRACE_GETEVENTMSG.

              PTRACE_O_TRACEEXIT (since Linux 2.5.60)
                     Stop the tracee at exit.  A waitpid(2) by the tracer will
                     return a status value such that

                       status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))

                     The tracee's exit status can be retrieved with
                     PTRACE_GETEVENTMSG.

                     The tracee is stopped early during process exit, when
                     registers are still available, allowing the tracer to see
                     where the exit occurred, whereas the normal exit notification
                     is done after the process is finished exiting.  Even though
                     context is available, the tracer cannot prevent the exit from
                     happening at this point.

       PTRACE_GETEVENTMSG (since Linux 2.5.46)
              Retrieve a message (as an unsigned long) about the ptrace event that
              just happened, placing it at the address data in the tracer.  For
              PTRACE_EVENT_EXIT, this is the tracee's exit status.  For
              PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK, PTRACE_EVENT_VFORK_DONE, and
              PTRACE_EVENT_CLONE, this is the PID of the new process.  (addr is
              ignored.)

       PTRACE_CONT
              Restart the stopped tracee process.  If data is nonzero, it is
              interpreted as the number of a signal to be delivered to the tracee;
              otherwise, no signal is delivered.  Thus, for example, the tracer
              can control whether a signal sent to the tracee is delivered or not.
              (addr is ignored.)

       PTRACE_SYSCALL, PTRACE_SINGLESTEP
              Restart the stopped tracee as for PTRACE_CONT, but arrange for the
              tracee to be stopped at the next entry to or exit from a system
              call, or after execution of a single instruction, respectively.
              (The tracee will also, as usual, be stopped upon receipt of a
              signal.)  From the tracer's perspective, the tracee will appear to
              have been stopped by receipt of a SIGTRAP.  So, for PTRACE_SYSCALL,
              for example, the idea is to inspect the arguments to the system call
              at the first stop, then do another PTRACE_SYSCALL and inspect the
              return value of the system call at the second stop.  The data
              argument is treated as for PTRACE_CONT.  (addr is ignored.)

       PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
              For PTRACE_SYSEMU, continue and stop on entry to the next system
              call, which will not be executed.  For PTRACE_SYSEMU_SINGLESTEP, do
              the same but also singlestep if not a system call.  This call is
              used by programs like User Mode Linux that want to emulate all the
              tracee's system calls.  The data argument is treated as for
              PTRACE_CONT.  The addr argument is ignored.  These requests are
              currently supported only on x86.

       PTRACE_KILL
              Send the tracee a SIGKILL to terminate it.  (addr and data are
              ignored.)

              This operation is deprecated; do not use it!  Instead, send a
              SIGKILL directly using kill(2) or tgkill(2).  The problem with
              PTRACE_KILL is that it requires the tracee to be in signal-delivery-
              stop, otherwise it may not work (i.e., may complete successfully but
              won't kill the tracee).  By contrast, sending a SIGKILL directly has
              no such limitation.

       PTRACE_ATTACH
              Attach to the process specified in pid, making it a tracee of the
              calling process.  The tracee is sent a SIGSTOP, but will not
              necessarily have stopped by the completion of this call; use
              waitpid(2) to wait for the tracee to stop.  See the "Attaching and
              detaching" subsection for additional information.  (addr and data
              are ignored.)

       PTRACE_DETACH
              Restart the stopped tracee as for PTRACE_CONT, but first detach from
              it.  Under Linux, a tracee can be detached in this way regardless of
              which method was used to initiate tracing.  (addr is ignored.)

Death under ptrace

       When a (possibly multithreaded) process receives a killing signal (one
       whose disposition is set to SIG_DFL and whose default action is to kill the
       process), all threads exit.  Tracees report their death to their tracer(s).
       Notification of this event is delivered via waitpid(2).

       Note that the killing signal will first cause signal-delivery-stop (on one
       tracee only), and only after it is injected by the tracer (or after it was
       dispatched to a thread which isn't traced), will death from the signal
       happen on all tracees within a multithreaded process.  (The term "signal-
       delivery-stop" is explained below.)

       SIGKILL does not generate signal-delivery-stop and therefore the tracer
       can't suppress it.  SIGKILL kills even within system calls (syscall-exit-
       stop is not generated prior to death by SIGKILL).  The net effect is that
       SIGKILL always kills the process (all its threads), even if some threads of
       the process are ptraced.

       When the tracee calls _exit(2), it reports its death to its tracer.  Other
       threads are not affected.

       When any thread executes exit_group(2), every tracee in its thread group
       reports its death to its tracer.

       If the PTRACE_O_TRACEEXIT option is on, PTRACE_EVENT_EXIT will happen
       before actual death.  This applies to exits via exit(2), exit_group(2), and
       signal deaths (except SIGKILL), and when threads are torn down on execve(2)
       in a multithreaded process.

       The tracer cannot assume that the ptrace-stopped tracee exists.  There are
       many scenarios when the tracee may die while stopped (such as SIGKILL).
       Therefore, the tracer must be prepared to handle an ESRCH error on any
       ptrace operation.  Unfortunately, the same error is returned if the tracee
       exists but is not ptrace-stopped (for commands which require a stopped
       tracee), or if it is not traced by the process which issued the ptrace
       call.  The tracer needs to keep track of the stopped/running state of the
       tracee, and interpret ESRCH as "tracee died unexpectedly" only if it knows
       that the tracee has been observed to enter ptrace-stop.  Note that there is
       no guarantee that waitpid(WNOHANG) will reliably report the tracee's death
       status if a ptrace operation returned ESRCH.  waitpid(WNOHANG) may return 0
       instead.  In other words, the tracee may be "not yet fully dead", but
       already refusing ptrace requests.

       The tracer can't assume that the tracee always ends its life by reporting
       WIFEXITED(status) or WIFSIGNALED(status); there are cases where this does
       not occur.  For example, if a thread other than thread group leader does an
       execve(2), it disappears; its PID will never be seen again, and any
       subsequent ptrace stops will be reported under the thread group leader's
       PID.

Stopped states

       A tracee can be in two states: running or stopped.

       There are many kinds of states when the tracee is stopped, and in ptrace
       discussions they are often conflated.  Therefore, it is important to use
       precise terms.

       In this manual page, any stopped state in which the tracee is ready to
       accept ptrace commands from the tracer is called ptrace-stop.  Ptrace-stops
       can be further subdivided into signal-delivery-stop, group-stop, syscall-
       stop, and so on.  These stopped states are described in detail below.

       When the running tracee enters ptrace-stop, it notifies its tracer using
       waitpid(2) (or one of the other "wait" system calls).  Most of this manual
       page assumes that the tracer waits with:

           pid = waitpid(pid_or_minus_1, &status, __WALL);

       Ptrace-stopped tracees are reported as returns with pid greater than 0 and
       WIFSTOPPED(status) true.

       The __WALL flag does not include the WSTOPPED and WEXITED flags, but
       implies their functionality.

       Setting the WCONTINUED flag when calling waitpid(2) is not recommended: the
       "continued" state is per-process and consuming it can confuse the real
       parent of the tracee.

       Use of the WNOHANG flag may cause waitpid(2) to return 0 ("no wait results
       available yet") even if the tracer knows there should be a notification.
       Example:

           errno = 0;
           ptrace(PTRACE_CONT, pid, 0L, 0L);
           if (errno == ESRCH) {
               /* tracee is dead */
               r = waitpid(tracee, &status, __WALL | WNOHANG);
               /* r can still be 0 here! */
           }

       The following kinds of ptrace-stops exist: signal-delivery-stops, group-
       stops, PTRACE_EVENT stops, syscall-stops.  They all are reported by
       waitpid(2) with WIFSTOPPED(status) true.  They may be differentiated by
       examining the value status>>8, and if there is ambiguity in that value, by
       querying PTRACE_GETSIGINFO.  (Note: the WSTOPSIG(status) macro can't be
       used to perform this examination, because it returns the value
       (status>>8) & 0xff.)

Signal-delivery-stop

       When a (possibly multithreaded) process receives any signal except SIGKILL,
       the kernel selects an arbitrary thread which handles the signal.  (If the
       signal is generated with tgkill(2), the target thread can be explicitly
       selected by the caller.)  If the selected thread is traced, it enters
       signal-delivery-stop.  At this point, the signal is not yet delivered to
       the process, and can be suppressed by the tracer.  If the tracer doesn't
       suppress the signal, it passes the signal to the tracee in the next ptrace
       restart request.  This second step of signal delivery is called signal
       injection in this manual page.  Note that if the signal is blocked, signal-
       delivery-stop doesn't happen until the signal is unblocked, with the usual
       exception that SIGSTOP can't be blocked.

       Signal-delivery-stop is observed by the tracer as waitpid(2) returning with
       WIFSTOPPED(status) true, with the signal returned by WSTOPSIG(status).  If
       the signal is SIGTRAP, this may be a different kind of ptrace-stop; see the
       "Syscall-stops" and "execve" sections below for details.  If
       WSTOPSIG(status) returns a stopping signal, this may be a group-stop; see
       below.

Signal injection and suppression

       After signal-delivery-stop is observed by the tracer, the tracer should
       restart the tracee with the call

           ptrace(PTRACE_restart, pid, 0, sig)

       where PTRACE_restart is one of the restarting ptrace requests.  If sig is
       0, then a signal is not delivered.  Otherwise, the signal sig is delivered.
       This operation is called signal injection in this manual page, to
       distinguish it from signal-delivery-stop.

       The sig value may be different from the WSTOPSIG(status) value: the tracer
       can cause a different signal to be injected.

       Note that a suppressed signal still causes system calls to return
       prematurely.  In this case system calls will be restarted: the tracer will
       observe the tracee to reexecute the interrupted system call (or
       restart_syscall(2) system call for a few syscalls which use a different
       mechanism for restarting) if the tracer uses PTRACE_SYSCALL.  Even system
       calls (such as poll(2)) which are not restartable after signal are
       restarted after signal is suppressed; however, kernel bugs exist which
       cause some syscalls to fail with EINTR even though no observable signal is
       injected to the tracee.

       Restarting ptrace commands issued in ptrace-stops other than signal-
       delivery-stop are not guaranteed to inject a signal, even if sig is
       nonzero.  No error is reported; a nonzero sig may simply be ignored.
       Ptrace users should not try to "create a new signal" this way: use
       tgkill(2) instead.

       The fact that signal injection requests may be ignored when restarting the
       tracee after ptrace stops that are not signal-delivery-stops is a cause of
       confusion among ptrace users.  One typical scenario is that the tracer
       observes group-stop, mistakes it for signal-delivery-stop, restarts the
       tracee with

           ptrace(PTRACE_rest, pid, 0, stopsig)

       with the intention of injecting stopsig, but stopsig gets ignored and the
       tracee continues to run.

       The SIGCONT signal has a side effect of waking up (all threads of) a group-
       stopped process.  This side effect happens before signal-delivery-stop.
       The tracer can't suppress this side effect (it can only suppress signal
       injection, which only causes the SIGCONT handler to not be executed in the
       tracee, if such a handler is installed).  In fact, waking up from group-
       stop may be followed by signal-delivery-stop for signal(s) other than
       SIGCONT, if they were pending when SIGCONT was delivered.  In other words,
       SIGCONT may be not the first signal observed by the tracee after it was
       sent.

       Stopping signals cause (all threads of) a process to enter group-stop.
       This side effect happens after signal injection, and therefore can be
       suppressed by the tracer.

       In Linux 2.4 and earlier, the SIGSTOP signal can't be injected.

       PTRACE_GETSIGINFO can be used to retrieve a siginfo_t structure which
       corresponds to the delivered signal.  PTRACE_SETSIGINFO may be used to
       modify it.  If PTRACE_SETSIGINFO has been used to alter siginfo_t, the
       si_signo field and the sig parameter in the restarting command must match,
       otherwise the result is undefined.

Group-stop

       When a (possibly multithreaded) process receives a stopping signal, all
       threads stop.  If some threads are traced, they enter a group-stop.  Note
       that the stopping signal will first cause signal-delivery-stop (on one
       tracee only), and only after it is injected by the tracer (or after it was
       dispatched to a thread which isn't traced), will group-stop be initiated on
       all tracees within the multithreaded process.  As usual, every tracee
       reports its group-stop separately to the corresponding tracer.

       Group-stop is observed by the tracer as waitpid(2) returning with
       WIFSTOPPED(status) true, with the stopping signal available via
       WSTOPSIG(status).  The same result is returned by some other classes of
       ptrace-stops, therefore the recommended practice is to perform the call

           ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)

       The call can be avoided if the signal is not SIGSTOP, SIGTSTP, SIGTTIN, or
       SIGTTOU; only these four signals are stopping signals.  If the tracer sees
       something else, it can't be a group-stop.  Otherwise, the tracer needs to
       call PTRACE_GETSIGINFO.  If PTRACE_GETSIGINFO fails with EINVAL, then it is
       definitely a group-stop.  (Other failure codes are possible, such as ESRCH
       ("no such process") if a SIGKILL killed the tracee.)

       As of kernel 2.6.38, after the tracer sees the tracee ptrace-stop and until
       it restarts or kills it, the tracee will not run, and will not send
       notifications (except SIGKILL death) to the tracer, even if the tracer
       enters into another waitpid(2) call.

       The kernel behavior described in the previous paragraph causes a problem
       with transparent handling of stopping signals.  If the tracer restarts the
       tracee after group-stop, the stopping signal is effectively ignored--the
       tracee doesn't remain stopped, it runs.  If the tracer doesn't restart the
       tracee before entering into the next waitpid(2), future SIGCONT signals
       will not be reported to the tracer; this would cause the SIGCONT signals to
       have no effect on the tracee.

PTRACE_EVENT stops

       If the tracer sets PTRACE_O_TRACE_* options, the tracee will enter ptrace-
       stops called PTRACE_EVENT stops.

       PTRACE_EVENT stops are observed by the tracer as waitpid(2) returning with
       WIFSTOPPED(status), and WSTOPSIG(status) returns SIGTRAP.  An additional
       bit is set in the higher byte of the status word: the value status>>8 will
       be

           (SIGTRAP | PTRACE_EVENT_foo << 8).

       The following events exist:

       PTRACE_EVENT_VFORK
              Stop before return from vfork(2) or clone(2) with the CLONE_VFORK
              flag.  When the tracee is continued after this stop, it will wait
              for child to exit/exec before continuing its execution (in other
              words, the usual behavior on vfork(2)).

       PTRACE_EVENT_FORK
              Stop before return from fork(2) or clone(2) with the exit signal set
              to SIGCHLD.

       PTRACE_EVENT_CLONE
              Stop before return from clone(2).

       PTRACE_EVENT_VFORK_DONE
              Stop before return from vfork(2) or clone(2) with the CLONE_VFORK
              flag, but after the child unblocked this tracee by exiting or
              execing.

       For all four stops described above, the stop occurs in the parent (i.e.,
       the tracee), not in the newly created thread.  PTRACE_GETEVENTMSG can be
       used to retrieve the new thread's ID.

       PTRACE_EVENT_EXEC
              Stop before return from execve(2).  Since Linux 3.0,
              PTRACE_GETEVENTMSG returns the former thread ID.

       PTRACE_EVENT_EXIT
              Stop before exit (including death from exit_group(2)), signal death,
              or exit caused by execve(2) in a multithreaded process.
              PTRACE_GETEVENTMSG returns the exit status.  Registers can be
              examined (unlike when "real" exit happens).  The tracee is still
              alive; it needs to be PTRACE_CONTed or PTRACE_DETACHed to finish
              exiting.

       PTRACE_GETSIGINFO on PTRACE_EVENT stops returns SIGTRAP in si_signo, with
       si_code set to (event<<8) | SIGTRAP.

Syscall-stops

       If the tracee was restarted by PTRACE_SYSCALL, the tracee enters syscall-
       enter-stop just prior to entering any system call.  If the tracer restarts
       the tracee with PTRACE_SYSCALL, the tracee enters syscall-exit-stop when
       the system call is finished, or if it is interrupted by a signal.  (That
       is, signal-delivery-stop never happens between syscall-enter-stop and
       syscall-exit-stop; it happens after syscall-exit-stop.)

       Other possibilities are that the tracee may stop in a PTRACE_EVENT stop,
       exit (if it entered _exit(2) or exit_group(2)), be killed by SIGKILL, or
       die silently (if it is a thread group leader, the execve(2) happened in
       another thread, and that thread is not traced by the same tracer; this
       situation is discussed later).

       Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
       waitpid(2) returning with WIFSTOPPED(status) true, and WSTOPSIG(status)
       giving SIGTRAP.  If the PTRACE_O_TRACESYSGOOD option was set by the tracer,
       then WSTOPSIG(status) will give the value (SIGTRAP | 0x80).

       Syscall-stops can be distinguished from signal-delivery-stop with SIGTRAP
       by querying PTRACE_GETSIGINFO for the following cases:

       si_code <= 0
              SIGTRAP was delivered as a result of a user-space action, for
              example, a system call (tgkill(2), kill(2), sigqueue(3), etc.),
              expiration of a POSIX timer, change of state on a POSIX message
              queue, or completion of an asynchronous I/O request.

       si_code == SI_KERNEL (0x80)
              SIGTRAP was sent by the kernel.

       si_code == SIGTRAP or si_code == (SIGTRAP|0x80)
              This is a syscall-stop.

       However, syscall-stops happen very often (twice per system call), and
       performing PTRACE_GETSIGINFO for every syscall-stop may be somewhat
       expensive.

       Some architectures allow the cases to be distinguished by examining
       registers.  For example, on x86, rax == -ENOSYS in syscall-enter-stop.
       Since SIGTRAP (like any other signal) always happens after syscall-exit-
       stop, and at this point rax almost never contains -ENOSYS, the SIGTRAP
       looks like "syscall-stop which is not syscall-enter-stop"; in other words,
       it looks like a "stray syscall-exit-stop" and can be detected this way.
       But such detection is fragile and is best avoided.

       Using the PTRACE_O_TRACESYSGOOD option is the recommended method to
       distinguish syscall-stops from other kinds of ptrace-stops, since it is
       reliable and does not incur a performance penalty.

       Syscall-enter-stop and syscall-exit-stop are indistinguishable from each
       other by the tracer.  The tracer needs to keep track of the sequence of
       ptrace-stops in order to not misinterpret syscall-enter-stop as syscall-
       exit-stop or vice versa.  The rule is that syscall-enter-stop is always
       followed by syscall-exit-stop, PTRACE_EVENT stop or the tracee's death; no
       other kinds of ptrace-stop can occur in between.

       If after syscall-enter-stop, the tracer uses a restarting command other
       than PTRACE_SYSCALL, syscall-exit-stop is not generated.

       PTRACE_GETSIGINFO on syscall-stops returns SIGTRAP in si_signo, with
       si_code set to SIGTRAP or (SIGTRAP|0x80).

PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops

       [Details of these kinds of stops are yet to be documented.]

Informational and restarting ptrace commands

       Most ptrace commands (all except PTRACE_ATTACH, PTRACE_TRACEME, and
       PTRACE_KILL) require the tracee to be in a ptrace-stop, otherwise they fail
       with ESRCH.

       When the tracee is in ptrace-stop, the tracer can read and write data to
       the tracee using informational commands.  These commands leave the tracee
       in ptrace-stopped state:

           ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
           ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
           ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
           ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
           ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
           ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
           ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
           ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);

       Note that some errors are not reported.  For example, setting signal
       information (siginfo) may have no effect in some ptrace-stops, yet the call
       may succeed (return 0 and not set errno); querying PTRACE_GETEVENTMSG may
       succeed and return some random value if current ptrace-stop is not
       documented as returning a meaningful event message.

       The call

           ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);

       affects one tracee.  The tracee's current flags are replaced.  Flags are
       inherited by new tracees created and "auto-attached" via active
       PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK, or PTRACE_O_TRACECLONE options.

       Another group of commands makes the ptrace-stopped tracee run.  They have
       the form:

           ptrace(cmd, pid, 0, sig);

       where cmd is PTRACE_CONT, PTRACE_DETACH, PTRACE_SYSCALL, PTRACE_SINGLESTEP,
       PTRACE_SYSEMU, or PTRACE_SYSEMU_SINGLESTEP.  If the tracee is in signal-
       delivery-stop, sig is the signal to be injected (if it is nonzero).
       Otherwise, sig may be ignored.  (When restarting a tracee from a ptrace-
       stop other than signal-delivery-stop, recommended practice is to always
       pass 0 in sig.)

Attaching and detaching

       A thread can be attached to the tracer using the call

           ptrace(PTRACE_ATTACH, pid, 0, 0);

       This also sends SIGSTOP to this thread.  If the tracer wants this SIGSTOP
       to have no effect, it needs to suppress it.  Note that if other signals are
       concurrently sent to this thread during attach, the tracer may see the
       tracee enter signal-delivery-stop with other signal(s) first!  The usual
       practice is to reinject these signals until SIGSTOP is seen, then suppress
       SIGSTOP injection.  The design bug here is that a ptrace attach and a
       concurrently delivered SIGSTOP may race and the concurrent SIGSTOP may be
       lost.

       Since attaching sends SIGSTOP and the tracer usually suppresses it, this
       may cause a stray EINTR return from the currently executing system call in
       the tracee, as described in the "Signal injection and suppression" section.

       The request

           ptrace(PTRACE_TRACEME, 0, 0, 0);

       turns the calling thread into a tracee.  The thread continues to run
       (doesn't enter ptrace-stop).  A common practice is to follow the
       PTRACE_TRACEME with

           raise(SIGSTOP);

       and allow the parent (which is our tracer now) to observe our signal-
       delivery-stop.

       If the PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK, or PTRACE_O_TRACECLONE
       options are in effect, then children created by, respectively, vfork(2) or
       clone(2) with the CLONE_VFORK flag, fork(2) or clone(2) with the exit
       signal set to SIGCHLD, and other kinds of clone(2), are automatically
       attached to the same tracer which traced their parent.  SIGSTOP is
       delivered to the children, causing them to enter signal-delivery-stop after
       they exit the system call which created them.

       Detaching of the tracee is performed by:

           ptrace(PTRACE_DETACH, pid, 0, sig);

       PTRACE_DETACH is a restarting operation; therefore it requires the tracee
       to be in ptrace-stop.  If the tracee is in signal-delivery-stop, a signal
       can be injected.  Otherwise, the sig parameter may be silently ignored.

       If the tracee is running when the tracer wants to detach it, the usual
       solution is to send SIGSTOP (using tgkill(2), to make sure it goes to the
       correct thread), wait for the tracee to stop in signal-delivery-stop for
       SIGSTOP and then detach it (suppressing SIGSTOP injection).  A design bug
       is that this can race with concurrent SIGSTOPs.  Another complication is
       that the tracee may enter other ptrace-stops and needs to be restarted and
       waited for again, until SIGSTOP is seen.  Yet another complication is to be
       sure that the tracee is not already ptrace-stopped, because no signal
       delivery happens while it is--not even SIGSTOP.

       If the tracer dies, all tracees are automatically detached and restarted,
       unless they were in group-stop.  Handling of restart from group-stop is
       currently buggy, but the "as planned" behavior is to leave tracee stopped
       and waiting for SIGCONT.  If the tracee is restarted from signal-delivery-
       stop, the pending signal is injected.

execve(2) under ptrace

       When one thread in a multithreaded process calls execve(2), the kernel
       destroys all other threads in the process, and resets the thread ID of the
       execing thread to the thread group ID (process ID).  (Or, to put things
       another way, when a multithreaded process does an execve(2), at completion
       of the call, it appears as though the execve(2) occurred in the thread
       group leader, regardless of which thread did the execve(2).)  This
       resetting of the thread ID looks very confusing to tracers:

       *  All other threads stop in PTRACE_EVENT_EXIT stop, if the
          PTRACE_O_TRACEEXIT option was turned on.  Then all other threads except
          the thread group leader report death as if they exited via _exit(2) with
          exit code 0.

       *  The execing tracee changes its thread ID while it is in the execve(2).
          (Remember, under ptrace, the "pid" returned from waitpid(2), or fed into
          ptrace calls, is the tracee's thread ID.)  That is, the tracee's thread
          ID is reset to be the same as its process ID, which is the same as the
          thread group leader's thread ID.

       *  Then a PTRACE_EVENT_EXEC stop happens, if the PTRACE_O_TRACEEXEC option
          was turned on.

       *  If the thread group leader has reported its PTRACE_EVENT_EXIT stop by
          this time, it appears to the tracer that the dead thread leader
          "reappears from nowhere".  (Note: the thread group leader does not
          report death via WIFEXITED(status) until there is at least one other
          live thread.  This eliminates the possibility that the tracer will see
          it dying and then reappearing.)  If the thread group leader was still
          alive, for the tracer this may look as if thread group leader returns
          from a different system call than it entered, or even "returned from a
          system call even though it was not in any system call".  If the thread
          group leader was not traced (or was traced by a different tracer), then
          during execve(2) it will appear as if it has become a tracee of the
          tracer of the execing tracee.

       All of the above effects are the artifacts of the thread ID change in the
       tracee.

       The PTRACE_O_TRACEEXEC option is the recommended tool for dealing with this
       situation.  First, it enables PTRACE_EVENT_EXEC stop, which occurs before
       execve(2) returns.  In this stop, the tracer can use PTRACE_GETEVENTMSG to
       retrieve the tracee's former thread ID.  (This feature was introduced in
       Linux 3.0).  Second, the PTRACE_O_TRACEEXEC option disables legacy SIGTRAP
       generation on execve(2).

       When the tracer receives PTRACE_EVENT_EXEC stop notification, it is
       guaranteed that except this tracee and the thread group leader, no other
       threads from the process are alive.

       On receiving the PTRACE_EVENT_EXEC stop notification, the tracer should
       clean up all its internal data structures describing the threads of this
       process, and retain only one data structure--one which describes the single
       still running tracee, with

           thread ID == thread group ID == process ID.

       Example: two threads call execve(2) at the same time:

       *** we get syscall-enter-stop in thread 1: **
       PID1 execve("/bin/foo", "foo" <unfinished ...>
       *** we issue PTRACE_SYSCALL for thread 1 **
       *** we get syscall-enter-stop in thread 2: **
       PID2 execve("/bin/bar", "bar" <unfinished ...>
       *** we issue PTRACE_SYSCALL for thread 2 **
       *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
       *** we get syscall-exit-stop for PID0: **
       PID0 <... execve resumed> )             = 0

       If the PTRACE_O_TRACEEXEC option is not in effect for the execing tracee,
       the kernel delivers an extra SIGTRAP to the tracee after execve(2) returns.
       This is an ordinary signal (similar to one which can be generated by kill
       -TRAP), not a special kind of ptrace-stop.  Employing PTRACE_GETSIGINFO for
       this signal returns si_code set to 0 (SI_USER).  This signal may be blocked
       by signal mask, and thus may be delivered (much) later.

       Usually, the tracer (for example, strace(1)) would not want to show this
       extra post-execve SIGTRAP signal to the user, and would suppress its
       delivery to the tracee (if SIGTRAP is set to SIG_DFL, it is a killing
       signal).  However, determining which SIGTRAP to suppress is not easy.
       Setting the PTRACE_O_TRACEEXEC option and thus suppressing this extra
       SIGTRAP is the recommended approach.

Real parent

       The ptrace API (ab)uses the standard UNIX parent/child signaling over
       waitpid(2).  This used to cause the real parent of the process to stop
       receiving several kinds of waitpid(2) notifications when the child process
       is traced by some other process.

       Many of these bugs have been fixed, but as of Linux 2.6.38 several still
       exist; see BUGS below.

       As of Linux 2.6.38, the following is believed to work correctly:

       *  exit/death by signal is reported first to the tracer, then, when the
          tracer consumes the waitpid(2) result, to the real parent (to the real
          parent only when the whole multithreaded process exits).  If the tracer
          and the real parent are the same process, the report is sent only once.

RETURN VALUE top

       On success, PTRACE_PEEK* requests return the requested data, while other
       requests return zero.  On error, all requests return -1, and errno is set
       appropriately.  Since the value returned by a successful PTRACE_PEEK*
       request may be -1, the caller must clear errno before the call, and then
       check it afterward to determine whether or not an error occurred.

ERRORS top

       EBUSY  (i386 only) There was an error with allocating or freeing a debug
              register.

       EFAULT There was an attempt to read from or write to an invalid area in the
              tracer's or the tracee's memory, probably because the area wasn't
              mapped or accessible.  Unfortunately, under Linux, different
              variations of this fault will return EIO or EFAULT more or less
              arbitrarily.

       EINVAL An attempt was made to set an invalid option.

       EIO    request is invalid, or an attempt was made to read from or write to
              an invalid area in the tracer's or the tracee's memory, or there was
              a word-alignment violation, or an invalid signal was specified
              during a restart request.

       EPERM  The specified process cannot be traced.  This could be because the
              tracer has insufficient privileges (the required capability is
              CAP_SYS_PTRACE); unprivileged processes cannot trace processes that
              they cannot send signals to or those running set-user-ID/set-group-
              ID programs, for obvious reasons.  Alternatively, the process may
              already be being traced, or (on kernels before 2.6.26) be init(8)
              (PID 1).

       ESRCH  The specified process does not exist, or is not currently being
              traced by the caller, or is not stopped (for requests that require a
              stopped tracee).

CONFORMING TO top

       SVr4, 4.3BSD.

NOTES top

       Although arguments to ptrace() are interpreted according to the prototype
       given, glibc currently declares ptrace() as a variadic function with only
       the request argument fixed.  It is recommended to always supply four
       arguments, even if the requested operation does not use them, setting
       unused/ignored arguments to 0L or (void *) 0.

       In Linux kernels before 2.6.26, init(8), the process with PID 1, may not be
       traced.

       The layout of the contents of memory and the USER area are quite operating-
       system- and architecture-specific.  The offset supplied, and the data
       returned, might not entirely match with the definition of struct user.

       The size of a "word" is determined by the operating-system variant (e.g.,
       for 32-bit Linux it is 32 bits).

       This page documents the way the ptrace() call works currently in Linux.
       Its behavior differs noticeably on other flavors of UNIX.  In any case, use
       of ptrace() is highly specific to the operating system and architecture.

BUGS top

       On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a
       different value than the one for 2.4.  This leads to applications compiled
       with 2.6 kernel headers failing when run on 2.4 kernels.  This can be
       worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSETOPTIONS, if
       that is defined.

       Group-stop notifications are sent to the tracer, but not to real parent.
       Last confirmed on 2.6.38.6.

       If a thread group leader is traced and exits by calling _exit(2), a
       PTRACE_EVENT_EXIT stop will happen for it (if requested), but the
       subsequent WIFEXITED notification will not be delivered until all other
       threads exit.  As explained above, if one of other threads calls execve(2),
       the death of the thread group leader will never be reported.  If the execed
       thread is not traced by this tracer, the tracer will never know that
       execve(2) happened.  One possible workaround is to PTRACE_DETACH the thread
       group leader instead of restarting it in this case.  Last confirmed on
       2.6.38.6.

       A SIGKILL signal may still cause a PTRACE_EVENT_EXIT stop before actual
       signal death.  This may be changed in the future; SIGKILL is meant to
       always immediately kill tasks even under ptrace.  Last confirmed on
       2.6.38.6.

       Some system calls return with EINTR if a signal was sent to a tracee, but
       delivery was suppressed by the tracer.  (This is very typical operation: it
       is usually done by debuggers on every attach, in order to not introduce a
       bogus SIGSTOP).  As of Linux 3.2.9, the following system calls are affected
       (this list is likely incomplete): epoll_wait(2), and read(2) from an
       inotify(7) file descriptor.  The usual symptom of this bug is that when you
       attach to a quiescent process with the command

           strace -p <process-ID>

       then, instead of the usual and expected one-line output such as

           restart_syscall(<... resuming interrupted call ...>_

       or

           select(6, [5], NULL, [5], NULL_

       ('_' denotes the cursor position), you observe more than one line.  For
       example:

           clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
           epoll_wait(4,_

       What is not visible here is that the process was blocked in epoll_wait(2)
       before strace(1) has attached to it.  Attaching caused epoll_wait(2) to
       return to user space with the error EINTR.  In this particular case, the
       program reacted to EINTR by checking the current time, and then executing
       epoll_wait(2) again.  (Programs which do not expect such "stray" EINTR
       errors may behave in an unintended way upon an strace(1) attach.)

SEE ALSO top

       gdb(1), strace(1), clone(2), execve(2), fork(2), gettid(2), sigaction(2),
       tgkill(2), vfork(2), waitpid(2), exec(3), capabilities(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-25                           PTRACE(2)


ptsname(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PTSNAME(3)                   Linux Programmer's Manual                  PTSNAME(3)

NAME top

       ptsname, ptsname_r - get the name of the slave pseudoterminal

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <stdlib.h>

       char *ptsname(int fd);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <stdlib.h>

       int ptsname_r(int fd, char *buf, size_t buflen);

DESCRIPTION top

       The ptsname() function returns the name of the slave pseudoterminal device
       corresponding to the master referred to by fd.

       The ptsname_r() function is the reentrant equivalent of ptsname().  It
       returns the name of the slave pseudoterminal device as a null-terminated
       string in the buffer pointed to by buf.  The buflen argument specifies the
       number of bytes available in buf.

RETURN VALUE top

       On success, ptsname() returns a pointer to a string in static storage which
       will be overwritten by subsequent calls.  This pointer must not be freed.
       On failure, a NULL pointer is returned.

       On success, ptsname_r() returns 0.  On failure, a nonzero value is returned
       and errno is set to indicate the error.

ERRORS top

       EINVAL (ptsname_r() only) buf is NULL.

       ENOTTY fd does not refer to a pseudoterminal master device.

       ERANGE (ptsname_r() only) buf is too small.

VERSIONS top

       ptsname() is provided in glibc since version 2.1.

CONFORMING TO top

       ptsname() is part of the UNIX 98 pseudoterminal support (see pts(4)).  This
       function is specified in POSIX.1-2001.

       ptsname_r() is a Linux extension.  A version of this function is documented
       on Tru64 and HP-UX, but on those implementations, -1 is returned on error,
       with errno set to indicate the error.  Avoid using this function in
       portable programs.

SEE ALSO top

       grantpt(3), posix_openpt(3), ttyname(3), unlockpt(3), pts(4), pty(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-09-03                          PTSNAME(3)


pty(7) - Linux manual page

NAME | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PTY(7)                       Linux Programmer's Manual                      PTY(7)

NAME top

       pty - pseudoterminal interfaces

DESCRIPTION top

       A pseudoterminal (sometimes abbreviated "pty") is a pair of virtual
       character devices that provide a bidirectional communication channel.  One
       end of the channel is called the master; the other end is called the slave.
       The slave end of the pseudoterminal provides an interface that behaves
       exactly like a classical terminal.  A process that expects to be connected
       to a terminal, can open the slave end of a pseudoterminal and then be
       driven by a program that has opened the master end.  Anything that is
       written on the master end is provided to the process on the slave end as
       though it was input typed on a terminal.  For example, writing the
       interrupt character (usually control-C) to the master device would cause an
       interrupt signal (SIGINT) to be generated for the foreground process group
       that is connected to the slave.  Conversely, anything that is written to
       the slave end of the pseudoterminal can be read by the process that is
       connected to the master end.  Pseudoterminals are used by applications such
       as network login services (ssh(1), rlogin(1), telnet(1)), terminal
       emulators, script(1), screen(1), and expect(1).

       Historically, two pseudoterminal APIs have evolved: BSD and System V.
       SUSv1 standardized a pseudoterminal API based on the System V API, and this
       API should be employed in all new programs that use pseudoterminals.

       Linux provides both BSD-style and (standardized) System V-style
       pseudoterminals.  System V-style terminals are commonly called UNIX 98
       pseudoterminals on Linux systems.  Since kernel 2.6.4, BSD-style
       pseudoterminals are considered deprecated (they can be disabled when
       configuring the kernel); UNIX 98 pseudoterminals should be used in new
       applications.

UNIX 98 pseudoterminals

       An unused UNIX 98 pseudoterminal master is opened by calling
       posix_openpt(3).  (This function opens the master clone device, /dev/ptmx;
       see pts(4).)  After performing any program-specific initializations,
       changing the ownership and permissions of the slave device using
       grantpt(3), and unlocking the slave using unlockpt(3)), the corresponding
       slave device can be opened by passing the name returned by ptsname(3) in a
       call to open(2).

       The Linux kernel imposes a limit on the number of available UNIX 98
       pseudoterminals.  In kernels up to and including 2.6.3, this limit is
       configured at kernel compilation time (CONFIG_UNIX98_PTYS), and the
       permitted number of pseudoterminals can be up to 2048, with a default
       setting of 256.  Since kernel 2.6.4, the limit is dynamically adjustable
       via /proc/sys/kernel/pty/max, and a corresponding file,
       /proc/sys/kernel/pty/nr, indicates how many pseudoterminals are currently
       in use.  For further details on these two files, see proc(5).

BSD pseudoterminals

       BSD-style pseudoterminals are provided as precreated pairs, with names of
       the form /dev/ptyXY (master) and /dev/ttyXY (slave), where X is a letter
       from the 16-character set [p-za-e], and Y is a letter from the 16-character
       set [0-9a-f].  (The precise range of letters in these two sets varies
       across UNIX implementations.)  For example, /dev/ptyp1 and /dev/ttyp1
       constitute a BSD pseudoterminal pair.  A process finds an unused
       pseudoterminal pair by trying to open(2) each pseudoterminal master until
       an open succeeds.  The corresponding pseudoterminal slave (substitute "tty"
       for "pty" in the name of the master) can then be opened.

FILES top

       /dev/ptmx (UNIX 98 master clone device)
       /dev/pts/* (UNIX 98 slave devices)
       /dev/pty[p-za-e][0-9a-f] (BSD master devices)
       /dev/tty[p-za-e][0-9a-f] (BSD slave devices)

NOTES top

       A description of the TIOCPKT ioctl(2), which controls packet mode
       operation, can be found in tty_ioctl(4).

       The BSD ioctl(2) operations TIOCSTOP, TIOCSTART, TIOCUCNTL, and TIOCREMOTE
       have not been implemented under Linux.

SEE ALSO top

       select(2), setsid(2), forkpty(3), openpty(3), termios(3), pts(4), tty(4),
       tty_ioctl(4)

COLOPHON top

       This page is part of release 3.45 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                               2005-10-10                              PTY(7)


putenv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PUTENV(3)                    Linux Programmer's Manual                   PUTENV(3)

NAME top

       putenv - change or add an environment variable

SYNOPSIS top

       #include <stdlib.h>

       int putenv(char *string);

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

       putenv(): _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       The putenv() function adds or changes the value of environment variables.
       The argument string is of the form name=value.  If name does not already
       exist in the environment, then string is added to the environment.  If name
       does exist, then the value of name in the environment is changed to value.
       The string pointed to by string becomes part of the environment, so
       altering the string changes the environment.

RETURN VALUE top

       The putenv() function returns zero on success, or nonzero if an error
       occurs.

ERRORS top

       ENOMEM Insufficient space to allocate new environment.

CONFORMING TO top

       SVr4, POSIX.1-2001, 4.3BSD.

NOTES top

       The putenv() function is not required to be reentrant, and the one in
       libc4, libc5 and glibc 2.0 is not, but the glibc 2.1 version is.

       Description for libc4, libc5, glibc: If the argument string is of the form
       name, and does not contain an '=' character, then the variable name is
       removed from the environment.  If putenv() has to allocate a new array
       environ, and the previous array was also allocated by putenv(), then it
       will be freed.  In no case will the old storage associated to the
       environment variable itself be freed.

       The libc4 and libc5 and glibc 2.1.2 versions conform to SUSv2: the pointer
       string given to putenv() is used.  In particular, this string becomes part
       of the environment; changing it later will change the environment.  (Thus,
       it is an error is to call putenv() with an automatic variable as the
       argument, then return from the calling function while string is still part
       of the environment.)  However, glibc 2.0-2.1.1 differs: a copy of the
       string is used.  On the one hand this causes a memory leak, and on the
       other hand it violates SUSv2.  This has been fixed in glibc 2.1.2.

       The 4.4BSD version, like glibc 2.0, uses a copy.

       SUSv2 removes the const from the prototype, and so does glibc 2.1.3.

SEE ALSO top

       clearenv(3), getenv(3), setenv(3), unsetenv(3), environ(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                           PUTENV(3)


putgrent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PUTGRENT(3)                  Linux Programmer's Manual                 PUTGRENT(3)

NAME top

       putgrent - write a group database entry to a file

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <grp.h>

       int putgrent(const struct group *grp, FILE *fp);

DESCRIPTION top

       The putgrent() function is the counterpart for fgetgrent(3).  The function
       writes the content of the provided struct group into the file pointed to by
       fp.  The list of group members must be NULL-terminated or NULL-initialized.

       The struct group is defined as follows:

           struct group {
               char   *gr_name;      /* group name */
               char   *gr_passwd;    /* group password */
               gid_t   gr_gid;       /* group ID */
               char  **gr_mem;       /* group members */
           };

RETURN VALUE top

       The function returns zero on success, and a nonzero value on error.

CONFORMING TO top

       This function is a GNU extension.

SEE ALSO top

       fgetgrent(3), getgrent(3), group(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2003-09-09                         PUTGRENT(3)


putpwent(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

PUTPWENT(3)                  Linux Programmer's Manual                 PUTPWENT(3)

NAME top

       putpwent - write a password file entry

SYNOPSIS top

       #include <stdio.h>
       #include <sys/types.h>
       #include <pwd.h>

       int putpwent(const struct passwd *p, FILE *stream);

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

       putpwent(): _SVID_SOURCE

DESCRIPTION top

       The putpwent() function writes a password entry from the structure p in the
       file associated with stream.

       The passwd structure is defined in <pwd.h> as follows:

           struct passwd {
               char    *pw_name;        /* username */
               char    *pw_passwd;      /* user password */
               uid_t    pw_uid;         /* user ID */
               gid_t    pw_gid;         /* group ID */
               char    *pw_gecos;       /* real name */
               char    *pw_dir;         /* home directory */
               char    *pw_shell;       /* shell program */
           };

RETURN VALUE top

       The putpwent() function returns 0 on success, or -1 if an error occurs.

ERRORS top

       EINVAL Invalid (NULL) argument given.

CONFORMING TO top

       SVr4.

SEE ALSO top

       endpwent(3), fgetpwent(3), getpw(3), getpwent(3), getpwnam(3), getpwuid(3),
       setpwent(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                         PUTPWENT(3)


putwchar(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

PUTWCHAR(3)                  Linux Programmer's Manual                 PUTWCHAR(3)

NAME top

       putwchar - write a wide character to standard output

SYNOPSIS top

       #include <wchar.h>

       wint_t putwchar(wchar_t wc);

DESCRIPTION top

       The putwchar() function is the wide-character equivalent of the putchar(3)
       function.  It writes the wide character wc to stdout.  If ferror(stdout)
       becomes true, it returns WEOF.  If a wide character conversion error
       occurs, it sets errno to EILSEQ and returns WEOF.  Otherwise it returns wc.

       For a nonlocking counterpart, see unlocked_stdio(3).

RETURN VALUE top

       The putwchar() function returns wc if no error occurred, or WEOF to
       indicate an error.

CONFORMING TO top

       C99.

NOTES top

       The behavior of putwchar() depends on the LC_CTYPE category of the current
       locale.

       It is reasonable to expect that putwchar() will actually write the
       multibyte sequence corresponding to the wide character wc.

SEE ALSO top

       fputwc(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         PUTWCHAR(3)


qecvt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

QECVT(3)                     Linux Programmer's Manual                    QECVT(3)

NAME top

       qecvt, qfcvt, qgcvt - convert a floating-point number to a string

SYNOPSIS top

       #include <stdlib.h>

       char *qecvt(long double number, int ndigits, int *decpt, int *sign);

       char *qfcvt(long double number, int ndigits, int *decpt, int *sign);

       char *qgcvt(long double number, int ndigit, char *buf);

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

       qecvt(), qfcvt(), qgcvt(): _SVID_SOURCE

DESCRIPTION top

       The functions qecvt(), qfcvt() and qgcvt() are identical to ecvt(3),
       fcvt(3) and gcvt(3) respectively, except that they use a long double
       argument number.  See ecvt(3) and gcvt(3).

CONFORMING TO top

       SVr4.  Not seen in most common UNIX implementations, but occurs in SunOS.
       Not supported by libc4 and libc5.  Supported by glibc.

NOTES top

       These functions are obsolete.  Instead, sprintf(3) is recommended.

SEE ALSO top

       ecvt(3), ecvt_r(3), gcvt(3), sprintf(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                            QECVT(3)


qsort(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

QSORT(3)                     Linux Programmer's Manual                    QSORT(3)

NAME top

       qsort, qsort_r - sort an array

SYNOPSIS top

       #include <stdlib.h>

       void qsort(void *base, size_t nmemb, size_t size,
                  int (*compar)(const void *, const void *));

       void qsort_r(void *base, size_t nmemb, size_t size,
                  int (*compar)(const void *, const void *, void *),
                  void *arg);

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

       qsort_r(): _GNU_SOURCE

DESCRIPTION top

       The qsort() function sorts an array with nmemb elements of size size.  The
       base argument points to the start of the array.

       The contents of the array are sorted in ascending order according to a
       comparison function pointed to by compar, which is called with two
       arguments that point to the objects being compared.

       The comparison function must return an integer less than, equal to, or
       greater than zero if the first argument is considered to be respectively
       less than, equal to, or greater than the second.  If two members compare as
       equal, their order in the sorted array is undefined.

       The qsort_r() function is identical to qsort() except that the comparison
       function compar takes a third argument.  A pointer is passed to the
       comparison function via arg.  In this way, the comparison function does not
       need to use global variables to pass through arbitrary arguments, and is
       therefore reentrant and safe to use in threads.

RETURN VALUE top

       The qsort() and qsort_r() functions return no value.

VERSIONS top

       qsort_r() was added to glibc in version 2.8.

CONFORMING TO top

       The qsort() function conforms to SVr4, 4.3BSD, C89, C99.

NOTES top

       Library routines suitable for use as the compar argument to qsort() include
       alphasort(3) and versionsort(3).  To compare C strings, the comparison
       function can call strcmp(3), as shown in the example below.

EXAMPLE top

       For one example of use, see the example under bsearch(3).

       Another example is the following program, which sorts the strings given in
       its command-line arguments:

       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       static int
       cmpstringp(const void *p1, const void *p2)
       {
           /* The actual arguments to this function are "pointers to
              pointers to char", but strcmp(3) arguments are "pointers
              to char", hence the following cast plus dereference */

           return strcmp(* (char * const *) p1, * (char * const *) p2);
       }

       int
       main(int argc, char *argv[])
       {
           int j;

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

           qsort(&argv[1], argc - 1, sizeof(char *), cmpstringp);

           for (j = 1; j < argc; j++)
               puts(argv[j]);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       sort(1), alphasort(3), strcmp(3), versionsort(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-03-08                            QSORT(3)


query_module(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

QUERY_MODULE(2)              Linux Programmer's Manual             QUERY_MODULE(2)

NAME top

       query_module - query the kernel for various bits pertaining to modules

SYNOPSIS top

       #include <linux/module.h>

       int query_module(const char *name, int which, void *buf,
                        size_t bufsize, size_t *ret);

DESCRIPTION top

       Note: This system call is present only in kernels before Linux 2.6.

       query_module() requests information from the kernel about loadable modules.
       The returned information is placed in the buffer pointed to by buf.  The
       caller must specify the size of buf in bufsize.  The precise nature and
       format of the returned information depend on the operation specified by
       which.  Some operations require name to identify a currently loaded module,
       some allow name to be NULL, indicating the kernel proper.

       The following values can be specified for which:

       0      Returns success, if the kernel supports query_module().  Used to
              probe for availability of the system call.

       QM_MODULES
              Returns the names of all loaded modules.  The returned buffer
              consists of a sequence of null-terminated strings; ret is set to the
              number of modules.

       QM_DEPS
              Returns the names of all modules used by the indicated module.  The
              returned buffer consists of a sequence of null-terminated strings;
              ret is set to the number of modules.

       QM_REFS
              Returns the names of all modules using the indicated module.  This
              is the inverse of QM_DEPS.  The returned buffer consists of a
              sequence of null-terminated strings; ret is set to the number of
              modules.

       QM_SYMBOLS
              Returns the symbols and values exported by the kernel or the
              indicated module.  The returned buffer is an array of structures of
              the following form

                  struct module_symbol {
                      unsigned long value;
                      unsigned long name;
                  };

              followed by null-terminated strings.  The value of name is the
              character offset of the string relative to the start of buf; ret is
              set to the number of symbols.

       QM_INFO
              Returns miscellaneous information about the indicated module.  The
              output buffer format is:

                  struct module_info {
                      unsigned long address;
                      unsigned long size;
                      unsigned long flags;
                  };

              where address is the kernel address at which the module resides,
              size is the size of the module in bytes, and flags is a mask of
              MOD_RUNNING, MOD_AUTOCLEAN, etc., that indicates the current status
              of the module (see the Linux kernel source file
              include/linux/module.h).  ret is set to the size of the module_info
              structure.

RETURN VALUE top

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

ERRORS top

       EFAULT At least one of name, buf, or ret was outside the program's
              accessible address space.

       EINVAL Invalid which; or name is NULL (indicating "the kernel"), but this
              is not permitted with the specified value of which.

       ENOENT No module by that name exists.

       ENOSPC The buffer size provided was too small.  ret is set to the minimum
              size needed.

       ENOSYS query_module() is not supported in this version of the kernel (e.g.,
              the kernel is version 2.6 or later).

VERSIONS top

       This system call is only present on Linux up until kernel 2.4; it was
       removed in Linux 2.6.

CONFORMING TO top

       query_module() is Linux-specific.

NOTES top

       Some of the information that was formerly available via query_module() can
       be obtained from /proc/modules, /proc/kallsyms, and the files under the
       directory /sys/module.

SEE ALSO top

       create_module(2), delete_module(2), get_kernel_syms(2), init_module(2),
       lsmod(8), modinfo(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-18                     QUERY_MODULE(2)


quotactl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | COLOPHON The Linux Programming Interface

QUOTACTL(2)                  Linux Programmer's Manual                 QUOTACTL(2)

NAME top

       quotactl - manipulate disk quotas

SYNOPSIS top

       #include <sys/quota.h>
       #include <xfs/xqm.h>

       int quotactl(int cmd, const char *special, int id, caddr_t addr);

DESCRIPTION top

       The quota system can be used to set per-user and per-group limits on the
       amount of disk space used on a file system.  For each user and/or group, a
       soft limit and a hard limit can be set for each file system.  The hard
       limit can't be exceeded.  The soft limit can be exceeded, but warnings will
       ensue.  Moreover, the user can't exceed the soft limit for more than one
       week (by default) at a time; after this time, the soft limit counts as a
       hard limit.

       The quotactl() call manipulates disk quotas.  The cmd argument indicates a
       command to be applied to the user or group ID specified in id.  To
       initialize the cmd argument, use the QCMD(subcmd, type) macro.  The type
       value is either USRQUOTA, for user quotas, or GRPQUOTA, for group quotas.
       The subcmd value is described below.

       The special argument is a pointer to a null-terminated string containing
       the pathname of the (mounted) block special device for the file system
       being manipulated.

       The addr argument is the address of an optional, command-specific, data
       structure that is copied in or out of the system.  The interpretation of
       addr is given with each command below.

       The subcmd value is one of the following:

       Q_QUOTAON
               Turn on quotas for a file system.  The id argument is the
               identification number of the quota format to be used.  Currently,
               there are three supported quota formats:

               QFMT_VFS_OLD The original quota format.

               QFMT_VFS_V0  The standard VFS v0 quota format, which can handle
                            32-bit UIDs and GIDs and quota limits up to 2^42 bytes
                            and 2^32 inodes.

               QFMT_VFS_V1  A quota format that can handle 32-bit UIDs and GIDs
                            and quota limits of 2^64 bytes and 2^64 inodes.

               The addr argument points to the pathname of a file containing the
               quotas for the file system.  The quota file must exist; it is
               normally created with the quotacheck(8) program.  This operation
               requires privilege (CAP_SYS_ADMIN).

       Q_QUOTAOFF
               Turn off quotas for a file system.  The addr and id arguments are
               ignored.  This operation requires privilege (CAP_SYS_ADMIN).

       Q_GETQUOTA
               Get disk quota limits and current usage for user or group id.  The
               addr argument is a pointer to a dqblk structure defined in
               <sys/quota.h> as follows:

                   /* uint64_t is an unsigned 64-bit integer;
                      uint32_t is an unsigned 32-bit integer */

                   struct dqblk {          /* Definition since Linux 2.4.22 */
                       uint64_t dqb_bhardlimit;   /* absolute limit on disk
                                                     quota blocks alloc */
                       uint64_t dqb_bsoftlimit;   /* preferred limit on
                                                     disk quota blocks */
                       uint64_t dqb_curspace;     /* current quota block
                                                     count */
                       uint64_t dqb_ihardlimit;   /* maximum number of
                                                     allocated inodes */
                       uint64_t dqb_isoftlimit;   /* preferred inode limit */
                       uint64_t dqb_curinodes;    /* current number of
                                                     allocated inodes */
                       uint64_t dqb_btime;        /* time limit for excessive
                                                     disk use */
                       uint64_t dqb_itime;        /* time limit for excessive
                                                     files */
                       uint32_t dqb_valid;        /* bit mask of QIF_*
                                                     constants */
                   };

                   /* Flags in dqb_valid that indicate which fields in
                      dqblk structure are valid. */

                   #define QIF_BLIMITS   1
                   #define QIF_SPACE     2
                   #define QIF_ILIMITS   4
                   #define QIF_INODES    8
                   #define QIF_BTIME     16
                   #define QIF_ITIME     32
                   #define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)
                   #define QIF_USAGE     (QIF_SPACE | QIF_INODES)
                   #define QIF_TIMES     (QIF_BTIME | QIF_ITIME)
                   #define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)

               The dqb_valid field is a bit mask that is set to indicate the
               entries in the dqblk structure that are valid.  Currently, the
               kernel fills in all entries of the dqblk structure and marks them
               as valid in the dqb_valid field.  Unprivileged users may retrieve
               only their own quotas; a privileged user (CAP_SYS_ADMIN) can
               retrieve the quotas of any user.

       Q_SETQUOTA
               Set quota information for user or group id, using the information
               supplied in the dqblk structure pointed to by addr.  The dqb_valid
               field of the dqblk structure indicates which entries in the
               structure have been set by the caller.  This operation supersedes
               the Q_SETQLIM and Q_SETUSE operations in the previous quota
               interfaces.  This operation requires privilege (CAP_SYS_ADMIN).

       Q_GETINFO
               Get information (like grace times) about quotafile.  The addr
               argument should be a pointer to a dqinfo structure.  This structure
               is defined in <sys/quota.h> as follows:

                   /* uint64_t is an unsigned 64-bit integer;
                      uint32_t is an unsigned 32-bit integer */

                   struct dqinfo {         /* Defined since kernel 2.4.22 */
                       uint64_t dqi_bgrace;    /* Time before block soft limit
                                                  becomes hard limit */

                       uint64_t dqi_igrace;    /* Time before inode soft limit
                                                  becomes hard limit */
                       uint32_t dqi_flags;     /* Flags for quotafile
                                                  (DQF_*) */
                       uint32_t dqi_valid;
                   };

                   /* Bits for dqi_flags */

                   /* Quota format QFMT_VFS_OLD */

                   #define V1_DQF_RSQUASH   1   /* Root squash enabled */

                   /* Other quota formats have no dqi_flags bits defined */

                   /* Flags in dqi_valid that indicate which fields in
                      dqinfo structure are valid. */

                   # define IIF_BGRACE 1
                   # define IIF_IGRACE 2
                   # define IIF_FLAGS  4
                   # define IIF_ALL    (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)

               The dqi_valid field in the dqinfo structure indicates the entries
               in the structure that are valid.  Currently, the kernel fills in
               all entries of the dqinfo structure and marks them all as valid in
               the dqi_valid field.  The id argument is ignored.

       Q_SETINFO
               Set information about quotafile.  The addr argument should be a
               pointer to a dqinfo structure.  The dqi_valid field of the dqinfo
               structure indicates the entries in the structure that have been set
               by the caller.  This operation supersedes the Q_SETGRACE and
               Q_SETFLAGS operations in the previous quota interfaces.  The id
               argument is ignored.  This operation requires privilege
               (CAP_SYS_ADMIN).

       Q_GETFMT
               Get quota format used on the specified file system.  The addr
               argument should be a pointer to a 4-byte buffer where the format
               number will be stored.

       Q_SYNC  Update the on-disk copy of quota usages for a file system.  If
               special is NULL, then all file systems with active quotas are
               sync'ed.  The addr and id arguments are ignored.

       Q_GETSTATS
               Get statistics and other generic information about the quota
               subsystem.  The addr argument should be a pointer to a dqstats
               structure in which data should be stored.  This structure is
               defined in <sys/quota.h>.  The special and id arguments are
               ignored.  This operation is obsolete and not supported by recent
               kernels.  Files in /proc/sys/fs/quota/ carry the information
               instead.

       For XFS file systems making use of the XFS Quota Manager (XQM), the above
       commands are bypassed and the following commands are used:

       Q_XQUOTAON
               Turn on quotas for an XFS file system.  XFS provides the ability to
               turn on/off quota limit enforcement with quota accounting.
               Therefore, XFS expects addr to be a pointer to an unsigned int that
               contains either the flags XFS_QUOTA_UDQ_ACCT and/or
               XFS_QUOTA_UDQ_ENFD (for user quota), or XFS_QUOTA_GDQ_ACCT and/or
               XFS_QUOTA_GDQ_ENFD (for group quota), as defined in <xfs/xqm.h>.
               This operation requires privilege (CAP_SYS_ADMIN).

       Q_XQUOTAOFF
               Turn off quotas for an XFS file system.  As with Q_QUOTAON, XFS
               file systems expect a pointer to an unsigned int that specifies
               whether quota accounting and/or limit enforcement need to be turned
               off.  This operation requires privilege (CAP_SYS_ADMIN).

       Q_XGETQUOTA
               Get disk quota limits and current usage for user id.  The addr
               argument is a pointer to an fs_disk_quota structure (defined in
               <xfs/xqm.h>).  Unprivileged users may retrieve only their own
               quotas; a privileged user (CAP_SYS_ADMIN) may retrieve the quotas
               of any user.

       Q_XSETQLIM
               Set disk quota limits for user id.  The addr argument is a pointer
               to an fs_disk_quota structure (defined in <xfs/xqm.h>).  This
               operation requires privilege (CAP_SYS_ADMIN).

       Q_XGETQSTAT
               Returns an fs_quota_stat structure containing XFS file system
               specific quota information.  This is useful for finding out how
               much space is used to store quota information, and also to get
               quotaon/off status of a given local XFS file system.

       Q_XQUOTARM
               Free the disk space taken by disk quotas.  Quotas must have already
               been turned off.

       There is no command equivalent to Q_SYNC for XFS since sync(1) writes quota
       information to disk (in addition to the other file system metadata that it
       writes out).

RETURN VALUES top

       On success, quotactl() returns 0; on error -1 is returned, and errno is set
       to indicate the error.

ERRORS top

       EFAULT addr or special is invalid.

       EINVAL cmd or type is invalid.

       ENOENT The file specified by special or addr does not exist.

       ENOSYS The kernel has not been compiled with the CONFIG_QUOTA option.

       ENOTBLK
              special is not a block device.

       EPERM  The caller lacked the required privilege (CAP_SYS_ADMIN) for the
              specified operation.

       ESRCH  No disk quota is found for the indicated user.  Quotas have not been
              turned on for this file system.

       If cmd is Q_SETQUOTA, quotactl() may also set errno to:

       ERANGE Specified limits are out of range allowed by quota format.

       If cmd is Q_QUOTAON, quotactl() may also set errno to:

       EACCES The quota file pointed to by addr exists, but is not a regular file;
              or, the quota file pointed to by addr exists, but is not on the file
              system pointed to by special.

       EBUSY  Q_QUOTAON attempted, but another Q_QUOTAON had already been
              performed.

       EINVAL The quota file is corrupted.

       ESRCH  Specified quota format was not found.

SEE ALSO top

       quota(1), getrlimit(2), quotacheck(8), quotaon(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-06-16                         QUOTACTL(2)


raise(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RAISE(3)                     Linux Programmer's Manual                    RAISE(3)

NAME top

       raise - send a signal to the caller

SYNOPSIS top

       #include <signal.h>

       int raise(int sig);

DESCRIPTION top

       The raise() function sends a signal to the calling process or thread.  In a
       single-threaded program it is equivalent to

           kill(getpid(), sig);

       In a multithreaded program it is equivalent to

           pthread_kill(pthread_self(), sig);

       If the signal causes a handler to be called, raise() will only return after
       the signal handler has returned.

RETURN VALUE top

       raise() returns 0 on success, and nonzero for failure.

CONFORMING TO top

       C89, C99, POSIX.1-2001.

NOTES top

       Since version 2.3.3, glibc implements raise() by calling tgkill(2), if the
       kernel supports that system call.  Older glibc versions implemented raise()
       using kill(2).

SEE ALSO top

       getpid(2), kill(2), sigaction(2), signal(2), pthread_kill(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-20                            RAISE(3)


ram(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

RAM(4)                       Linux Programmer's Manual                      RAM(4)

NAME top

       ram - ram disk device

DESCRIPTION top

       The ram device is a block device to access the ram disk in raw mode.

       It is typically created by:

              mknod -m 660 /dev/ram b 1 1
              chown root:disk /dev/ram

FILES top

       /dev/ram

SEE ALSO top

       chown(1), mknod(1), mount(8)

COLOPHON top

       This page is part of release 3.45 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                               1992-11-21                              RAM(4)


rand(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

RAND(3)                      Linux Programmer's Manual                     RAND(3)

NAME top

       rand, rand_r, srand - pseudo-random number generator

SYNOPSIS top

       #include <stdlib.h>

       int rand(void);

       int rand_r(unsigned int *seedp);

       void srand(unsigned int seed);

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

       rand_r(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The rand() function returns a pseudo-random integer in the range 0 to
       RAND_MAX inclusive (i.e., the mathematical range [0, RAND_MAX]).

       The srand() function sets its argument as the seed for a new sequence of
       pseudo-random integers to be returned by rand().  These sequences are
       repeatable by calling srand() with the same seed value.

       If no seed value is provided, the rand() function is automatically seeded
       with a value of 1.

       The function rand() is not reentrant or thread-safe, since it uses hidden
       state that is modified on each call.  This might just be the seed value to
       be used by the next call, or it might be something more elaborate.  In
       order to get reproducible behavior in a threaded application, this state
       must be made explicit; this can be done using the reentrant function
       rand_r().

       Like rand(), rand_r() returns a pseudo-random integer in the range
       [0, RAND_MAX].  The seedp argument is a pointer to an unsigned int that is
       used to store state between calls.  If rand_r() is called with the same
       initial value for the integer pointed to by seedp, and that value is not
       modified between calls, then the same pseudo-random sequence will result.

       The value pointed to by the seedp argument of rand_r() provides only a very
       small amount of state, so this function will be a weak pseudo-random
       generator.  Try drand48_r(3) instead.

RETURN VALUE top

       The rand() and rand_r() functions return a value between 0 and RAND_MAX
       (inclusive).  The srand() function returns no value.

CONFORMING TO top

       The functions rand() and srand() conform to SVr4, 4.3BSD, C89, C99,
       POSIX.1-2001.  The function rand_r() is from POSIX.1-2001.  POSIX.1-2008
       marks rand_r() as obsolete.

NOTES top

       The versions of rand() and srand() in the Linux C Library use the same
       random number generator as random(3) and srandom(3), so the lower-order
       bits should be as random as the higher-order bits.  However, on older
       rand() implementations, and on current implementations on different
       systems, the lower-order bits are much less random than the higher-order
       bits.  Do not use this function in applications intended to be portable
       when good randomness is needed.  (Use random(3) instead.)

EXAMPLE top

       POSIX.1-2001 gives the following example of an implementation of rand() and
       srand(), possibly useful when one needs the same sequence on two different
       machines.

           static unsigned long next = 1;

           /* RAND_MAX assumed to be 32767 */
           int myrand(void) {
               next = next * 1103515245 + 12345;
               return((unsigned)(next/65536) % 32768);
           }

           void mysrand(unsigned seed) {
               next = seed;
           }

       The following program can be used to display the pseudo-random sequence
       produced by rand() when given a particular seed.

           #include <stdlib.h>
           #include <stdio.h>

           int
           main(int argc, char *argv[])
           {
               int j, r, nloops;
               unsigned int seed;

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

               seed = atoi(argv[1]);
               nloops = atoi(argv[2]);

               srand(seed);
               for (j = 0; j < nloops; j++) {
                   r =  rand();
                   printf("%d\n", r);
               }

               exit(EXIT_SUCCESS);
           }

SEE ALSO top

       drand48(3), random(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-10-01                             RAND(3)


random(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

RANDOM(4)                    Linux Programmer's Manual                   RANDOM(4)

NAME top

       random, urandom - kernel random number source devices

DESCRIPTION top

       The character special files /dev/random and /dev/urandom (present since
       Linux 1.3.30) provide an interface to the kernel's random number generator.
       File /dev/random has major device number 1 and minor device number 8.  File
       /dev/urandom has major device number 1 and minor device number 9.

       The random number generator gathers environmental noise from device drivers
       and other sources into an entropy pool.  The generator also keeps an
       estimate of the number of bits of noise in the entropy pool.  From this
       entropy pool random numbers are created.

       When read, the /dev/random device will only return random bytes within the
       estimated number of bits of noise in the entropy pool.  /dev/random should
       be suitable for uses that need very high quality randomness such as one-
       time pad or key generation.  When the entropy pool is empty, reads from
       /dev/random will block until additional environmental noise is gathered.

       A read from the /dev/urandom device will not block waiting for more
       entropy.  As a result, if there is not sufficient entropy in the entropy
       pool, the returned values are theoretically vulnerable to a cryptographic
       attack on the algorithms used by the driver.  Knowledge of how to do this
       is not available in the current unclassified literature, but it is
       theoretically possible that such an attack may exist.  If this is a concern
       in your application, use /dev/random instead.

Usage

       If you are unsure about whether you should use /dev/random or /dev/urandom,
       then probably you want to use the latter.  As a general rule, /dev/urandom
       should be used for everything except long-lived GPG/SSL/SSH keys.

       If a seed file is saved across reboots as recommended below (all major
       Linux distributions have done this since 2000 at least), the output is
       cryptographically secure against attackers without local root access as
       soon as it is reloaded in the boot sequence, and perfectly adequate for
       network encryption session keys.  Since reads from /dev/random may block,
       users will usually want to open it in nonblocking mode (or perform a read
       with timeout), and provide some sort of user notification if the desired
       entropy is not immediately available.

       The kernel random-number generator is designed to produce a small amount of
       high-quality seed material to seed a cryptographic pseudo-random number
       generator (CPRNG).  It is designed for security, not speed, and is poorly
       suited to generating large amounts of random data.  Users should be very
       economical in the amount of seed material that they read from /dev/urandom
       (and /dev/random); unnecessarily reading large quantities of data from this
       device will have a negative impact on other users of the device.

       The amount of seed material required to generate a cryptographic key equals
       the effective key size of the key.  For example, a 3072-bit RSA or Diffie-
       Hellman private key has an effective key size of 128 bits (it requires
       about 2^128 operations to break) so a key generator only needs 128 bits (16
       bytes) of seed material from /dev/random.

       While some safety margin above that minimum is reasonable, as a guard
       against flaws in the CPRNG algorithm, no cryptographic primitive available
       today can hope to promise more than 256 bits of security, so if any program
       reads more than 256 bits (32 bytes) from the kernel random pool per
       invocation, or per reasonable reseed interval (not less than one minute),
       that should be taken as a sign that its cryptography is not skilfully
       implemented.

Configuration

       If your system does not have /dev/random and /dev/urandom created already,
       they can be created with the following commands:

           mknod -m 644 /dev/random c 1 8
           mknod -m 644 /dev/urandom c 1 9
           chown root:root /dev/random /dev/urandom

       When a Linux system starts up without much operator interaction, the
       entropy pool may be in a fairly predictable state.  This reduces the actual
       amount of noise in the entropy pool below the estimate.  In order to
       counteract this effect, it helps to carry entropy pool information across
       shut-downs and start-ups.  To do this, add the following lines to an
       appropriate script which is run during the Linux system start-up sequence:

           echo "Initializing random number generator..."
           random_seed=/var/run/random-seed
           # Carry a random seed from start-up to start-up
           # Load and then save the whole entropy pool
           if [ -f $random_seed ]; then
               cat $random_seed >/dev/urandom
           else
               touch $random_seed
           fi
           chmod 600 $random_seed
           poolfile=/proc/sys/kernel/random/poolsize
           [ -r $poolfile ] && bytes=`cat $poolfile` || bytes=512
           dd if=/dev/urandom of=$random_seed count=1 bs=$bytes

       Also, add the following lines in an appropriate script which is run during
       the Linux system shutdown:

           # Carry a random seed from shut-down to start-up
           # Save the whole entropy pool
           echo "Saving random seed..."
           random_seed=/var/run/random-seed
           touch $random_seed
           chmod 600 $random_seed
           poolfile=/proc/sys/kernel/random/poolsize
           [ -r $poolfile ] && bytes=`cat $poolfile` || bytes=512
           dd if=/dev/urandom of=$random_seed count=1 bs=$bytes

/proc Interface

       The files in the directory /proc/sys/kernel/random (present since 2.3.16)
       provide an additional interface to the /dev/random device.

       The read-only file entropy_avail gives the available entropy.  Normally,
       this will be 4096 (bits), a full entropy pool.

       The file poolsize gives the size of the entropy pool.  The semantics of
       this file vary across kernel versions:

              Linux 2.4:  This file gives the size of the entropy pool in bytes.
                          Normally, this file will have the value 512, but it is
                          writable, and can be changed to any value for which an
                          algorithm is available.  The choices are 32, 64, 128,
                          256, 512, 1024, or 2048.

              Linux 2.6:  This file is read-only, and gives the size of the
                          entropy pool in bits.  It contains the value 4096.

       The file read_wakeup_threshold contains the number of bits of entropy
       required for waking up processes that sleep waiting for entropy from
       /dev/random.  The default is 64.  The file write_wakeup_threshold contains
       the number of bits of entropy below which we wake up processes that do a
       select(2) or poll(2) for write access to /dev/random.  These values can be
       changed by writing to the files.

       The read-only files uuid and boot_id contain random strings like
       6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.  The former is generated afresh for
       each read, the latter was generated once.

FILES top

       /dev/random
       /dev/urandom

SEE ALSO top

       mknod(1)
       RFC 1750, "Randomness Recommendations for Security"

COLOPHON top

       This page is part of release 3.45 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                               2010-08-29                           RANDOM(4)


raw(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RAW(7)                       Linux Programmer's Manual                      RAW(7)

NAME top

       raw - Linux IPv4 raw sockets

SYNOPSIS top

       #include <sys/socket.h>
       #include <netinet/in.h>
       raw_socket = socket(AF_INET, SOCK_RAW, int protocol);

DESCRIPTION top

       Raw sockets allow new IPv4 protocols to be implemented in user space.  A
       raw socket receives or sends the raw datagram not including link level
       headers.

       The IPv4 layer generates an IP header when sending a packet unless the
       IP_HDRINCL socket option is enabled on the socket.  When it is enabled, the
       packet must contain an IP header.  For receiving the IP header is always
       included in the packet.

       Only processes with an effective user ID of 0 or the CAP_NET_RAW capability
       are allowed to open raw sockets.

       All packets or errors matching the protocol number specified for the raw
       socket are passed to this socket.  For a list of the allowed protocols see
       RFC 1700 assigned numbers and getprotobyname(3).

       A protocol of IPPROTO_RAW implies enabled IP_HDRINCL and is able to send
       any IP protocol that is specified in the passed header.  Receiving of all
       IP protocols via IPPROTO_RAW is not possible using raw sockets.

              +---------------------------------------------------+
              |IP Header fields modified on sending by IP_HDRINCL |
              +----------------------+----------------------------+
              |IP Checksum           |Always filled in.           |
              +----------------------+----------------------------+
              |Source Address        |Filled in when zero.        |
              +----------------------+----------------------------+
              |Packet Id             |Filled in when zero.        |
              +----------------------+----------------------------+
              |Total Length          |Always filled in.           |
              +----------------------+----------------------------+

       If IP_HDRINCL is specified and the IP header has a nonzero destination
       address then the destination address of the socket is used to route the
       packet.  When MSG_DONTROUTE is specified, the destination address should
       refer to a local interface, otherwise a routing table lookup is done anyway
       but gatewayed routes are ignored.

       If IP_HDRINCL isn't set, then IP header options can be set on raw sockets
       with setsockopt(2); see ip(7) for more information.

       In Linux 2.2, all IP header fields and options can be set using IP socket
       options.  This means raw sockets are usually only needed for new protocols
       or protocols with no user interface (like ICMP).

       When a packet is received, it is passed to any raw sockets which have been
       bound to its protocol before it is passed to other protocol handlers (e.g.,
       kernel protocol modules).

Address Format

       Raw sockets use the standard sockaddr_in address structure defined in
       ip(7).  The sin_port field could be used to specify the IP protocol number,
       but it is ignored for sending in Linux 2.2 and should be always set to 0
       (see BUGS).  For incoming packets, sin_port is set to the protocol of the
       packet.  See the <netinet/in.h> include file for valid IP protocols.

Socket Options

       Raw socket options can be set with setsockopt(2) and read with
       getsockopt(2) by passing the IPPROTO_RAW family flag.

       ICMP_FILTER
              Enable a special filter for raw sockets bound to the IPPROTO_ICMP
              protocol.  The value has a bit set for each ICMP message type which
              should be filtered out.  The default is to filter no ICMP messages.

       In addition, all ip(7) IPPROTO_IP socket options valid for datagram sockets
       are supported.

Error Handling

       Errors originating from the network are only passed to the user when the
       socket is connected or the IP_RECVERR flag is enabled.  For connected
       sockets, only EMSGSIZE and EPROTO are passed for compatibility.  With
       IP_RECVERR, all network errors are saved in the error queue.

ERRORS top

       EACCES User tried to send to a broadcast address without having the
              broadcast flag set on the socket.

       EFAULT An invalid memory address was supplied.

       EINVAL Invalid argument.

       EMSGSIZE
              Packet too big.  Either Path MTU Discovery is enabled (the
              IP_MTU_DISCOVER socket flag) or the packet size exceeds the maximum
              allowed IPv4 packet size of 64KB.

       EOPNOTSUPP
              Invalid flag has been passed to a socket call (like MSG_OOB).

       EPERM  The user doesn't have permission to open raw sockets.  Only
              processes with an effective user ID of 0 or the CAP_NET_RAW
              attribute may do that.

       EPROTO An ICMP error has arrived reporting a parameter problem.

VERSIONS top

       IP_RECVERR and ICMP_FILTER are new in Linux 2.2.  They are Linux extensions
       and should not be used in portable programs.

       Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket
       code when the SO_BSDCOMPAT socket option was set -- since Linux 2.2, this
       option no longer has that effect.

NOTES top

       By default, raw sockets do path MTU (Maximum Transmission Unit) discovery.
       This means the kernel will keep track of the MTU to a specific target IP
       address and return EMSGSIZE when a raw packet write exceeds it.  When this
       happens, the application should decrease the packet size.  Path MTU
       discovery can be also turned off using the IP_MTU_DISCOVER socket option or
       the /proc/sys/net/ipv4/ip_no_pmtu_disc file, see ip(7) for details.  When
       turned off, raw sockets will fragment outgoing packets that exceed the
       interface MTU.  However, disabling it is not recommended for performance
       and reliability reasons.

       A raw socket can be bound to a specific local address using the bind(2)
       call.  If it isn't bound, all packets with the specified IP protocol are
       received.  In addition, a RAW socket can be bound to a specific network
       device using SO_BINDTODEVICE; see socket(7).

       An IPPROTO_RAW socket is send only.  If you really want to receive all IP
       packets, use a packet(7) socket with the ETH_P_IP protocol.  Note that
       packet sockets don't reassemble IP fragments, unlike raw sockets.

       If you want to receive all ICMP packets for a datagram socket, it is often
       better to use IP_RECVERR on that particular socket; see ip(7).

       Raw sockets may tap all IP protocols in Linux, even protocols like ICMP or
       TCP which have a protocol module in the kernel.  In this case, the packets
       are passed to both the kernel module and the raw socket(s).  This should
       not be relied upon in portable programs, many other BSD socket
       implementation have limitations here.

       Linux never changes headers passed from the user (except for filling in
       some zeroed fields as described for IP_HDRINCL).  This differs from many
       other implementations of raw sockets.

       RAW sockets are generally rather unportable and should be avoided in
       programs intended to be portable.

       Sending on raw sockets should take the IP protocol from sin_port; this
       ability was lost in Linux 2.2.  The workaround is to use IP_HDRINCL.

BUGS top

       Transparent proxy extensions are not described.

       When the IP_HDRINCL option is set, datagrams will not be fragmented and are
       limited to the interface MTU.

       Setting the IP protocol for sending in sin_port got lost in Linux 2.2.  The
       protocol that the socket was bound to or that was specified in the initial
       socket(2) call is always used.

SEE ALSO top

       recvmsg(2), sendmsg(2), capabilities(7), ip(7), socket(7)

       RFC 1191 for path MTU discovery.  RFC 791 and the <linux/ip.h> header file
       for the IP protocol.

COLOPHON top

       This page is part of release 3.45 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                               2012-05-10                              RAW(7)


read(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

READ(2)                      Linux Programmer's Manual                     READ(2)

NAME top

       read - read from a file descriptor

SYNOPSIS top

       #include <unistd.h>

       ssize_t read(int fd, void *buf, size_t count);

DESCRIPTION top

       read() attempts to read up to count bytes from file descriptor fd into the
       buffer starting at buf.

       If count is zero, read() returns zero and has no other results.  If count
       is greater than SSIZE_MAX, the result is unspecified.

RETURN VALUE top

       On success, the number of bytes read is returned (zero indicates end of
       file), and the file position is advanced by this number.  It is not an
       error if this number is smaller than the number of bytes requested; this
       may happen for example because fewer bytes are actually available right now
       (maybe because we were close to end-of-file, or because we are reading from
       a pipe, or from a terminal), or because read() was interrupted by a signal.
       On error, -1 is returned, and errno is set appropriately.  In this case it
       is left unspecified whether the file position (if any) changes.

ERRORS top

       EAGAIN The file descriptor fd refers to a file other than a socket and has
              been marked nonblocking (O_NONBLOCK), and the read would block.

       EAGAIN or EWOULDBLOCK
              The file descriptor fd refers to a socket and has been marked
              nonblocking (O_NONBLOCK), and the read would block.  POSIX.1-2001
              allows either error to be returned for this case, and does not
              require these constants to have the same value, so a portable
              application should check for both possibilities.

       EBADF  fd is not a valid file descriptor or is not open for reading.

       EFAULT buf is outside your accessible address space.

       EINTR  The call was interrupted by a signal before any data was read; see
              signal(7).

       EINVAL fd is attached to an object which is unsuitable for reading; or the
              file was opened with the O_DIRECT flag, and either the address
              specified in buf, the value specified in count, or the current file
              offset is not suitably aligned.

       EINVAL fd was created via a call to timerfd_create(2) and the wrong size
              buffer was given to read(); see timerfd_create(2) for further
              information.

       EIO    I/O error.  This will happen for example when the process is in a
              background process group, tries to read from its controlling tty,
              and either it is ignoring or blocking SIGTTIN or its process group
              is orphaned.  It may also occur when there is a low-level I/O error
              while reading from a disk or tape.

       EISDIR fd refers to a directory.

       Other errors may occur, depending on the object connected to fd.  POSIX
       allows a read() that is interrupted after reading some data to return -1
       (with errno set to EINTR) or to return the number of bytes already read.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       On NFS file systems, reading small amounts of data will only update the
       timestamp the first time, subsequent calls may not do so.  This is caused
       by client side attribute caching, because most if not all NFS clients leave
       st_atime (last file access time) updates to the server and client side
       reads satisfied from the client's cache will not cause st_atime updates on
       the server as there are no server side reads.  UNIX semantics can be
       obtained by disabling client side attribute caching, but in most situations
       this will substantially increase server load and decrease performance.

       Many file systems and disks were considered to be fast enough that the
       implementation of O_NONBLOCK was deemed unnecessary.  So, O_NONBLOCK may
       not be available on files and/or disks.

SEE ALSO top

       close(2), fcntl(2), ioctl(2), lseek(2), open(2), pread(2), readdir(2),
       readlink(2), readv(2), select(2), write(2), fread(3)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-23                             READ(2)


readahead(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

READAHEAD(2)                 Linux Programmer's Manual                READAHEAD(2)

NAME top

       readahead - perform file readahead into page cache

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <fcntl.h>

       ssize_t readahead(int fd, off64_t offset, size_t count);

DESCRIPTION top

       readahead() populates the page cache with data from a file so that
       subsequent reads from that file will not block on disk I/O.  The fd
       argument is a file descriptor identifying the file which is to be read.
       The offset argument specifies the starting point from which data is to be
       read and count specifies the number of bytes to be read.  I/O is performed
       in whole pages, so that offset is effectively rounded down to a page
       boundary and bytes are read up to the next page boundary greater than or
       equal to (offset+count).  readahead() does not read beyond the end of the
       file.  readahead() blocks until the specified data has been read.  The
       current file offset of the open file referred to by fd is left unchanged.

RETURN VALUE top

       On success, readahead() returns 0; on failure, -1 is returned, with errno
       set to indicate the cause of the error.

ERRORS top

       EBADF  fd is not a valid file descriptor or is not open for reading.

       EINVAL fd does not refer to a file type to which readahead() can be
              applied.

VERSIONS top

       The readahead() system call appeared in Linux 2.4.13; glibc support has
       been provided since version 2.3.

CONFORMING TO top

       The readahead() system call is Linux-specific, and its use should be
       avoided in portable applications.

SEE ALSO top

       lseek(2), madvise(2), mmap(2), posix_fadvise(2), read(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10                        READAHEAD(2)


readdir(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

READDIR(2)                   Linux Programmer's Manual                  READDIR(2)

NAME top

       readdir - read directory entry

SYNOPSIS top

       int readdir(unsigned int fd, struct old_linux_dirent *dirp,
                   unsigned int count);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       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, which is superseded by getdents(2).

       readdir() reads one old_linux_dirent structure from the directory referred
       to by the file descriptor fd into the buffer pointed to by dirp.  The
       argument count is ignored; at most one old_linux_dirent structure is read.

       The old_linux_dirent structure is declared as follows:

           struct old_linux_dirent {
               long  d_ino;              /* inode number */
               off_t d_off;              /* offset to this old_linux_dirent */
               unsigned short d_reclen;  /* length of this d_name */
               char  d_name[NAME_MAX+1]; /* filename (null-terminated) */
           }

       d_ino is an inode number.  d_off is the distance from the start of the
       directory to this old_linux_dirent.  d_reclen is the size of d_name, not
       counting the terminating null byte.  d_name is a null-terminated filename.

RETURN VALUE top

       On success, 1 is returned.  On end of directory, 0 is returned.  On error,
       -1 is returned, and errno is set appropriately.

ERRORS top

       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 top

       This system call is Linux-specific.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).  You will need to define the old_linux_dirent structure
       yourself.  However, probably you should use readdir(3) instead.

SEE ALSO top

       getdents(2), readdir(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                          READDIR(2)


readdir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

READDIR(3)                   Linux Programmer's Manual                  READDIR(3)

NAME top

       readdir, readdir_r - read a directory

SYNOPSIS top

       #include <dirent.h>

       struct dirent *readdir(DIR *dirp);

       int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);

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

       readdir_r():
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||
           _POSIX_SOURCE

DESCRIPTION top

       The readdir() function returns a pointer to a dirent structure representing
       the next directory entry in the directory stream pointed to by dirp.  It
       returns NULL on reaching the end of the directory stream or if an error
       occurred.

       On Linux, the dirent structure is defined as follows:

           struct dirent {
               ino_t          d_ino;       /* inode number */
               off_t          d_off;       /* offset to the next dirent */
               unsigned short d_reclen;    /* length of this record */
               unsigned char  d_type;      /* type of file; not supported
                                              by all file system types */
               char           d_name[256]; /* filename */
           };

       The only fields in the dirent structure that are mandated by POSIX.1 are:
       d_name[], of unspecified size, with at most NAME_MAX characters preceding
       the terminating null byte; and (as an XSI extension) d_ino.  The other
       fields are unstandardized, and not present on all systems; see NOTES below
       for some further details.

       The data returned by readdir() may be overwritten by subsequent calls to
       readdir() for the same directory stream.

       The readdir_r() function is a reentrant version of readdir().  It reads the
       next directory entry from the directory stream dirp, and returns it in the
       caller-allocated buffer pointed to by entry.  (See NOTES for information on
       allocating this buffer.)  A pointer to the returned item is placed in
       *result; if the end of the directory stream was encountered, then NULL is
       instead returned in *result.

RETURN VALUE top

       On success, readdir() returns a pointer to a dirent structure.  (This
       structure may be statically allocated; do not attempt to free(3) it.)  If
       the end of the directory stream is reached, NULL is returned and errno is
       not changed.  If an error occurs, NULL is returned and errno is set
       appropriately.

       The readdir_r() function returns 0 on success.  On error, it returns a
       positive error number (listed under ERRORS).  If the end of the directory
       stream is reached, readdir_r() returns 0, and returns NULL in *result.

ERRORS top

       EBADF  Invalid directory stream descriptor dirp.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       Only the fields d_name and d_ino are specified in POSIX.1-2001.  The
       remaining fields are available on many, but not all systems.  Under glibc,
       programs can check for the availability of the fields not defined in
       POSIX.1 by testing whether the macros _DIRENT_HAVE_D_NAMLEN,
       _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF, or _DIRENT_HAVE_D_TYPE are
       defined.

       Other than Linux, the d_type field is available mainly only on BSD systems.
       This field makes it possible to avoid the expense of calling lstat(2) if
       further actions depend on the type of the file.  If the _BSD_SOURCE feature
       test macro is defined, then glibc defines the following macro constants for
       the value returned in d_type:

       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.

       If the file type could not be determined, the value DT_UNKNOWN is returned
       in d_type.

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

       Since POSIX.1 does not specify the size of the d_name field, and other
       nonstandard fields may precede that field within the dirent structure,
       portable applications that use readdir_r() should allocate the buffer whose
       address is passed in entry as follows:

           name_max = pathconf(dirpath, _PC_NAME_MAX);
           if (name_max == -1)         /* Limit not defined, or error */
               name_max = 255;         /* Take a guess */
           len = offsetof(struct dirent, d_name) + name_max + 1;
           entryp = malloc(len);

       (POSIX.1 requires that d_name is the last field in a struct dirent.)

SEE ALSO top

       getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3),
       opendir(3), rewinddir(3), scandir(3), seekdir(3), telldir(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-07-07                          READDIR(3)


readlink(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

READLINK(2)                  Linux Programmer's Manual                 READLINK(2)

NAME top

       readlink - read value of a symbolic link

SYNOPSIS top

       #include <unistd.h>

       ssize_t readlink(const char *path, char *buf, size_t bufsiz);

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

       readlink():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       readlink() places the contents of the symbolic link path in the buffer buf,
       which has size bufsiz.  readlink() does not append a null byte to buf.  It
       will truncate the contents (to a length of bufsiz characters), in case the
       buffer is too small to hold all of the contents.

RETURN VALUE top

       On success, readlink() returns the number of bytes placed in buf.  On
       error, -1 is returned and errno is set to indicate the error.

ERRORS top

       EACCES Search permission is denied for a component of the path prefix.
              (See also path_resolution(7).)

       EFAULT buf extends outside the process's allocated address space.

       EINVAL bufsiz is not positive.

       EINVAL The named file is not a symbolic link.

       EIO    An I/O error occurred while reading from the file system.

       ELOOP  Too many symbolic links were encountered in translating the
              pathname.

       ENAMETOOLONG
              A pathname, or a component of a pathname, was too long.

       ENOENT The named file does not exist.

       ENOMEM Insufficient kernel memory was available.

       ENOTDIR
              A component of the path prefix is not a directory.

CONFORMING TO top

       4.4BSD (readlink() first appeared in 4.2BSD), POSIX.1-2001.

NOTES top

       In versions of glibc up to and including glibc 2.4, the return type of
       readlink() was declared as int.  Nowadays, the return type is declared as
       ssize_t, as (newly) required in POSIX.1-2001.

       Using a statically sized buffer might not provide enough room for the
       symbolic link contents.  The required size for the buffer can be obtained
       from the stat.st_size value returned by a call to lstat(2) on the link.
       However, the number of bytes written by readlink() should be checked to
       make sure that the size of the symbolic link did not increase between the
       calls.  Dynamically allocating the buffer for readlink() also addresses a
       common portability problem when using PATH_MAX for the buffer size, as this
       constant is not guaranteed to be defined per POSIX if the system does not
       have such limit.

EXAMPLE top

       The following program allocates the buffer needed by readlink() dynamically
       from the information provided by lstat(), making sure there's no race
       condition between the calls.

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

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

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

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

           linkname = malloc(sb.st_size + 1);
           if (linkname == NULL) {
               fprintf(stderr, "insufficient memory\n");
               exit(EXIT_FAILURE);
           }

           r = readlink(argv[1], linkname, sb.st_size + 1);

           if (r < 0) {
               perror("lstat");
               exit(EXIT_FAILURE);
           }

           if (r > sb.st_size) {
               fprintf(stderr, "symlink increased in size "
                               "between lstat() and readlink()\n");
               exit(EXIT_FAILURE);
           }

           linkname[sb.st_size] = '\0';

           printf("'%s' points to '%s'\n", argv[1], linkname);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       readlink(1), lstat(2), readlinkat(2), stat(2), symlink(2),
       path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-20                         READLINK(2)


readlinkat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

READLINKAT(2)                Linux Programmer's Manual               READLINKAT(2)

NAME top

       readlinkat  -  read  value  of a symbolic link relative to a directory file
       descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <unistd.h>

       int readlinkat(int dirfd, const char *pathname,
                      char *buf, size_t bufsiz);

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

       readlinkat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The readlinkat() system call operates in exactly the same way as
       readlink(2), except for the differences described in this manual page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by readlink(2) for a relative pathname).

       If pathname is relative and dirfd is the special value AT_FDCWD, then
       pathname is interpreted relative to the current working directory of the
       calling process (like readlink(2)).

       If pathname is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, readlinkat() returns the number of bytes placed in buf.  On
       error, -1 is returned and errno is set to indicate the error.

ERRORS top

       The same errors that occur for readlink(2) can also occur for readlinkat().
       The following additional errors can occur for readlinkat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       readlinkat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for readlinkat().

SEE ALSO top

       openat(2), readlink(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                       READLINKAT(2)


realpath(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

REALPATH(3)                  Linux Programmer's Manual                 REALPATH(3)

NAME top

       realpath - return the canonicalized absolute pathname

SYNOPSIS top

       #include <limits.h>
       #include <stdlib.h>

       char *realpath(const char *path, char *resolved_path);

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

       realpath():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       realpath() expands all symbolic links and resolves references to /./, /../
       and extra '/' characters in the null-terminated string named by path to
       produce a canonicalized absolute pathname.  The resulting pathname is
       stored as a null-terminated string, up to a maximum of PATH_MAX bytes, in
       the buffer pointed to by resolved_path.  The resulting path will have no
       symbolic link, /./ or /../ components.

       If resolved_path is specified as NULL, then realpath() uses malloc(3) to
       allocate a buffer of up to PATH_MAX bytes to hold the resolved pathname,
       and returns a pointer to this buffer.  The caller should deallocate this
       buffer using free(3).

RETURN VALUE top

       If there is no error, realpath() returns a pointer to the resolved_path.

       Otherwise it returns a NULL pointer, and the contents of the array
       resolved_path are undefined, and errno is set to indicate the error.

ERRORS top

       EACCES Read or search permission was denied for a component of the path
              prefix.

       EINVAL path is NULL.  (In glibc versions before 2.3, this error is also
              returned if resolved_path is NULL.)

       EIO    An I/O error occurred while reading from the file system.

       ELOOP  Too many symbolic links were encountered in translating the
              pathname.

       ENAMETOOLONG
              A component of a pathname exceeded NAME_MAX characters, or an entire
              pathname exceeded PATH_MAX characters.

       ENOENT The named file does not exist.

       ENOTDIR
              A component of the path prefix is not a directory.

VERSIONS top

       On Linux this function appeared in libc 4.5.21.

CONFORMING TO top

       4.4BSD, POSIX.1-2001.

       POSIX.1-2001 says that the behavior if resolved_path is NULL is
       implementation-defined.  POSIX.1-2008 specifies the behavior described in
       this page.

NOTES top

       In 4.4BSD and Solaris the limit on the pathname length is MAXPATHLEN (found
       in <sys/param.h>).  SUSv2 prescribes PATH_MAX and NAME_MAX, as found in
       <limits.h> or provided by the pathconf(3) function.  A typical source
       fragment would be

           #ifdef PATH_MAX
             path_max = PATH_MAX;
           #else
             path_max = pathconf(path, _PC_PATH_MAX);
             if (path_max <= 0)
               path_max = 4096;
           #endif

       (But see the BUGS section.)

       The prototype of realpath() is given in <unistd.h> in libc4 and libc5, but
       in <stdlib.h> everywhere else.

BUGS top

       The POSIX.1-2001 standard version of this function is broken by design,
       since it is impossible to determine a suitable size for the output buffer,
       resolved_path.  According to POSIX.1-2001 a buffer of size PATH_MAX
       suffices, but PATH_MAX need not be a defined constant, and may have to be
       obtained using pathconf(3).  And asking pathconf(3) does not really help,
       since, on the one hand POSIX warns that the result of pathconf(3) may be
       huge and unsuitable for mallocing memory, and on the other hand pathconf(3)
       may return -1 to signify that PATH_MAX is not bounded.  The
       resolved_path == NULL feature, not standardized in POSIX.1-2001, but
       standardized in POSIX.1-2008, allows this design problem to be avoided.

       The libc4 and libc5 implementation contained a buffer overflow (fixed in
       libc-5.4.13).  Thus, set-user-ID programs like mount(8) needed a private
       version.

SEE ALSO top

       readlink(2), canonicalize_file_name(3), getcwd(3), pathconf(3), sysconf(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-08-14                         REALPATH(3)


reboot(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

REBOOT(2)                    Linux Programmer's Manual                   REBOOT(2)

NAME top

       reboot - reboot or enable/disable Ctrl-Alt-Del

SYNOPSIS top

       /* For libc4 and libc5 the library call and the system call
          are identical, and since kernel version 2.1.30 there are
          symbolic names LINUX_REBOOT_* for the constants and a
          fourth argument to the call: */

       #include <unistd.h>
       #include <linux/reboot.h>

       int reboot(int magic, int magic2, int cmd, void *arg);

       /* Under glibc some of the constants involved have gotten
          symbolic names RB_*, and the library call is a 1-argument
          wrapper around the 3-argument system call: */

       #include <unistd.h>
       #include <sys/reboot.h>

       int reboot(int cmd);

DESCRIPTION top

       The reboot() call reboots the system, or enables/disables the reboot
       keystroke (abbreviated CAD, since the default is Ctrl-Alt-Delete; it can be
       changed using loadkeys(1)).

       This system call will fail (with EINVAL) unless magic equals
       LINUX_REBOOT_MAGIC1 (that is, 0xfee1dead) and magic2 equals
       LINUX_REBOOT_MAGIC2 (that is, 672274793).  However, since 2.1.17 also
       LINUX_REBOOT_MAGIC2A (that is, 85072278) and since 2.1.97 also
       LINUX_REBOOT_MAGIC2B (that is, 369367448) and since 2.5.71 also
       LINUX_REBOOT_MAGIC2C (that is, 537993216) are permitted as value for
       magic2.  (The hexadecimal values of these constants are meaningful.)  The
       cmd argument can have the following values:

       LINUX_REBOOT_CMD_CAD_OFF
              (RB_DISABLE_CAD, 0).  CAD is disabled.  This means that the CAD
              keystroke will cause a SIGINT signal to be sent to init (process 1),
              whereupon this process may decide upon a proper action (maybe: kill
              all processes, sync, reboot).

       LINUX_REBOOT_CMD_CAD_ON
              (RB_ENABLE_CAD, 0x89abcdef).  CAD is enabled.  This means that the
              CAD keystroke will immediately cause the action associated with
              LINUX_REBOOT_CMD_RESTART.

       LINUX_REBOOT_CMD_HALT
              (RB_HALT_SYSTEM, 0xcdef0123; since 1.1.76).  The message "System
              halted." is printed, and the system is halted.  Control is given to
              the ROM monitor, if there is one.  If not preceded by a sync(2),
              data will be lost.

       LINUX_REBOOT_CMD_KEXEC (since Linux 2.6.13)
              Execute a kernel that has been loaded earlier with kexec_load(2).
              This option is only available if the kernel was configured with
              CONFIG_KEXEC.

       LINUX_REBOOT_CMD_POWER_OFF
              (0x4321fedc; since 2.1.30).  The message "Power down." is printed,
              the system is stopped, and all power is removed from the system, if
              possible.  If not preceded by a sync(2), data will be lost.

       LINUX_REBOOT_CMD_RESTART
              (RB_AUTOBOOT, 0x1234567).  The message "Restarting system." is
              printed, and a default restart is performed immediately.  If not
              preceded by a sync(2), data will be lost.

       LINUX_REBOOT_CMD_RESTART2
              (0xa1b2c3d4; since 2.1.30).  The message "Restarting system with
              command '%s'" is printed, and a restart (using the command string
              given in arg) is performed immediately.  If not preceded by a
              sync(2), data will be lost.

       Only the superuser may call reboot().

       The precise effect of the above actions depends on the architecture.  For
       the i386 architecture, the additional argument does not do anything at
       present (2.1.122), but the type of reboot can be determined by kernel
       command-line arguments ("reboot=...") to be either warm or cold, and either
       hard or through the BIOS.

RETURN VALUE top

       For the values of cmd that stop or restart the system, a successful call to
       reboot() does not return.  For the other cmd values, zero is returned on
       success.  In all cases, -1 is returned on failure, and errno is set
       appropriately.

ERRORS top

       EFAULT Problem with getting user-space data under
              LINUX_REBOOT_CMD_RESTART2.

       EINVAL Bad magic numbers or cmd.

       EPERM  The calling process has insufficient privilege to call reboot(); the
              CAP_SYS_BOOT capability is required.

CONFORMING TO top

       reboot() is Linux-specific, and should not be used in programs intended to
       be portable.

SEE ALSO top

       sync(2), bootparam(7), capabilities(7), ctrlaltdel(8), halt(8), reboot(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-31                           REBOOT(2)


recno(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RECNO(3)                     Linux Programmer's Manual                    RECNO(3)

NAME top

       recno - record number database access method

SYNOPSIS top

       #include <sys/types.h>
       #include <db.h>

DESCRIPTION top

       Note well: This page documents interfaces provided in glibc up until
       version 2.1.  Since version 2.2, glibc no longer provides these interfaces.
       Probably, you are looking for the APIs provided by the libdb library
       instead.

       The routine dbopen(3) is the library interface to database files.  One of
       the supported file formats is record number files.  The general description
       of the database access methods is in dbopen(3), this manual page describes
       only the recno specific information.

       The record number data structure is either variable or fixed-length records
       stored in a flat-file format, accessed by the logical record number.  The
       existence of record number five implies the existence of records one
       through four, and the deletion of record number one causes record number
       five to be renumbered to record number four, as well as the cursor, if
       positioned after record number one, to shift down one record.

       The recno access method specific data structure provided to dbopen(3) is
       defined in the <db.h> include file as follows:

           typedef struct {
               unsigned long flags;
               unsigned int  cachesize;
               unsigned int  psize;
               int           lorder;
               size_t        reclen;
               unsigned char bval;
               char         *bfname;
           } RECNOINFO;

       The elements of this structure are defined as follows:

       flags  The flag value is specified by ORing any of the following values:

              R_FIXEDLEN
                     The records are fixed-length, not byte delimited.  The
                     structure element reclen specifies the length of the record,
                     and the structure element bval is used as the pad character.
                     Any records, inserted into the database, that are less than
                     reclen bytes long are automatically padded.

              R_NOKEY
                     In the interface specified by dbopen(3), the sequential
                     record retrieval fills in both the caller's key and data
                     structures.  If the R_NOKEY flag is specified, the cursor
                     routines are not required to fill in the key structure.  This
                     permits applications to retrieve records at the end of files
                     without reading all of the intervening records.

              R_SNAPSHOT
                     This flag requires that a snapshot of the file be taken when
                     dbopen(3) is called, instead of permitting any unmodified
                     records to be read from the original file.

       cachesize
              A suggested maximum size, in bytes, of the memory cache.  This value
              is only advisory, and the access method will allocate more memory
              rather than fail.  If cachesize is  0 (no size is specified) a
              default cache is used.

       psize  The recno access method stores the in-memory copies of its records
              in a btree.  This value is the size (in bytes) of the pages used for
              nodes in that tree.  If psize is 0 (no page size is specified) a
              page size is chosen based on the underlying file system I/O block
              size.  See btree(3) for more information.

       lorder The byte order for integers in the stored database metadata.  The
              number should represent the order as an integer; for example, big
              endian order would be the number 4,321.  If lorder is 0 (no order is
              specified) the current host order is used.

       reclen The length of a fixed-length record.

       bval   The delimiting byte to be used to mark the end of a record for
              variable-length records, and the pad character for fixed-length
              records.  If no value is specified, newlines ("\n") are used to mark
              the end of variable-length records and fixed-length records are
              padded with spaces.

       bfname The recno access method stores the in-memory copies of its records
              in a btree.  If bfname is non-NULL, it specifies the name of the
              btree file, as if specified as the filename for a dbopen(3) of a
              btree file.

       The data part of the key/data pair used by the recno access method is the
       same as other access methods.  The key is different.  The data field of the
       key should be a pointer to a memory location of type recno_t, as defined in
       th <db.h> include file.  This type is normally the largest unsigned
       integral type available to the implementation.  The size field of the key
       should be the size of that type.

       Because there can be no metadata associated with the underlying recno
       access method files, any changes made to the default values (e.g., fixed
       record length or byte separator value) must be explicitly specified each
       time the file is opened.

       In the interface specified by dbopen(3), using the put interface to create
       a new record will cause the creation of multiple, empty records if the
       record number is more than one greater than the largest record currently in
       the database.

ERRORS top

       The recno access method routines may fail and set errno for any of the
       errors specified for the library routine dbopen(3) or the following:

       EINVAL An attempt was made to add a record to a fixed-length database that
              was too large to fit.

BUGS top

       Only big and little endian byte order is supported.

SEE ALSO top

       btree(3), dbopen(3), hash(3), mpool(3)

       Document Processing in a Relational Database System, Michael Stonebraker,
       Heidi Stettner, Joseph Kalash, Antonin Guttman, Nadene Lynn, Memorandum No.
       UCB/ERL M82/32, May 1982.

COLOPHON top

       This page is part of release 3.45 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/.

4.4 Berkeley Distribution           2012-04-23                            RECNO(3)


recv(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

RECV(2)                      Linux Programmer's Manual                     RECV(2)

NAME top

       recv, recvfrom, recvmsg - receive a message from a socket

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/socket.h>

       ssize_t recv(int sockfd, void *buf, size_t len, int flags);

       ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
                        struct sockaddr *src_addr, socklen_t *addrlen);

       ssize_t recvmsg(int sockfd, struct msghdr *msg, int flags);

DESCRIPTION top

       The recvfrom() and recvmsg() calls are used to receive messages from a
       socket, and may be used to receive data on a socket whether or not it is
       connection-oriented.

       If src_addr is not NULL, and the underlying protocol provides the source
       address, this source address is filled in.  When src_addr is NULL, nothing
       is filled in; in this case, addrlen is not used, and should also be NULL.
       The argument addrlen is a value-result argument, which the caller should
       initialize before the call to the size of the buffer associated with
       src_addr, and modified on return to indicate the actual size of the source
       address.  The returned address is truncated if the buffer provided is too
       small; in this case, addrlen will return a value greater than was supplied
       to the call.

       The recv() call is normally used only on a connected socket (see
       connect(2)) and is identical to recvfrom() with a NULL src_addr argument.

       All three routines return the length of the message on successful
       completion.  If a message is too long to fit in the supplied buffer, excess
       bytes may be discarded depending on the type of socket the message is
       received from.

       If no messages are available at the socket, the receive calls wait for a
       message to arrive, unless the socket is nonblocking (see fcntl(2)), in
       which case the value -1 is returned and the external variable errno is set
       to EAGAIN or EWOULDBLOCK.  The receive calls normally return any data
       available, up to the requested amount, rather than waiting for receipt of
       the full amount requested.

       The select(2) or poll(2) call may be used to determine when more data
       arrives.

       The flags argument to a recv() call is formed by ORing one or more of the
       following values:

       MSG_CMSG_CLOEXEC (recvmsg() only; since Linux 2.6.23)
              Set the close-on-exec flag for the file descriptor received via a
              UNIX domain file descriptor using the SCM_RIGHTS operation
              (described in unix(7)).  This flag is useful for the same reasons as
              the O_CLOEXEC flag of open(2).

       MSG_DONTWAIT (since Linux 2.2)
              Enables nonblocking operation; if the operation would block, the
              call fails with the error EAGAIN or EWOULDBLOCK (this can also be
              enabled using the O_NONBLOCK flag with the F_SETFL fcntl(2)).

       MSG_ERRQUEUE (since Linux 2.2)
              This flag specifies that queued errors should be received from the
              socket error queue.  The error is passed in an ancillary message
              with a type dependent on the protocol (for IPv4 IP_RECVERR).  The
              user should supply a buffer of sufficient size.  See cmsg(3) and
              ip(7) for more information.  The payload of the original packet that
              caused the error is passed as normal data via msg_iovec.  The
              original destination address of the datagram that caused the error
              is supplied via msg_name.

              For local errors, no address is passed (this can be checked with the
              cmsg_len member of the cmsghdr).  For error receives, the
              MSG_ERRQUEUE is set in the msghdr.  After an error has been passed,
              the pending socket error is regenerated based on the next queued
              error and will be passed on the next socket operation.

              The error is supplied in a sock_extended_err structure:

                  #define SO_EE_ORIGIN_NONE    0
                  #define SO_EE_ORIGIN_LOCAL   1
                  #define SO_EE_ORIGIN_ICMP    2
                  #define SO_EE_ORIGIN_ICMP6   3

                  struct sock_extended_err
                  {
                      uint32_t ee_errno;   /* error number */
                      uint8_t  ee_origin;  /* where the error originated */
                      uint8_t  ee_type;    /* type */
                      uint8_t  ee_code;    /* code */
                      uint8_t  ee_pad;     /* padding */
                      uint32_t ee_info;    /* additional information */
                      uint32_t ee_data;    /* other data */
                      /* More data may follow */
                  };

                  struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);

              ee_errno contains the errno number of the queued error.  ee_origin
              is the origin code of where the error originated.  The other fields
              are protocol-specific.  The macro SOCK_EE_OFFENDER returns a pointer
              to the address of the network object where the error originated from
              given a pointer to the ancillary message.  If this address is not
              known, the sa_family member of the sockaddr contains AF_UNSPEC and
              the other fields of the sockaddr are undefined.  The payload of the
              packet that caused the error is passed as normal data.

              For local errors, no address is passed (this can be checked with the
              cmsg_len member of the cmsghdr).  For error receives, the
              MSG_ERRQUEUE is set in the msghdr.  After an error has been passed,
              the pending socket error is regenerated based on the next queued
              error and will be passed on the next socket operation.

       MSG_OOB
              This flag requests receipt of out-of-band data that would not be
              received in the normal data stream.  Some protocols place expedited
              data at the head of the normal data queue, and thus this flag cannot
              be used with such protocols.

       MSG_PEEK
              This flag causes the receive operation to return data from the
              beginning of the receive queue without removing that data from the
              queue.  Thus, a subsequent receive call will return the same data.

       MSG_TRUNC (since Linux 2.2)
              For raw (AF_PACKET), Internet datagram (since Linux 2.4.27/2.6.8),
              netlink (since Linux 2.6.22) and UNIX datagram (since Linux 3.4)
              sockets: return the real length of the packet or datagram, even when
              it was longer than the passed buffer.  Not implemented for UNIX
              domain (unix(7)) sockets.

              For use with Internet stream sockets, see tcp(7).

       MSG_WAITALL (since Linux 2.2)
              This flag requests that the operation block until the full request
              is satisfied.  However, the call may still return less data than
              requested if a signal is caught, an error or disconnect occurs, or
              the next data to be received is of a different type than that
              returned.

       The recvmsg() call uses a msghdr structure to minimize the number of
       directly supplied arguments.  This structure is defined as follows in
       <sys/socket.h>:

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

           struct msghdr {
               void         *msg_name;       /* optional address */
               socklen_t     msg_namelen;    /* size of address */
               struct iovec *msg_iov;        /* scatter/gather array */
               size_t        msg_iovlen;     /* # elements in msg_iov */
               void         *msg_control;    /* ancillary data, see below */
               size_t        msg_controllen; /* ancillary data buffer len */
               int           msg_flags;      /* flags on received message */
           };

       Here msg_name and msg_namelen specify the source address if the socket is
       unconnected; msg_name may be given as a NULL pointer if no names are
       desired or required.  The fields msg_iov and msg_iovlen describe scatter-
       gather locations, as discussed in readv(2).  The field msg_control, which
       has length msg_controllen, points to a buffer for other protocol control-
       related messages or miscellaneous ancillary data.  When recvmsg() is
       called, msg_controllen should contain the length of the available buffer in
       msg_control; upon return from a successful call it will contain the length
       of the control message sequence.

       The messages are of the form:

           struct cmsghdr {
               socklen_t     cmsg_len;     /* data byte count, including hdr */
               int           cmsg_level;   /* originating protocol */
               int           cmsg_type;    /* protocol-specific type */
           /* followed by
               unsigned char cmsg_data[]; */
           };

       Ancillary data should only be accessed by the macros defined in cmsg(3).

       As an example, Linux uses this ancillary data mechanism to pass extended
       errors, IP options, or file descriptors over UNIX domain sockets.

       The msg_flags field in the msghdr is set on return of recvmsg().  It can
       contain several flags:

       MSG_EOR
              indicates end-of-record; the data returned completed a record
              (generally used with sockets of type SOCK_SEQPACKET).

       MSG_TRUNC
              indicates that the trailing portion of a datagram was discarded
              because the datagram was larger than the buffer supplied.

       MSG_CTRUNC
              indicates that some control data were discarded due to lack of space
              in the buffer for ancillary data.

       MSG_OOB
              is returned to indicate that expedited or out-of-band data were
              received.

       MSG_ERRQUEUE
              indicates that no data was received but an extended error from the
              socket error queue.

RETURN VALUE top

       These calls return the number of bytes received, or -1 if an error
       occurred.  The return value will be 0 when the peer has performed an
       orderly shutdown.

ERRORS top

       These are some standard errors generated by the socket layer.  Additional
       errors may be generated and returned from the underlying protocol modules;
       see their manual pages.

       EAGAIN or EWOULDBLOCK
              The socket is marked nonblocking and the receive operation would
              block, or a receive timeout had been set and the timeout expired
              before data was received.  POSIX.1-2001 allows either error to be
              returned for this case, and does not require these constants to have
              the same value, so a portable application should check for both
              possibilities.

       EBADF  The argument sockfd is an invalid descriptor.

       ECONNREFUSED
              A remote host refused to allow the network connection (typically
              because it is not running the requested service).

       EFAULT The receive buffer pointer(s) point outside the process's address
              space.

       EINTR  The receive was interrupted by delivery of a signal before any data
              were available; see signal(7).

       EINVAL Invalid argument passed.

       ENOMEM Could not allocate memory for recvmsg().

       ENOTCONN
              The socket is associated with a connection-oriented protocol and has
              not been connected (see connect(2) and accept(2)).

       ENOTSOCK
              The argument sockfd does not refer to a socket.

CONFORMING TO top

       4.4BSD (these function calls first appeared in 4.2BSD), POSIX.1-2001.

       POSIX.1-2001 only describes the MSG_OOB, MSG_PEEK, and MSG_WAITALL flags.

NOTES top

       The prototypes given above follow glibc2.  The Single UNIX Specification
       agrees, except that it has return values of type ssize_t (while 4.x BSD and
       libc4 and libc5 all have int).  The flags argument is int in 4.x BSD, but
       unsigned int in libc4 and libc5.  The len argument is int in 4.x BSD, but
       size_t in libc4 and libc5.  The addrlen argument is int * in 4.x BSD, libc4
       and libc5.  The present  socklen_t * was invented by POSIX.  See also
       accept(2).

       According to POSIX.1-2001, the msg_controllen field of the msghdr structure
       should be typed as socklen_t, but glibc currently types it as size_t.

       See recvmmsg(2) for information about a Linux-specific system call that can
       be used to receive multiple datagrams in a single call.

EXAMPLE top

       An example of the use of recvfrom() is shown in getaddrinfo(3).

SEE ALSO top

       fcntl(2), getsockopt(2), read(2), recvmmsg(2), select(2), shutdown(2),
       socket(2), cmsg(3), sockatmark(3), socket(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-21                             RECV(2)


recvmmsg(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

RECVMMSG(2)                  Linux Programmer's Manual                 RECVMMSG(2)

NAME top

       recvmmsg - receive multiple messages on a socket

SYNOPSIS top

       #define _GNU_SOURCE
       #include <sys/socket.h>

       int recvmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen,
                    unsigned int flags, struct timespec *timeout);

DESCRIPTION top

       The recvmmsg() system call is an extension of recvmsg(2) that allows the
       caller to receive multiple messages from a socket using a single system
       call.  (This has performance benefits for some applications.)  A further
       extension over recvmsg(2) is support for a timeout on the receive
       operation.

       The sockfd argument is the file descriptor of the socket to receive data
       from.

       The msgvec argument is a pointer to an array of mmsghdr structures.  The
       size of this array is specified in vlen.

       The mmsghdr structure is defined in <sys/socket.h> as:

           struct mmsghdr {
               struct msghdr msg_hdr;  /* Message header */
               unsigned int  msg_len;  /* Number of received bytes for header */
           };

       The msg_hdr field is a msghdr structure, as described in recvmsg(2).  The
       msg_len field is the number of bytes returned for the message in the entry.
       This field has the same value as the return value of a single recvmsg(2) on
       the header.

       The flags argument contains flags ORed together.  The flags are the same as
       documented for recvmsg(2), with the following addition:

       MSG_WAITFORONE
              Turns on MSG_DONTWAIT after the first message has been received.

       The timeout argument points to a struct timespec (see clock_gettime(2))
       defining a timeout (seconds plus nanoseconds) for the receive operation.
       (This interval will be rounded up to the system clock granularity, and
       kernel scheduling delays mean that the blocking interval may overrun by a
       small amount.)  If timeout is NULL then the operation blocks indefinitely.

       A blocking recvmmsg() call blocks until vlen messages have been received or
       until the timeout expires.  A nonblocking call reads as many messages as
       are available (up to the limit specified by vlen) and returns immediately.

       On return from recvmmsg(), successive elements of msgvec are updated to
       contain information about each received message: msg_len contains the size
       of the received message; the subfields of msg_hdr are updated as described
       in recvmsg(2).  The return value of the call indicates the number of
       elements of msgvec that have been updated.

RETURN VALUE top

       On success, recvmmsg() returns the number of messages received in msgvec;
       on error, -1 is returned, and errno is set to indicate the error.

ERRORS top

       Errors are as for recvmsg(2).  In addition, the following error can occur:

       EINVAL timeout is invalid.

VERSIONS top

       The recvmmsg() system call was added in Linux 2.6.32.  Support in glibc was
       added in version 2.12.

CONFORMING TO top

       recvmmsg() is Linux-specific.

SEE ALSO top

       clock_gettime(2), recvmsg(2), sendmmsg(2), sendmsg(2), socket(2), socket(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-02                         RECVMMSG(2)


regex(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

REGEX(3)                     Linux Programmer's Manual                    REGEX(3)

NAME top

       regcomp, regexec, regerror, regfree - POSIX regex functions

SYNOPSIS top

       #include <sys/types.h>
       #include <regex.h>

       int regcomp(regex_t *preg, const char *regex, int cflags);

       int regexec(const regex_t *preg, const char *string, size_t nmatch,
                   regmatch_t pmatch[], int eflags);

       size_t regerror(int errcode, const regex_t *preg, char *errbuf,
                       size_t errbuf_size);

       void regfree(regex_t *preg);

DESCRIPTION top

POSIX Regex Compiling

       regcomp() is used to compile a regular expression into a form that is
       suitable for subsequent regexec() searches.

       regcomp() is supplied with preg, a pointer to a pattern buffer storage
       area; regex, a pointer to the null-terminated string and cflags, flags used
       to determine the type of compilation.

       All regular expression searching must be done via a compiled pattern
       buffer, thus regexec() must always be supplied with the address of a
       regcomp() initialized pattern buffer.

       cflags may be the bitwise-or of one or more of the following:

       REG_EXTENDED
              Use POSIX Extended Regular Expression syntax when interpreting
              regex.  If not set, POSIX Basic Regular Expression syntax is used.

       REG_ICASE
              Do not differentiate case.  Subsequent regexec() searches using this
              pattern buffer will be case insensitive.

       REG_NOSUB
              Support for substring addressing of matches is not required.  The
              nmatch and pmatch arguments to regexec() are ignored if the pattern
              buffer supplied was compiled with this flag set.

       REG_NEWLINE
              Match-any-character operators don't match a newline.

              A nonmatching list ([^...])  not containing a newline does not match
              a newline.

              Match-beginning-of-line operator (^) matches the empty string
              immediately after a newline, regardless of whether eflags, the
              execution flags of regexec(), contains REG_NOTBOL.

              Match-end-of-line operator ($) matches the empty string immediately
              before a newline, regardless of whether eflags contains REG_NOTEOL.

POSIX Regex Matching

       regexec() is used to match a null-terminated string against the precompiled
       pattern buffer, preg.  nmatch and pmatch are used to provide information
       regarding the location of any matches.  eflags may be the bitwise-or of one
       or both of REG_NOTBOL and REG_NOTEOL which cause changes in matching
       behavior described below.

       REG_NOTBOL
              The match-beginning-of-line operator always fails to match (but see
              the compilation flag REG_NEWLINE above) This flag may be used when
              different portions of a string are passed to regexec() and the
              beginning of the string should not be interpreted as the beginning
              of the line.

       REG_NOTEOL
              The match-end-of-line operator always fails to match (but see the
              compilation flag REG_NEWLINE above)

Byte Offsets

       Unless REG_NOSUB was set for the compilation of the pattern buffer, it is
       possible to obtain substring match addressing information.  pmatch must be
       dimensioned to have at least nmatch elements.  These are filled in by
       regexec() with substring match addresses.  Any unused structure elements
       will contain the value -1.

       The regmatch_t structure which is the type of pmatch is defined in
       <regex.h>.

           typedef struct {
               regoff_t rm_so;
               regoff_t rm_eo;
           } regmatch_t;

       Each rm_so element that is not -1 indicates the start offset of the next
       largest substring match within the string.  The relative rm_eo element
       indicates the end offset of the match, which is the offset of the first
       character after the matching text.

Posix Error Reporting

       regerror() is used to turn the error codes that can be returned by both
       regcomp() and regexec() into error message strings.

       regerror() is passed the error code, errcode, the pattern buffer, preg, a
       pointer to a character string buffer, errbuf, and the size of the string
       buffer, errbuf_size.  It returns the size of the errbuf required to contain
       the null-terminated error message string.  If both errbuf and errbuf_size
       are nonzero, errbuf is filled in with the first errbuf_size - 1 characters
       of the error message and a terminating null byte ('\0').

POSIX Pattern Buffer Freeing

       Supplying regfree() with a precompiled pattern buffer, preg will free the
       memory allocated to the pattern buffer by the compiling process, regcomp().

RETURN VALUE          top
       regcomp() returns zero for a successful compilation or an error code for
       failure.

       regexec() returns zero for a successful match or REG_NOMATCH for failure.

ERRORS          top
       The following errors can be returned by regcomp():

       REG_BADBR
              Invalid use of back reference operator.

       REG_BADPAT
              Invalid use of pattern operators such as group or list.

       REG_BADRPT
              Invalid use of repetition operators such as using '*' as the first
              character.

       REG_EBRACE
              Un-matched brace interval operators.

       REG_EBRACK
              Un-matched bracket list operators.

       REG_ECOLLATE
              Invalid collating element.

       REG_ECTYPE
              Unknown character class name.

       REG_EEND
              Non specific error.  This is not defined by POSIX.2.

       REG_EESCAPE
              Trailing backslash.

       REG_EPAREN
              Un-matched parenthesis group operators.

       REG_ERANGE
              Invalid use of the range operator, e.g., the ending point of the
              range occurs prior to the starting point.

       REG_ESIZE
              Compiled regular expression requires a pattern buffer larger than
              64Kb.  This is not defined by POSIX.2.

       REG_ESPACE
              The regex routines ran out of memory.

       REG_ESUBREG
              Invalid back reference to a subexpression.

CONFORMING TO          top
       POSIX.1-2001.

SEE ALSO          top
       grep(1), regex(7)
       The glibc manual section, Regular Expression Matching

COLOPHON          top
       This page is part of release 3.45 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/.

GNU                                 2012-06-11                            REGEX(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


regex(7) - Linux manual page

NAME | DESCRIPTION | BUGS | AUTHOR | SEE ALSO | COLOPHON The Linux Programming Interface

REGEX(7)                     Linux Programmer's Manual                    REGEX(7)

NAME top

       regex - POSIX.2 regular expressions

DESCRIPTION top

       Regular expressions ("RE"s), as defined in POSIX.2, come in two forms:
       modern REs (roughly those of egrep; POSIX.2 calls these "extended" REs) and
       obsolete REs (roughly those of ed(1); POSIX.2 "basic" REs).  Obsolete REs
       mostly exist for backward compatibility in some old programs; they will be
       discussed at the end.  POSIX.2 leaves some aspects of RE syntax and
       semantics open; "(!)" marks decisions on these aspects that may not be
       fully portable to other POSIX.2 implementations.

       A (modern) RE is one(!) or more nonempty(!) branches, separated by '|'.  It
       matches anything that matches one of the branches.

       A branch is one(!) or more pieces, concatenated.  It matches a match for
       the first, followed by a match for the second, etc.

       A piece is an atom possibly followed by a single(!) '*', '+', '?', or
       bound.  An atom followed by '*' matches a sequence of 0 or more matches of
       the atom.  An atom followed by '+' matches a sequence of 1 or more matches
       of the atom.  An atom followed by '?' matches a sequence of 0 or 1 matches
       of the atom.

       A bound is '{' followed by an unsigned decimal integer, possibly followed
       by ',' possibly followed by another unsigned decimal integer, always
       followed by '}'.  The integers must lie between 0 and RE_DUP_MAX (255(!))
       inclusive, and if there are two of them, the first may not exceed the
       second.  An atom followed by a bound containing one integer i and no comma
       matches a sequence of exactly i matches of the atom.  An atom followed by a
       bound containing one integer i and a comma matches a sequence of i or more
       matches of the atom.  An atom followed by a bound containing two integers i
       and j matches a sequence of i through j (inclusive) matches of the atom.

       An atom is a regular expression enclosed in "()" (matching a match for the
       regular expression), an empty set of "()" (matching the null string)(!), a
       bracket expression (see below), '.' (matching any single character), '^'
       (matching the null string at the beginning of a line), '$' (matching the
       null string at the end of a line), a '\' followed by one of the characters
       "^.[$()|*+?{\" (matching that character taken as an ordinary character), a
       '\' followed by any other character(!)  (matching that character taken as
       an ordinary character, as if the '\' had not been present(!)), or a single
       character with no other significance (matching that character).  A '{'
       followed by a character other than a digit is an ordinary character, not
       the beginning of a bound(!).  It is illegal to end an RE with '\'.

       A bracket expression is a list of characters enclosed in "[]".  It normally
       matches any single character from the list (but see below).  If the list
       begins with '^', it matches any single character (but see below) not from
       the rest of the list.  If two characters in the list are separated by '-',
       this is shorthand for the full range of characters between those two
       (inclusive) in the collating sequence, for example, "[0-9]" in ASCII
       matches any decimal digit.  It is illegal(!) for two ranges to share an
       endpoint, for example, "a-c-e".  Ranges are very collating-sequence-
       dependent, and portable programs should avoid relying on them.

       To include a literal ']' in the list, make it the first character
       (following a possible '^').  To include a literal '-', make it the first or
       last character, or the second endpoint of a range.  To use a literal '-' as
       the first endpoint of a range, enclose it in "[." and ".]"  to make it a
       collating element (see below).  With the exception of these and some
       combinations using '[' (see next paragraphs), all other special characters,
       including '\', lose their special significance within a bracket expression.

       Within a bracket expression, a collating element (a character, a
       multicharacter sequence that collates as if it were a single character, or
       a collating-sequence name for either) enclosed in "[." and ".]" stands for
       the sequence of characters of that collating element.  The sequence is a
       single element of the bracket expression's list.  A bracket expression
       containing a multicharacter collating element can thus match more than one
       character, for example, if the collating sequence includes a "ch" collating
       element, then the RE "[[.ch.]]*c" matches the first five characters of
       "chchcc".

       Within a bracket expression, a collating element enclosed in "[=" and "=]"
       is an equivalence class, standing for the sequences of characters of all
       collating elements equivalent to that one, including itself.  (If there are
       no other equivalent collating elements, the treatment is as if the
       enclosing delimiters were "[." and ".]".)  For example, if o and o^ are the
       members of an equivalence class, then "[[=o=]]", "[[=o^=]]", and "[oo^]" are
       all synonymous.  An equivalence class may not(!) be an endpoint of a range.

       Within a bracket expression, the name of a character class enclosed in "[:"
       and ":]" stands for the list of all characters belonging to that class.
       Standard character class names are:

              alnum       digit       punct
              alpha       graph       space
              blank       lower       upper
              cntrl       print       xdigit

       These stand for the character classes defined in wctype(3).  A locale may
       provide others.  A character class may not be used as an endpoint of a
       range.

       In the event that an RE could match more than one substring of a given
       string, the RE matches the one starting earliest in the string.  If the RE
       could match more than one substring starting at that point, it matches the
       longest.  Subexpressions also match the longest possible substrings,
       subject to the constraint that the whole match be as long as possible, with
       subexpressions starting earlier in the RE taking priority over ones
       starting later.  Note that higher-level subexpressions thus take priority
       over their lower-level component subexpressions.

       Match lengths are measured in characters, not collating elements.  A null
       string is considered longer than no match at all.  For example, "bb*"
       matches the three middle characters of "abbbc",
       "(wee|week)(knights|nights)" matches all ten characters of "weeknights",
       when "(.*).*" is matched against "abc" the parenthesized subexpression
       matches all three characters, and when "(a*)*" is matched against "bc" both
       the whole RE and the parenthesized subexpression match the null string.

       If case-independent matching is specified, the effect is much as if all
       case distinctions had vanished from the alphabet.  When an alphabetic that
       exists in multiple cases appears as an ordinary character outside a bracket
       expression, it is effectively transformed into a bracket expression
       containing both cases, for example, 'x' becomes "[xX]".  When it appears
       inside a bracket expression, all case counterparts of it are added to the
       bracket expression, so that, for example, "[x]" becomes "[xX]" and "[^x]"
       becomes "[^xX]".

       No particular limit is imposed on the length of REs(!).  Programs intended
       to be portable should not employ REs longer than 256 bytes, as an
       implementation can refuse to accept such REs and remain POSIX-compliant.

       Obsolete ("basic") regular expressions differ in several respects.  '|',
       '+', and '?' are ordinary characters and there is no equivalent for their
       functionality.  The delimiters for bounds are "\{" and "\}", with '{' and
       '}' by themselves ordinary characters.  The parentheses for nested
       subexpressions are "\(" and "\)", with '(' and ')' by themselves ordinary
       characters.  '^' is an ordinary character except at the beginning of the RE
       or(!) the beginning of a parenthesized subexpression, '$' is an ordinary
       character except at the end of the RE or(!) the end of a parenthesized
       subexpression, and '*' is an ordinary character if it appears at the
       beginning of the RE or the beginning of a parenthesized subexpression
       (after a possible leading '^').

       Finally, there is one new type of atom, a back reference: '\' followed by a
       nonzero decimal digit d matches the same sequence of characters matched by
       the dth parenthesized subexpression (numbering subexpressions by the
       positions of their opening parentheses, left to right), so that, for
       example, "\([bc]\)\1" matches "bb" or "cc" but not "bc".

BUGS top

       Having two kinds of REs is a botch.

       The current POSIX.2 spec says that ')' is an ordinary character in the
       absence of an unmatched '('; this was an unintentional result of a wording
       error, and change is likely.  Avoid relying on it.

       Back references are a dreadful botch, posing major problems for efficient
       implementations.  They are also somewhat vaguely defined (does
       "a\(\(b\)*\2\)*d" match "abbbd"?).  Avoid using them.

       POSIX.2's specification of case-independent matching is vague.  The "one
       case implies all cases" definition given above is current consensus among
       implementors as to the right interpretation.

AUTHOR top

       This page was taken from Henry Spencer's regex package.

SEE ALSO top

       grep(1), regex(3)

       POSIX.2, section 2.8 (Regular Expression Notation).

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-01-12                            REGEX(7)


remap_file_pages(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

REMAP_FILE_PAGES(2)          Linux Programmer's Manual         REMAP_FILE_PAGES(2)

NAME top

       remap_file_pages - create a nonlinear file mapping

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <sys/mman.h>

       int remap_file_pages(void *addr, size_t size, int prot,
                            ssize_t pgoff, int flags);

DESCRIPTION top

       The remap_file_pages() system call is used to create a nonlinear mapping,
       that is, a mapping in which the pages of the file are mapped into a
       nonsequential order in memory.  The advantage of using remap_file_pages()
       over using repeated calls to mmap(2) is that the former approach does not
       require the kernel to create additional VMA (Virtual Memory Area) data
       structures.

       To create a nonlinear mapping we perform the following steps:

       1. Use mmap(2) to create a mapping (which is initially linear).  This
          mapping must be created with the MAP_SHARED flag.

       2. Use one or more calls to remap_file_pages() to rearrange the
          correspondence between the pages of the mapping and the pages of the
          file.  It is possible to map the same page of a file into multiple
          locations within the mapped region.

       The pgoff and size arguments specify the region of the file that is to be
       relocated within the mapping: pgoff is a file offset in units of the system
       page size; size is the length of the region in bytes.

       The addr argument serves two purposes.  First, it identifies the mapping
       whose pages we want to rearrange.  Thus, addr must be an address that falls
       within a region previously mapped by a call to mmap(2).  Second, addr
       specifies the address at which the file pages identified by pgoff and size
       will be placed.

       The values specified in addr and size should be multiples of the system
       page size.  If they are not, then the kernel rounds both values down to the
       nearest multiple of the page size.

       The prot argument must be specified as 0.

       The flags argument has the same meaning as for mmap(2), but all flags other
       than MAP_NONBLOCK are ignored.

RETURN VALUE top

       On success, remap_file_pages() returns 0.  On error, -1 is returned, and
       errno is set appropriately.

ERRORS top

       EINVAL addr does not refer to a valid mapping created with the MAP_SHARED
              flag.

       EINVAL addr, size, prot, or pgoff is invalid.

VERSIONS top

       The remap_file_pages() system call appeared in Linux 2.5.46; glibc support
       was added in version 2.3.3.

CONFORMING TO top

       The remap_file_pages() system call is Linux-specific.

SEE ALSO top

       getpagesize(2), mmap(2), mmap2(2), mprotect(2), mremap(2), msync(2)

COLOPHON top

       This page is part of release 3.45 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-22                 REMAP_FILE_PAGES(2)


remove(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

REMOVE(3)                    Linux Programmer's Manual                   REMOVE(3)

NAME top

       remove - remove a file or directory

SYNOPSIS top

       #include <stdio.h>

       int remove(const char *pathname);

DESCRIPTION top

       remove() deletes a name from the file system.  It calls unlink(2) for
       files, and rmdir(2) for directories.

       If the removed name was the last link to a file and no processes have the
       file open, the file is deleted and the space it was using is made available
       for reuse.

       If the name was the last link to a file, but any processes still have the
       file open, the file will remain in existence until the last file descriptor
       referring to it is closed.

       If the name referred to a symbolic link, the link is removed.

       If the name referred to a socket, FIFO, or device, the name is removed, but
       processes which have the object open may continue to use it.

RETURN VALUE top

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

ERRORS top

       The errors that occur are those for unlink(2) and rmdir(2).

CONFORMING TO top

       C89, C99, 4.3BSD, POSIX.1-2001.

NOTES top

       Under libc4 and libc5, remove() was an alias for unlink(2) (and hence would
       not remove directories).

BUGS top

       Infelicities in the protocol underlying NFS can cause the unexpected
       disappearance of files which are still being used.

SEE ALSO top

       rm(1), unlink(1), link(2), mknod(2), open(2), rename(2), rmdir(2),
       unlink(2), mkfifo(3), symlink(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-12-03                           REMOVE(3)


remquo(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

REMQUO(3)                    Linux Programmer's Manual                   REMQUO(3)

NAME top

       remquo, remquof, remquol - remainder and part of quotient

SYNOPSIS top

       #include <math.h>

       double remquo(double x, double y, int *quo);
       float remquof(float x, float y, int *quo);
       long double remquol(long double x, long double y, int *quo);

       Link with -lm.

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

       remquo(), remquof(), remquol():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions compute the remainder and part of the quotient upon
       division of x by y.  A few bits of the quotient are stored via the quo
       pointer.  The remainder is returned as the function result.

       The value of the remainder is the same as that computed by the remainder(3)
       function.

       The value stored via the quo pointer has the sign of x / y and agrees with
       the quotient in at least the low order 3 bits.

       For example, remquo(29.0, 3.0) returns -1.0 and might store 2.  Note that
       the actual quotient might not fit in an integer.

RETURN VALUE top

       On success, these functions return the same value as the analogous
       functions described in remainder(3).

       If x or y is a NaN, a NaN is returned.

       If x is an infinity, and y is not a NaN, a domain error occurs, and a NaN
       is returned.

       If y is zero, and x is not a NaN, a domain error occurs, and a NaN is
       returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity or y is 0, and the other argument is not a
       NaN
              An invalid floating-point exception (FE_INVALID) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       fmod(3), logb(3), remainder(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           REMQUO(3)


rename(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RENAME(2)                    Linux Programmer's Manual                   RENAME(2)

NAME top

       rename - change the name or location of a file

SYNOPSIS top

       #include <stdio.h>

       int rename(const char *oldpath, const char *newpath);

DESCRIPTION top

       rename() renames a file, moving it between directories if required.  Any
       other hard links to the file (as created using link(2)) are unaffected.
       Open file descriptors for oldpath are also unaffected.

       If newpath already exists it will be atomically replaced (subject to a few
       conditions; see ERRORS below), so that there is no point at which another
       process attempting to access newpath will find it missing.

       If oldpath and newpath are existing hard links referring to the same file,
       then rename() does nothing, and returns a success status.

       If newpath exists but the operation fails for some reason rename()
       guarantees to leave an instance of newpath in place.

       oldpath can specify a directory.  In this case, newpath must either not
       exist, or it must specify an empty directory.

       However, when overwriting there will probably be a window in which both
       oldpath and newpath refer to the file being renamed.

       If oldpath refers to a symbolic link the link is renamed; if newpath refers
       to a symbolic link the link will be overwritten.

RETURN VALUE top

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

ERRORS top

       EACCES Write permission is denied for the directory containing oldpath or
              newpath, or, search permission is denied for one of the directories
              in the path prefix of oldpath or newpath, or oldpath is a directory
              and does not allow write permission (needed to update the ..
              entry).  (See also path_resolution(7).)

       EBUSY  The rename fails because oldpath or newpath is a directory that is
              in use by some process (perhaps as current working directory, or as
              root directory, or because it was open for reading) or is in use by
              the system (for example as mount point), while the system considers
              this an error.  (Note that there is no requirement to return EBUSY
              in such cases--there is nothing wrong with doing the rename anyway--
              but it is allowed to return EBUSY if the system cannot otherwise
              handle such situations.)

       EFAULT oldpath or newpath points outside your accessible address space.

       EINVAL The new pathname contained a path prefix of the old, or, more
              generally, an attempt was made to make a directory a subdirectory of
              itself.

       EISDIR newpath is an existing directory, but oldpath is not a directory.

       ELOOP  Too many symbolic links were encountered in resolving oldpath or
              newpath.

       EMLINK oldpath already has the maximum number of links to it, or it was a
              directory and the directory containing newpath has the maximum
              number of links.

       ENAMETOOLONG
              oldpath or newpath was too long.

       ENOENT The link named by oldpath does not exist; or, a directory component
              in newpath does not exist; or, oldpath or newpath is an empty
              string.

       ENOMEM Insufficient kernel memory was available.

       ENOSPC The device containing the file has no room for the new directory
              entry.

       ENOTDIR
              A component used as a directory in oldpath or newpath is not, in
              fact, a directory.  Or, oldpath is a directory, and newpath exists
              but is not a directory.

       ENOTEMPTY or EEXIST
              newpath is a nonempty directory, that is, contains entries other
              than "." and "..".

       EPERM or EACCES
              The directory containing oldpath has the sticky bit (S_ISVTX) set
              and the process's effective user ID is neither the user ID of the
              file to be deleted nor that of the directory containing it, and the
              process is not privileged (Linux: does not have the CAP_FOWNER
              capability); or newpath is an existing file and the directory
              containing it has the sticky bit set and the process's effective
              user ID is neither the user ID of the file to be replaced nor that
              of the directory containing it, and the process is not privileged
              (Linux: does not have the CAP_FOWNER capability); or the file system
              containing pathname does not support renaming of the type requested.

       EROFS  The file is on a read-only file system.

       EXDEV  oldpath and newpath are not on the same mounted file system.  (Linux
              permits a file system to be mounted at multiple points, but rename()
              does not work across different mount points, even if the same file
              system is mounted on both.)

CONFORMING TO top

       4.3BSD, C89, C99, POSIX.1-2001.

BUGS top

       On NFS file systems, you can not assume that if the operation failed the
       file was not renamed.  If the server does the rename operation and then
       crashes, the retransmitted RPC which will be processed when the server is
       up again causes a failure.  The application is expected to deal with this.
       See link(2) for a similar problem.

SEE ALSO top

       mv(1), chmod(2), link(2), renameat(2), symlink(2), unlink(2),
       path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-03-30                           RENAME(2)


renameat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RENAMEAT(2)                  Linux Programmer's Manual                 RENAMEAT(2)

NAME top

       renameat - rename a file relative to directory file descriptors

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <stdio.h>

       int renameat(int olddirfd, const char *oldpath,
                    int newdirfd, const char *newpath);

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

       renameat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The renameat() system call operates in exactly the same way as rename(2),
       except for the differences described in this manual page.

       If the pathname given in oldpath is relative, then it is interpreted
       relative to the directory referred to by the file descriptor olddirfd
       (rather than relative to the current working directory of the calling
       process, as is done by rename(2) for a relative pathname).

       If oldpath is relative and olddirfd is the special value AT_FDCWD, then
       oldpath is interpreted relative to the current working directory of the
       calling process (like rename(2)).

       If oldpath is absolute, then olddirfd is ignored.

       The interpretation of newpath is as for oldpath, except that a relative
       pathname is interpreted relative to the directory referred to by the file
       descriptor newdirfd.

RETURN VALUE top

       On success, renameat() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for rename(2) can also occur for renameat().
       The following additional errors can occur for renameat():

       EBADF  olddirfd or newdirfd is not a valid file descriptor.

       ENOTDIR
              oldpath is relative and olddirfd is a file descriptor referring to a
              file other than a directory; or similar for newpath and newdirfd

VERSIONS top

       renameat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for renameat().

SEE ALSO top

       openat(2), rename(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                         RENAMEAT(2)


request_key(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | LINKING | SEE ALSO | COLOPHON The Linux Programming Interface

REQUEST_KEY(2)              Linux Key Management Calls              REQUEST_KEY(2)

NAME top

       request_key - request a key from the kernel's key management facility

SYNOPSIS top

       #include <keyutils.h>

       key_serial_t request_key(const char *type, const char *description,
                                const char *callout_info,
                                key_serial_t keyring);

DESCRIPTION top

       request_key() asks the kernel to find a key of the given type that matches
       the specified description and, if successful, to attach it to the nominated
       keyring and to return its serial number.

       request_key() first recursively searches all the keyrings attached to the
       calling process in the order thread-specific keyring, process-specific
       keyring and then session keyring for a matching key.

       If request_key() is called from a program invoked by request_key() on
       behalf of some other process to generate a key, then the keyrings of that
       other process will be searched next, using that other process's UID, GID,
       groups and security context to control access.

       The keys in each keyring searched are checked for a match before any child
       keyrings are recursed into.  Only keys that are searchable for the caller
       may be found, and only searchable keyrings may be searched.

       If the key is not found then, if callout_info is set, this function will
       attempt to look further afield.  In such a case, the callout_info is passed
       to a user-space service such as /sbin/request-key to generate the key.

       If that is unsuccessful also, then an error will be returned, and a
       temporary negative key will be installed in the nominated keyring.  This
       will expire after a few seconds, but will cause subsequent calls to
       request_key() to fail until it does.

       The keyring serial number may be that of a valid keyring to which the
       caller has write permission, or it may be a special keyring ID:

       KEY_SPEC_THREAD_KEYRING
              This specifies the caller's thread-specific keyring.

       KEY_SPEC_PROCESS_KEYRING
              This specifies the caller's process-specific keyring.

       KEY_SPEC_SESSION_KEYRING
              This specifies the caller's session-specific keyring.

       KEY_SPEC_USER_KEYRING
              This specifies the caller's UID-specific keyring.

       KEY_SPEC_USER_SESSION_KEYRING
              This specifies the caller's UID-session keyring.

       If a key is created, no matter whether it's a valid key or a negative key,
       it will displace any other key of the same type and description from the
       destination keyring.

RETURN VALUE top

       On success request_key() returns the serial number of the key it found.  On
       error, the value -1 will be returned and errno will have been set to an
       appropriate error.

ERRORS top

       EACCES The keyring wasn't available for modification by the user.

       EINTR  The request was interrupted by a signal.

       EDQUOT The key quota for this user would be exceeded by creating this key
              or linking it to the keyring.

       EKEYEXPIRED
              An expired key was found, but no replacement could be obtained.

       EKEYREJECTED
              The attempt to generate a new key was rejected.

       EKEYREVOKED
              A revoked key was found, but no replacement could be obtained.

       ENOMEM Insufficient memory to create a key.

       ENOKEY No matching key was found.

LINKING top

       Although this is a Linux system call, it is not present in libc but can be
       found rather in libkeyutils.  When linking, -lkeyutils should be specified
       to the linker.

SEE ALSO top

       keyctl(1), add_key(2), keyctl(2), request-key(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-25                      REQUEST_KEY(2)


resolv.conf(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

RESOLV.CONF(5)               Linux Programmer's Manual              RESOLV.CONF(5)

NAME top

       resolv.conf - resolver configuration file

SYNOPSIS top

       /etc/resolv.conf

DESCRIPTION top

       The resolver is a set of routines in the C library that provide access to
       the Internet Domain Name System (DNS).  The resolver configuration file
       contains information that is read by the resolver routines the first time
       they are invoked by a process.  The file is designed to be human readable
       and contains a list of keywords with values that provide various types of
       resolver information.

       If this file does not exist, only the name server on the local machine will
       be queried; the domain name is determined from the hostname and the domain
       search path is constructed from the domain name.

       The different configuration options are:

       nameserver Name server IP address
              Internet address of a name server that the resolver should query,
              either an IPv4 address (in dot notation), or an IPv6 address in
              colon (and possibly dot) notation as per RFC 2373.  Up to MAXNS
              (currently 3, see <resolv.h>) name servers may be listed, one per
              keyword.  If there are multiple servers, the resolver library
              queries them in the order listed.  If no nameserver entries are
              present, the default is to use the name server on the local machine.
              (The algorithm used is to try a name server, and if the query times
              out, try the next, until out of name servers, then repeat trying all
              the name servers until a maximum number of retries are made.)

       domain Local domain name.
              Most queries for names within this domain can use short names
              relative to the local domain.  If no domain entry is present, the
              domain is determined from the local hostname returned by
              gethostname(2); the domain part is taken to be everything after the
              first '.'.  Finally, if the hostname does not contain a domain part,
              the root domain is assumed.

       search Search list for host-name lookup.
              The search list is normally determined from the local domain name;
              by default, it contains only the local domain name.  This may be
              changed by listing the desired domain search path following the
              search keyword with spaces or tabs separating the names.  Resolver
              queries having fewer than ndots dots (default is 1) in them will be
              attempted using each component of the search path in turn until a
              match is found.  For environments with multiple subdomains please
              read options ndots:n below to avoid man-in-the-middle attacks and
              unnecessary traffic for the root-dns-servers.  Note that this
              process may be slow and will generate a lot of network traffic if
              the servers for the listed domains are not local, and that queries
              will time out if no server is available for one of the domains.

              The search list is currently limited to six domains with a total of
              256 characters.

       sortlist
              This option allows addresses returned by gethostbyname(3) to be
              sorted.  A sortlist is specified by IP-address-netmask pairs.  The
              netmask is optional and defaults to the natural netmask of the net.
              The IP address and optional network pairs are separated by slashes.
              Up to 10 pairs may be specified.  Here is an example:

                  sortlist 130.155.160.0/255.255.240.0 130.155.0.0

       options
              Options allows certain internal resolver variables to be modified.
              The syntax is

                     options option ...

              where option is one of the following:

              debug  sets RES_DEBUG in _res.options.

              ndots:[22mn[0m
                     sets a threshold for the number of dots which must appear in
                     a name given to res_query(3) (see resolver(3)) before an
                     initial absolute query will be made.  The default for n is 1,
                     meaning that if there are any dots in a name, the name will
                     be tried first as an absolute name before any search list
                     elements are appended to it.  The value for this option is
                     silently capped to 15.

              timeout:[22mn[0m
                     sets the amount of time the resolver will wait for a response
                     from a remote name server before retrying the query via a
                     different name server.  Measured in seconds, the default is
                     RES_TIMEOUT (currently 5, see <resolv.h>).  The value for
                     this option is silently capped to 30.

              attempts:[22mn[0m
                     sets the number of times the resolver will send a query to
                     its name servers before giving up and returning an error to
                     the calling application.  The default is RES_DFLRETRY
                     (currently 2, see <resolv.h>).  The value for this option is
                     silently capped to 5.

              rotate sets RES_ROTATE in _res.options, which causes round robin
                     selection of nameservers from among those listed.  This has
                     the effect of spreading the query load among all listed
                     servers, rather than having all clients try the first listed
                     server first every time.

              no-check-names
                     sets RES_NOCHECKNAME in _res.options, which disables the
                     modern BIND checking of incoming hostnames and mail names for
                     invalid characters such as underscore (_), non-ASCII, or
                     control characters.

              inet6  sets RES_USE_INET6 in _res.options.  This has the effect of
                     trying a AAAA query before an A query inside the
                     gethostbyname(3) function, and of mapping IPv4 responses in
                     IPv6 "tunneled form" if no AAAA records are found but an A
                     record set exists.

              ip6-bytestring (since glibc 2.3.4)
                     sets RES_USE_BSTRING in _res.options.  This causes reverse
                     IPv6 lookups to be made using the bit-label format described
                     in RFC 2673; if this option is not set, then nibble format is
                     used.

              ip6-dotint/no-ip6-dotint (since glibc 2.3.4)
                     Clear/set RES_NOIP6DOTINT in _res.options.  When this option
                     is clear (ip6-dotint), reverse IPv6 lookups are made in the
                     (deprecated) ip6.int zone; when this option is set (no-
                     ip6-dotint), reverse IPv6 lookups are made in the ip6.arpa
                     zone by default.  This option is set by default.

              edns0 (since glibc 2.6)
                     sets RES_USE_EDNSO in _res.options.  This enables support for
                     the DNS extensions described in RFC 2671.

              single-request (since glibc 2.10)
                     sets RES_SNGLKUP in _res.options.  By default, glibc performs
                     IPv4 and IPv6 lookups in parallel since version 2.9.  Some
                     appliance DNS servers cannot handle these queries properly
                     and make the requests time out.  This option disables the
                     behavior and makes glibc perform the IPv6 and IPv4 requests
                     sequentially (at the cost of some slowdown of the resolving
                     process).

       The domain and search keywords are mutually exclusive.  If more than one
       instance of these keywords is present, the last instance wins.

       The search keyword of a system's resolv.conf file can be overridden on a
       per-process basis by setting the environment variable LOCALDOMAIN to a
       space-separated list of search domains.

       The options keyword of a system's resolv.conf file can be amended on a per-
       process basis by setting the environment variable RES_OPTIONS to a space-
       separated list of resolver options as explained above under options.

       The keyword and value must appear on a single line, and the keyword (e.g.,
       nameserver) must start the line.  The value follows the keyword, separated
       by white space.

       Lines that contain a semicolon (;) or hash character (#) in the first
       column are treated as comments.

FILES top

       /etc/resolv.conf, <resolv.h>

SEE ALSO top

       gethostbyname(3), resolver(3), hostname(7), named(8)
       Name Server Operations Guide for BIND

COLOPHON top

       This page is part of release 3.45 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/.

4th Berkeley Distribution           2012-11-11                      RESOLV.CONF(5)


rewinddir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

REWINDDIR(3)                 Linux Programmer's Manual                REWINDDIR(3)

NAME top

       rewinddir - reset directory stream

SYNOPSIS top

       #include <sys/types.h>

       #include <dirent.h>

       void rewinddir(DIR *dirp);

DESCRIPTION top

       The rewinddir() function resets the position of the directory stream dirp
       to the beginning of the directory.

RETURN VALUE top

       The rewinddir() function returns no value.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

SEE ALSO top

       closedir(3), opendir(3), readdir(3), scandir(3), seekdir(3), telldir(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    1995-06-11                        REWINDDIR(3)


rexec(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

REXEC(3)                     Linux Programmer's Manual                    REXEC(3)

NAME top

       rexec, rexec_af - return stream to a remote command

SYNOPSIS top

       #define _BSD_SOURCE             /* See feature_test_macros(7) */
       #include <netdb.h>

       int rexec(char **ahost, int inport, char *user,
                 char *passwd, char *cmd, int *fd2p);

       int rexec_af(char **ahost, int inport, char *user,
                    char *passwd, char *cmd, int *fd2p,
                    sa_family_t af);

DESCRIPTION top

       This interface is obsoleted by rcmd(3).

       The rexec() function looks up the host *ahost using gethostbyname(3),
       returning -1 if the host does not exist.  Otherwise *ahost is set to the
       standard name of the host.  If a username and password are both specified,
       then these are used to authenticate to the foreign host; otherwise the
       environment and then the user's .netrc file in his home directory are
       searched for appropriate information.  If all this fails, the user is
       prompted for the information.

       The port inport specifies which well-known DARPA Internet port to use for
       the connection; the call getservbyname("exec", "tcp") (see getservent(3))
       will return a pointer to a structure that contains the necessary port.  The
       protocol for connection is described in detail in rexecd(8).

       If the connection succeeds, a socket in the Internet domain of type
       SOCK_STREAM is returned to the caller, and given to the remote command as
       stdin and stdout.  If fd2p is nonzero, then an auxiliary channel to a
       control process will be setup, and a descriptor for it will be placed in
       *fd2p.  The control process will return diagnostic output from the command
       (unit 2) on this channel, and will also accept bytes on this channel as
       being UNIX signal numbers, to be forwarded to the process group of the
       command.  The diagnostic information returned does not include remote
       authorization failure, as the secondary connection is set up after
       authorization has been verified.  If fd2p is 0, then the stderr (unit 2 of
       the remote command) will be made the same as the stdout and no provision is
       made for sending arbitrary signals to the remote process, although you may
       be able to get its attention by using out-of-band data.

rexec_af()

       The rexec() function works over IPv4 (AF_INET).  By contrast, the
       rexec_af() function provides an extra argument, af, that allows the caller
       to select the protocol.  This argument can be specified as AF_INET,
       AF_INET6, or AF_UNSPEC (to allow the implementation to select the
       protocol).

VERSIONS top

       The rexec_af() function was added to glibc in version 2.2.

CONFORMING TO top

       These functions are not in POSIX.1-2001.  The rexec() function first
       appeared in 4.2BSD, and is present on the BSDs, Solaris, and many other
       systems.  The rexec_af() function is more recent, and less widespread.

BUGS top

       The rexec() function sends the unencrypted password across the network.

       The underlying service is considered a big security hole and therefore not
       enabled on many sites; see rexecd(8) for explanations.

SEE ALSO top

       rcmd(3), rexecd(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-23                            REXEC(3)


re_comp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RE_COMP(3)                   Linux Programmer's Manual                  RE_COMP(3)

NAME top

       re_comp, re_exec - BSD regex functions

SYNOPSIS top

       #define _REGEX_RE_COMP
       #include <sys/types.h>
       #include <regex.h>

       char *re_comp(char *regex);

       int re_exec(char *string);

DESCRIPTION top

       re_comp() is used to compile the null-terminated regular expression pointed
       to by regex.  The compiled pattern occupies a static area, the pattern
       buffer, which is overwritten by subsequent use of re_comp().  If regex is
       NULL, no operation is performed and the pattern buffer's contents are not
       altered.

       re_exec() is used to assess whether the null-terminated string pointed to
       by string matches the previously compiled regex.

RETURN VALUE top

       re_comp() returns NULL on successful compilation of regex otherwise it
       returns a pointer to an appropriate error message.

       re_exec() returns 1 for a successful match, zero for failure.

CONFORMING TO top

       4.3BSD.

NOTES top

       These functions are obsolete; the functions documented in regcomp(3) should
       be used instead.

SEE ALSO top

       regcomp(3), regex(7), GNU regex manual

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1995-07-14                          RE_COMP(3)


rmdir(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RMDIR(2)                     Linux Programmer's Manual                    RMDIR(2)

NAME top

       rmdir - delete a directory

SYNOPSIS top

       #include <unistd.h>

       int rmdir(const char *pathname);

DESCRIPTION top

       rmdir() deletes a directory, which must be empty.

RETURN VALUE top

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

ERRORS top

       EACCES Write access to the directory containing pathname was not allowed,
              or one of the directories in the path prefix of pathname did not
              allow search permission.  (See also path_resolution(7).

       EBUSY  pathname is currently in use by the system or some process that
              prevents its removal.  On Linux this means pathname is currently
              used as a mount point or is the root directory of the calling
              process.

       EFAULT pathname points outside your accessible address space.

       EINVAL pathname has .  as last component.

       ELOOP  Too many symbolic links were encountered in resolving pathname.

       ENAMETOOLONG
              pathname was too long.

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

       ENOMEM Insufficient kernel memory was available.

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

       ENOTEMPTY
              pathname contains entries other than . and .. ; or, pathname has ..
              as its final component.  POSIX.1-2001 also allows EEXIST for this
              condition.

       EPERM  The directory containing pathname has the sticky bit (S_ISVTX) set
              and the process's effective user ID is neither the user ID of the
              file to be deleted nor that of the directory containing it, and the
              process is not privileged (Linux: does not have the CAP_FOWNER
              capability).

       EPERM  The file system containing pathname does not support the removal of
              directories.

       EROFS  pathname refers to a directory on a read-only file system.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

BUGS top

       Infelicities in the protocol underlying NFS can cause the unexpected
       disappearance of directories which are still being used.

SEE ALSO top

       rm(1), rmdir(1), chdir(2), chmod(2), mkdir(2), rename(2), unlink(2),
       unlinkat(2)

COLOPHON top

       This page is part of release 3.45 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-05-08                            RMDIR(2)


round(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ROUND(3)                     Linux Programmer's Manual                    ROUND(3)

NAME top

       round, roundf, roundl - round to nearest integer, away from zero

SYNOPSIS top

       #include <math.h>

       double round(double x);
       float roundf(float x);
       long double roundl(long double x);

       Link with -lm.

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

       round(), roundf(), roundl():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions round x to the nearest integer, but round halfway cases
       away from zero (regardless of the current rounding direction, see fenv(3)),
       instead of to the nearest even integer like rint(3).

       For example, round(0.5) is 1.0, and round(-0.5) is -1.0.

RETURN VALUE top

       These functions return the rounded integer value.

       If x is integral, +0, -0, NaN,  or infinite, x itself is returned.

ERRORS top

       No errors occur.  POSIX.1-2001 documents a range error for overflows, but
       see NOTES.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       POSIX.1-2001 contains text about overflow (which might set errno to ERANGE,
       or raise an FE_OVERFLOW exception).  In practice, the result cannot
       overflow on any current machine, so this error-handling stuff is just
       nonsense.  (More precisely, overflow can happen only when the maximum value
       of the exponent is smaller than the number of mantissa bits.  For the
       IEEE-754 standard 32-bit and 64-bit floating-point numbers the maximum
       value of the exponent is 128 (respectively, 1024), and the number of
       mantissa bits is 24 (respectively, 53).)

       If you want to store the rounded value in an integer type, you probably
       want to use one of the functions described in lround(3) instead.

SEE ALSO top

       ceil(3), floor(3), lround(3), nearbyint(3), rint(3), trunc(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            ROUND(3)


rpc(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

RPC(5)                       Linux Programmer's Manual                      RPC(5)

NAME top

       rpc - RPC program number data base

SYNOPSIS top

       /etc/rpc

DESCRIPTION top

       The rpc file contains user readable names that can be used in place of RPC
       program numbers.  Each line has the following information:

       name of server for the RPC program
       RPC program number
       aliases

       Items are separated by any number of blanks and/or tab characters.  A '#'
       indicates the beginning of a comment; characters from the '#' to the end of
       the line are not interpreted by routines which search the file.

       Here is an example of the /etc/rpc file from the Sun RPC Source
       distribution.
       #
       # rpc 88/08/01 4.0 RPCSRC; from 1.12   88/02/07 SMI
       #
       portmapper          100000    portmap sunrpc
       rstatd              100001    rstat rstat_svc rup perfmeter
       rusersd             100002    rusers
       nfs                 100003    nfsprog
       ypserv              100004    ypprog
       mountd              100005    mount showmount
       ypbind              100007
       walld               100008    rwall shutdown
       yppasswdd           100009    yppasswd
       etherstatd          100010    etherstat
       rquotad             100011    rquotaprog quota rquota
       sprayd              100012    spray
       3270_mapper         100013
       rje_mapper          100014
       selection_svc       100015    selnsvc
       database_svc        100016
       rexd                100017    rex
       alis                100018
       sched               100019
       llockmgr            100020
       nlockmgr            100021
       x25.inr             100022
       statmon             100023
       status              100024
       bootparam           100026
       ypupdated           100028    ypupdate
       keyserv             100029    keyserver
       tfsd                100037
       nsed                100038
       nsemntd             100039

FILES top

       /etc/rpc
              RPC program number data base

SEE ALSO top

       getrpcent(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    1985-09-26                              RPC(5)


rpmatch(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

RPMATCH(3)                   Linux Programmer's Manual                  RPMATCH(3)

NAME top

       rpmatch - determine if the answer to a question is affirmative or negative

SYNOPSIS top

       #include <stdlib.h>

       int rpmatch(const char *response);

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

       rpmatch(): _SVID_SOURCE

DESCRIPTION top

       rpmatch() handles a user response to yes or no questions, with support for
       internationalization.

       response should be a null-terminated string containing a user-supplied
       response, perhaps obtained with fgets(3) or getline(3).

       The user's language preference is taken into account per the environment
       variables LANG, LC_MESSAGES, and LC_ALL, if the program has called
       setlocale(3) to effect their changes.

       Regardless of the locale, responses matching ^[Yy] are always accepted as
       affirmative, and those matching ^[Nn] are always accepted as negative.

RETURN VALUE top

       After examining response, rpmatch() returns 0 for a recognized negative
       response ("no"), 1 for a recognized positive response ("yes"), and -1 when
       the value of response is unrecognized.

ERRORS top

       A return value of -1 may indicate either an invalid input, or some other
       error.  It is incorrect to only test if the return value is nonzero.

       rpmatch() can fail for any of the reasons that regcomp(3) or regexec(3) can
       fail; the cause of the error is not available from errno or anywhere else,
       but indicates a failure of the regex engine (but this case is
       indistinguishable from that of an unrecognized value of response).

CONFORMING TO top

       rpmatch() is not required by any standard, but is available on a few other
       systems.

BUGS top

       The rpmatch() implementation looks at only the first character of response.
       As a consequence, "nyes" returns 0, and "ynever; not in a million years"
       returns 1.  It would be preferable to accept input strings much more
       strictly, for example (using the extended regular expression notation
       described in regex(7)): ^([yY]|yes|YES)$ and ^([nN]|no|NO)$.

EXAMPLE top

       The following program displays the results when rpmatch() is applied to the
       string given in the program's command-line argument.

       #define _SVID_SOURCE
       #include <locale.h>
       #include <stdlib.h>
       #include <string.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           if (argc != 2 || strcmp(argv[1], "--help") == 0) {
               fprintf(stderr, "%s response\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           setlocale(LC_ALL, "");
           printf("rpmatch() returns: %d\n", rpmatch(argv[1]));
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fgets(3), getline(3), nl_langinfo(3), regcomp(3), setlocale(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                          RPMATCH(3)


rtc(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RTC(4)                       Linux Programmer's Manual                      RTC(4)

NAME top

       rtc - real-time clock

SYNOPSIS top

       #include <linux/rtc.h>

       int ioctl(fd, RTC_request, param);

DESCRIPTION top

       This is the interface to drivers for real-time clocks (RTCs).

       Most computers have one or more hardware clocks which record the current
       "wall clock" time.  These are called "Real Time Clocks" (RTCs).  One of
       these usually has battery backup power so that it tracks the time even
       while the computer is turned off.  RTCs often provide alarms and other
       interrupts.

       All i386 PCs, and ACPI-based systems, have an RTC that is compatible with
       the Motorola MC146818 chip on the original PC/AT.  Today such an RTC is
       usually integrated into the mainboard's chipset (south bridge), and uses a
       replaceable coin-sized backup battery.

       Non-PC systems, such as embedded systems built around system-on-chip
       processors, use other implementations.  They usually won't offer the same
       functionality as the RTC from a PC/AT.

RTC vs System Clock

       RTCs should not be confused with the system clock, which is a software
       clock maintained by the kernel and used to implement gettimeofday(2) and
       time(2), as well as setting timestamps on files, etc.  The system clock
       reports seconds and microseconds since a start point, defined to be the
       POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC).  (One common implementation
       counts timer interrupts, once per "jiffy", at a frequency of 100, 250, or
       1000 Hz.)  That is, it is supposed to report wall clock time, which RTCs
       also do.

       A key difference between an RTC and the system clock is that RTCs run even
       when the system is in a low power state (including "off"), and the system
       clock can't.  Until it is initialized, the system clock can only report
       time since system boot ... not since the POSIX Epoch.  So at boot time, and
       after resuming from a system low power state, the system clock will often
       be set to the current wall clock time using an RTC.  Systems without an RTC
       need to set the system clock using another clock, maybe across the network
       or by entering that data manually.

RTC functionality

       RTCs can be read and written with hwclock(8), or directly with the ioctl
       requests listed below.

       Besides tracking the date and time, many RTCs can also generate interrupts

       *  on every clock update (i.e., once per second);

       *  at periodic intervals with a frequency that can be set to any power-of-2
          multiple in the range 2 Hz to 8192 Hz;

       *  on reaching a previously specified alarm time.

       Each of those interrupt sources can be enabled or disabled separately.  On
       many systems, the alarm interrupt can be configured as a system wakeup
       event, which can resume the system from a low power state such as Suspend-
       to-RAM (STR, called S3 in ACPI systems), Hibernation (called S4 in ACPI
       systems), or even "off" (called S5 in ACPI systems).  On some systems, the
       battery backed RTC can't issue interrupts, but another one can.

       The /dev/rtc (or /dev/rtc0, /dev/rtc1, etc.)  device can be opened only
       once (until it is closed) and it is read-only.  On read(2) and select(2)
       the calling process is blocked until the next interrupt from that RTC is
       received.  Following the interrupt, the process can read a long integer, of
       which the least significant byte contains a bit mask encoding the types of
       interrupt that occurred, while the remaining 3 bytes contain the number of
       interrupts since the last read(2).

ioctl(2) interface

       The following ioctl(2) requests are defined on file descriptors connected
       to RTC devices:

       RTC_RD_TIME
              Returns this RTC's time in the following structure:

                  struct rtc_time {
                      int tm_sec;
                      int tm_min;
                      int tm_hour;
                      int tm_mday;
                      int tm_mon;
                      int tm_year;
                      int tm_wday;     /* unused */
                      int tm_yday;     /* unused */
                      int tm_isdst;    /* unused */
                  };

              The fields in this structure have the same meaning and ranges as for
              the tm structure described in gmtime(3).  A pointer to this
              structure should be passed as the third ioctl(2) argument.

       RTC_SET_TIME
              Sets this RTC's time to the time specified by the rtc_time structure
              pointed to by the third ioctl(2) argument.  To set the RTC's time
              the process must be privileged (i.e., have the CAP_SYS_TIME
              capability).

       RTC_ALM_READ, RTC_ALM_SET
              Read and set the alarm time, for RTCs that support alarms.  The
              alarm interrupt must be separately enabled or disabled using the
              RTC_AIE_ON, RTC_AIE_OFF requests.  The third ioctl(2) argument is a
              pointer to an rtc_time structure.  Only the tm_sec, tm_min, and
              tm_hour fields of this structure are used.

       RTC_IRQP_READ, RTC_IRQP_SET
              Read and set the frequency for periodic interrupts, for RTCs that
              support periodic interrupts.  The periodic interrupt must be
              separately enabled or disabled using the RTC_PIE_ON, RTC_PIE_OFF
              requests.  The third ioctl(2) argument is an unsigned long * or an
              unsigned long, respectively.  The value is the frequency in
              interrupts per second.  The set of allowable frequencies is the
              multiples of two in the range 2 to 8192.  Only a privileged process
              (i.e., one having the CAP_SYS_RESOURCE capability) can set
              frequencies above the value specified in /proc/sys/dev/rtc/max-user-
              freq.  (This file contains the value 64 by default.)

       RTC_AIE_ON, RTC_AIE_OFF
              Enable or disable the alarm interrupt, for RTCs that support alarms.
              The third ioctl(2) argument is ignored.

       RTC_UIE_ON, RTC_UIE_OFF
              Enable or disable the interrupt on every clock update, for RTCs that
              support this once-per-second interrupt.  The third ioctl(2) argument
              is ignored.

       RTC_PIE_ON, RTC_PIE_OFF
              Enable or disable the periodic interrupt, for RTCs that support
              these periodic interrupts.  The third ioctl(2) argument is ignored.
              Only a privileged process (i.e., one having the CAP_SYS_RESOURCE
              capability) can enable the periodic interrupt if the frequency is
              currently set above the value specified in /proc/sys/dev/rtc/max-
              user-freq.

       RTC_EPOCH_READ, RTC_EPOCH_SET
              Many RTCs encode the year in an 8-bit register which is either
              interpreted as an 8-bit binary number or as a BCD number.  In both
              cases, the number is interpreted relative to this RTC's Epoch.  The
              RTC's Epoch is initialized to 1900 on most systems but on Alpha and
              MIPS it might also be initialized to 1952, 1980, or 2000, depending
              on the value of an RTC register for the year.  With some RTCs, these
              operations can be used to read or to set the RTC's Epoch,
              respectively.  The third ioctl(2) argument is a unsigned long * or a
              unsigned long, respectively, and the value returned (or assigned) is
              the Epoch.  To set the RTC's Epoch the process must be privileged
              (i.e., have the CAP_SYS_TIME capability).

       RTC_WKALM_RD, RTC_WKALM_SET
              Some RTCs support a more powerful alarm interface, using these
              ioctls to read or write the RTC's alarm time (respectively) with
              this structure:

                  struct rtc_wkalrm {
                      unsigned char enabled;
                      unsigned char pending;
                      struct rtc_time time;
                  };

              The enabled flag is used to enable or disable the alarm interrupt,
              or to read its current status; when using these calls, RTC_AIE_ON
              and RTC_AIE_OFF are not used.  The pending flag is used by
              RTC_WKALM_RD to report a pending interrupt (so it's mostly useless
              on Linux, except when talking to the RTC managed by EFI firmware).
              The time field is as used with RTC_ALM_READ and RTC_ALM_SET except
              that the tm_mday, tm_mon, and tm_year fields are also valid.  A
              pointer to this structure should be passed as the third ioctl(2)
              argument.

FILES top

       /dev/rtc, /dev/rtc0, /dev/rtc1, etc: RTC special character device files.

       /proc/driver/rtc: status of the (first) RTC.

NOTES top

       When the kernel's system time is synchronized with an external reference
       using adjtimex(2) it will update a designated RTC periodically every 11
       minutes.  To do so, the kernel has to briefly turn off periodic interrupts;
       this might affect programs using that RTC.

       An RTC's Epoch has nothing to do with the POSIX Epoch which is only used
       for the system clock.

       If the year according to the RTC's Epoch and the year register is less than
       1970 it is assumed to be 100 years later, that is, between 2000 and 2069.

       Some RTCs support "wildcard" values in alarm fields, to support scenarios
       like periodic alarms at fifteen minutes after every hour, or on the first
       day of each month.  Such usage is nonportable; portable user space code
       only expects a single alarm interrupt, and will either disable or
       reinitialize the alarm after receiving it.

       Some RTCs support periodic interrupts with periods that are multiples of a
       second rather than fractions of a second; multiple alarms; programmable
       output clock signals; nonvolatile memory; and other hardware capabilities
       that are not currently exposed by this API.

SEE ALSO top

       date(1), adjtimex(2), gettimeofday(2), settimeofday(2), stime(2), time(2),
       gmtime(3), time(7), hwclock(8)

       Documentation/rtc.txt in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2010-02-25                              RTC(4)


rtime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

RTIME(3)                     Linux Programmer's Manual                    RTIME(3)

NAME top

       rtime - get time from a remote machine

SYNOPSIS top

       #include <rpc/des_crypt.h>

       int rtime(struct sockaddr_in *addrp, struct rpc_timeval *timep,
                 struct rpc_timeval *timeout);

DESCRIPTION top

       This function uses the Time Server Protocol as described in RFC 868 to
       obtain the time from a remote machine.

       The Time Server Protocol gives the time in seconds since 00:00:00 UTC, 1
       Jan 1900, and this function subtracts the appropriate constant in order to
       convert the result to seconds since the Epoch, 1970-01-01 00:00:00 +0000
       (UTC).

       When timeout is non-NULL, the udp/time socket (port 37) is used.
       Otherwise, the tcp/time socket (port 37) is used.

RETURN VALUE top

       On success, 0 is returned, and the obtained 32-bit time value is stored in
       timep->tv_sec.  In case of error -1 is returned, and errno is set
       appropriately.

ERRORS top

       All errors for underlying functions (sendto(2), poll(2), recvfrom(2),
       connect(2), read(2)) can occur.  Moreover:

       EIO    The number of returned bytes is not 4.

       ETIMEDOUT
              The waiting time as defined in timeout has expired.

NOTES top

       Only IPv4 is supported.

       Some in.timed versions only support TCP.  Try the example program with
       use_tcp set to 1.

       Libc5 uses the prototype
       int rtime(struct sockaddr_in *, struct timeval *, struct timeval *);
       and requires <sys/time.h> instead of <rpc/auth_des.h>.

BUGS top

       rtime() in glibc 2.2.5 and earlier does not work properly on 64-bit
       machines.

EXAMPLE top

       This example requires that port 37 is up and open.  You may check that the
       time entry within /etc/inetd.conf is not commented out.
       The program connects to a computer called "linux".  Using "localhost" does
       not work.  The result is the localtime of the computer "linux".

       #include <stdio.h>
       #include <stdlib.h>
       #include <errno.h>
       #include <string.h>
       #include <time.h>
       #include <rpc/auth_des.h>
       #include <netdb.h>

       int use_tcp = 0;
       char *servername = "linux";

       int
       main(void)
       {
           struct sockaddr_in name;
           struct rpc_timeval time1 = {0,0};
           struct rpc_timeval timeout = {1,0};
           struct hostent *hent;
           int ret;

           memset(&name, 0, sizeof(name));
           sethostent(1);
           hent = gethostbyname(servername);
           memcpy(&name.sin_addr, hent->h_addr, hent->h_length);

           ret = rtime(&name, &time1, use_tcp ? NULL : &timeout);
           if (ret < 0)
               perror("rtime error");
           else {
            time_t t = time1.tv_sec;
               printf("%s\n", ctime(&t));
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       ntpdate(1), inetd(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-03                            RTIME(3)


rtld-audit(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RTLD-AUDIT(7)                Linux Programmer's Manual               RTLD-AUDIT(7)

NAME top

       rtld-audit - auditing API for the dynamic linker

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */

       #include <link.h>

DESCRIPTION top

       The GNU dynamic linker (run-time linker) provides an auditing API that
       allows an application to be notified when various dynamic linking events
       occur.  This API is very similar to the auditing interface provided by the
       Solaris run-time linker.  The necessary constants and prototypes are
       defined by including <link.h>.

       To use this interface, the programmer creates a shared library that
       implements a standard set of function names.  Not all of the functions need
       to be implemented: in most cases, if the programmer is not interested in a
       particular class of auditing event, then no implementation needs to be
       provided for the corresponding auditing function.

       To employ the auditing interface, the environment variable LD_AUDIT must be
       defined to contain a colon-separated list of shared libraries, each of
       which can implement (parts of) the auditing API.  When an auditable event
       occurs, the corresponding function is invoked in each library, in the order
       that the libraries are listed.

la_version()

       unsigned int la_version(unsigned int version);

       This is the only function that must be defined by an auditing library: it
       performs the initial handshake between the dynamic linker and the auditing
       library.  When invoking this function, the dynamic linker passes, in
       version, the highest version of the auditing interface that the linker
       supports.  If necessary, the auditing library can check that this version
       is sufficient for its requirements.

       As its function result, this function should return the version of the
       auditing interface that this auditing library expects to use (returning
       version is acceptable).  If the returned value is 0, or a version that is
       greater than that supported by the dynamic linker, then the audit library
       is ignored.

la_objsearch()

       char *la_objsearch(const char *name, uintptr_t *cookie,
                          unsigned int flag);

       The dynamic linker invokes this function to inform the auditing library
       that it is about to search for a shared object.  The name argument is the
       filename or pathname that is to be searched for.  cookie identifies the
       shared object that initiated the search.  flag is set to one of the
       following values:

       LA_SER_ORIG      This is the original name that is being searched for.
                        Typically, this name comes from an ELF DT_NEEDED entry, or
                        is the filename argument given to dlopen(3).

       LA_SER_LIBPATH   name was created using a directory specified in
                        LD_LIBRARY_PATH.

       LA_SER_RUNPATH   name was created using a directory specified in an ELF
                        DT_RPATH or DT_RUNPATH list.

       LA_SER_CONFIG    name was found via the ldconfig(8) cache
                        (/etc/ld.so.cache).

       LA_SER_DEFAULT   name was found via a search of one of the default
                        directories.

       LA_SER_SECURE    name is specific to a secure object (unused on Linux).

       As its function result, la_objsearch() returns the pathname that the
       dynamic linker should use for further processing.  If NULL is returned,
       then this pathname is ignored for further processing.  If this audit
       library simply intends to monitor search paths, then name should be
       returned.

la_activity()

       void la_activity( uintptr_t *cookie, unsigned int flag);

       The dynamic linker calls this function to inform the auditing library that
       link-map activity is occurring.  cookie identifies the object at the head
       of the link map.  When the dynamic linker invokes this function, flag is
       set to one of the following values:

       LA_ACT_ADD         New objects are being added to the link map.

       LA_ACT_DELETE      Objects are being removed from the link map.

       LA_ACT_CONSISTENT  Link-map activity has been completed: the map is once
                          again consistent.

la_objopen()

       unsigned int la_objopen(struct link_map *map, Lmid_t lmid,
                               uintptr_t *cookie);

       The dynamic linker calls this function when a new shared object is loaded.
       The map argument is a pointer to a link-map structure that describes the
       object.  The lmid field has one of the following values

       LM_ID_BASE       Link map is part of the initial namespace.

       LM_ID_NEWLM      Link map is part of a new namespace requested via
                        dlmopen(3).

       cookie is a pointer to an identifier for this object.  The identifier is
       provided to later calls to functions in the auditing library in order to
       identify this object.  This identifier is initialized to point to object's
       link map, but the audit library can change the identifier to some other
       value that it may prefer to use to identify the object.

       As its return value, la_objopen() returns a bit mask created by ORing zero
       or more of the following constants, which allow the auditing library to
       select the objects to be monitored by la_symbind*():

       LA_FLG_BINDTO    Audit symbol bindings to this object.

       LA_FLG_BINDFROM  Audit symbol bindings from this object.

       A return value of 0 from la_objopen() indicates that no symbol bindings
       should be audited for this object.

la_objclose()

       unsigned int la_objclose(uintptr_t *[22mcookie);[0m

       The dynamic linker invokes this function after any finalization code for
       the object has been executed, before the object is unloaded.  The cookie
       argument is the identifier obtained from a previous invocation of
       la_objopen().

       In the current implementation, the value returned by la_objclose() is
       ignored.

la_preinit()

       void la_preinit(uintptr_t *cookie);

       The dynamic linker invokes this function after all shared objects have been
       loaded, before control is passed to the application (i.e., before calling
       main()).  Note that main() may still later dynamically load objects using
       dlopen(3).

la_symbind*()

       uintptr_t la_symbind32(Elf32_Sym *sym, unsigned int ndx,
                              uintptr_t *refcook, uintptr_t *defcook,
                              unsigned int *flags, const char *symname);
       uintptr_t la_symbind64(Elf64_Sym *sym, unsigned int ndx,
                              uintptr_t *refcook, uintptr_t *defcook,
                              unsigned int *flags, const char *symname);

       The dynamic linker invokes one of these functions when a symbol binding
       occurs between two shared objects that have been marked for auditing
       notification by la_objopen().  The la_symbind32() function is employed on
       32-bit platforms; the la_symbind64() function is employed on 64-bit
       platforms.

       The sym argument is a pointer to a structure that provides information
       about the symbol being bound.  The structure definition is shown in
       <elf.h>.  Among the fields of this structure, st_value indicates the
       address to which the symbol is bound.

       The ndx argument gives the index of the symbol in the symbol table of the
       bound shared object.

       The refcook argument identifies the shared object that is making the symbol
       reference; this is the same identifier that is provided to the la_objopen()
       function that returned LA_FLG_BINDFROM.  The defcook argument identifies
       the shared object that defines the referenced symbol; this is the same
       identifier that is provided to the la_objopen() function that returned
       LA_FLG_BINDTO.

       The symname argument points a string containing the name of the symbol.

       The flags argument is a bit mask that both provides information about the
       symbol and can be used to modify further auditing of this PLT (Procedure
       Linkage Table) entry.  The dynamic linker may supply the following bit
       values in this argument:

       LA_SYMB_DLSYM         The binding resulted from a call to dlsym(3).

       LA_SYMB_ALTVALUE      A previous la_symbind*() call returned an alternate
                             value for this symbol.

       By default, if the auditing library implements la_pltenter() and
       la_pltexit() functions (see below), then these functions are invoked, after
       la_symbind(), for PLT entries, each time the symbol is referenced.  The
       following flags can be ORed into *flags to change this default behavior:

       LA_SYMB_NOPLTENTER    Don't call la_pltenter() for this symbol.

       LA_SYMB_NOPLTEXIT     Don't call la_pltexit() for this symbol.

       The return value of la_symbind32() and la_symbind64() is the address to
       which control should be passed after the function returns.  If the auditing
       library is simply monitoring symbol bindings, then it should return
       sym->st_value.  A different value may be returned if the library wishes to
       direct control to an alternate location.

la_pltenter()

       The precise name and argument types for this function depend on the
       hardware platform.  (The appropriate definition is supplied by <link.h>.)
       Here is the definition for x86-32:

       Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
                        uintptr_t *refcook, uintptr_t *defcook,
                        La_i86_regs *regs, unsigned int *flags,
                        const char *symname, long int *framesizep);

       This function is invoked just before a PLT entry is called, between two
       shared objects that have been marked for binding notification.

       The sym, ndx, refcook, defcook, and symname are as for la_symbind*().

       The regs argument points to a structure (defined in <link.h>) containing
       the values of registers to be used for the call to this PLT entry.

       The flags argument points to a bit mask that conveys information about, and
       can be used to modify subsequent auditing of, this PLT entry, as for
       la_symbind*().

       The framesizep argument points to a long int buffer that can be used to
       explicitly set the frame size used for the call to this PLT entry.  If
       different la_pltenter() invocations for this symbol return different
       values, then the maximum returned value is used.  The la_pltenter()
       function is only called if this buffer is explicitly set to a suitable
       value.

       The return value of la_pltenter() is as for la_symbind*().

la_pltexit()

       The precise name and argument types for this function depend on the
       hardware platform.  (The appropriate definition is supplied by <link.h>.)
       Here is the definition for x86-32:

       unsigned int la_i86_gnu_pltexit(Elf32_Sym *sym, unsigned int ndx,
                        uintptr_t *refcook, uintptr_t *defcook,
                        const La_i86_regs *inregs, La_i86_retval *outregs,
                        const char *symname);

       This function is called when a PLT entry, made between two shared objects
       that have been marked for binding notification, returns.  The function is
       called just before control returns to the caller of the PLT entry.

       The sym, ndx, refcook, defcook, and symname are as for la_symbind*().

       The inregs argument points to a structure (defined in <link.h>) containing
       the values of registers used for the call to this PLT entry.  The outregs
       argument points to a structure (defined in <link.h>) containing return
       values for the call to this PLT entry.  These values can be modified by the
       caller, and the changes will be visible to the caller of the PLT entry.

       In the current GNU implementation, the return value of la_pltexit() is
       ignored.

CONFORMING TO top

       This API is nonstandard, but very similar to the Solaris API, described in
       the Solaris Linker and Libraries Guide, in the chapter Runtime Linker
       Auditing Interface.

NOTES top

       Note the following differences from the Solaris dynamic linker auditing
       API:

       *  The Solaris la_objfilter() interface is not supported by the GNU
          implementation.

       *  The Solaris la_symbind32() and la_pltexit() functions do not provide a
          symname argument.

       *  The Solaris la_pltexit() function does not provide inregs and outregs
          arguments (but does provide a retval argument with the function return
          value).

EXAMPLE top

       #include <link.h>
       #include <stdio.h>

       unsigned int
       la_version(unsigned int version)
       {
           printf("la_version(): %d\n", version);

           return version;
       }

       char *
       la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
       {
           printf("la_objsearch(): name = %s; cookie = %x", name, cookie);
           printf("; flag = %s\n",
                   (flag == LA_SER_ORIG) ?    "LA_SER_ORIG" :
                   (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
                   (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
                   (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
                   (flag == LA_SER_CONFIG) ?  "LA_SER_CONFIG" :
                   (flag == LA_SER_SECURE) ?  "LA_SER_SECURE" :
                   "???");

           return name;
       }

       void
       la_activity (uintptr_t *cookie, unsigned int flag)
       {
           printf("la_activity(): cookie = %x; flag = %s\n", cookie,
                   (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
                   (flag == LA_ACT_ADD) ?        "LA_ACT_ADD" :
                   (flag == LA_ACT_DELETE) ?     "LA_ACT_DELETE" :
                   "???");
       }

       unsigned int
       la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
       {
           printf("la_objopen(): loading \"%s\"; lmid = %s; cookie=%x\n",
                   map->l_name,
                   (lmid == LM_ID_BASE) ?  "LM_ID_BASE" :
                   (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
                   "???",
                   cookie);

           return LA_FLG_BINDTO | LA_FLG_BINDFROM;
       }

       unsigned int
       la_objclose (uintptr_t *cookie)
       {
           printf("la_objclose(): %x\n", cookie);

           return 0;
       }

       void
       la_preinit(uintptr_t *cookie)
       {
           printf("la_preinit(): %x\n", cookie);
       }

       uintptr_t
       la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
               uintptr_t *defcook, unsigned int *flags, const char *symname)
       {
           printf("la_symbind32(): symname = %s; sym->st_value = %p\n",
                   symname, sym->st_value);
           printf("        ndx = %d; flags = 0x%x", ndx, *flags);
           printf("; refcook = %x; defcook = %x\n", refcook, defcook);

           return sym->st_value;
       }

       uintptr_t
       la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
               uintptr_t *defcook, unsigned int *flags, const char *symname)
       {
           printf("la_symbind64(): symname = %s; sym->st_value = %p\n",
                   symname, sym->st_value);
           printf("        ndx = %d; flags = 0x%x", ndx, *flags);
           printf("; refcook = %x; defcook = %x\n", refcook, defcook);

           return sym->st_value;
       }

       Elf32_Addr
       la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
               uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
               unsigned int *flags, const char *symname, long int *framesizep)
       {
           printf("la_i86_gnu_pltenter(): %s (%p)\n", symname, sym->st_value);

           return sym->st_value;
       }

BUGS top

       In glibc versions up to and include 2.9, specifying more than one audit
       library in LD_AUDIT results in a run-time crash.  This is reportedly fixed
       in glibc 2.10.

SEE ALSO top

       ldd(1), dlopen(3), ld.so(8), ldconfig(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-07                       RTLD-AUDIT(7)


rtnetlink(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

RTNETLINK(3)                 Linux Programmer's Manual                RTNETLINK(3)

NAME top

       rtnetlink - macros to manipulate rtnetlink messages

SYNOPSIS top

       #include <asm/types.h>
       #include <linux/netlink.h>
       #include <linux/rtnetlink.h>
       #include <sys/socket.h>

       rtnetlink_socket = socket(AF_NETLINK, int socket_type, NETLINK_ROUTE);

       int RTA_OK(struct rtattr *rta, int rtabuflen);

       void *RTA_DATA(struct rtattr *rta);

       unsigned int RTA_PAYLOAD(struct rtattr *rta);

       struct rtattr *RTA_NEXT(struct rtattr *rta, unsigned int rtabuflen);

       unsigned int RTA_LENGTH(unsigned int length);

       unsigned int RTA_SPACE(unsigned int length);

DESCRIPTION top

       All rtnetlink(7) messages consist of a netlink(7) message header and
       appended attributes.  The attributes should be only manipulated using the
       macros provided here.

       RTA_OK(rta, attrlen) returns true if rta points to a valid routing
       attribute; attrlen is the running length of the attribute buffer.  When not
       true then you must assume there are no more attributes in the message, even
       if attrlen is nonzero.

       RTA_DATA(rta) returns a pointer to the start of this attribute's data.

       RTA_PAYLOAD(rta) returns the length of this attribute's data.

       RTA_NEXT(rta, attrlen) gets the next attribute after rta.  Calling this
       macro will update attrlen.  You should use RTA_OK to check the validity of
       the returned pointer.

       RTA_LENGTH(len) returns the length which is required for len bytes of data
       plus the header.

       RTA_SPACE(len) returns the amount of space which will be needed in a
       message with len bytes of data.

CONFORMING TO top

       These macros are nonstandard Linux extensions.

BUGS top

       This manual page is incomplete.

EXAMPLE top

       Creating a rtnetlink message to set the MTU of a device:
           #include <linux/rtnetlink.h>

           ...

           struct {
               struct nlmsghdr  nh;
               struct ifinfomsg if;
               char             attrbuf[512];
           } req;

           struct rtattr *rta;
           unsigned int mtu = 1000;

           int rtnetlink_sk = socket(AF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE);

           memset(&req, 0, sizeof(req));
           req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(struct ifinfomsg));
           req.nh.nlmsg_flags = NLM_F_REQUEST;
           req.nh.nlmsg_type = RTM_NEWLINK;
           req.if.ifi_family = AF_UNSPEC;
           req.if.ifi_index = INTERFACE_INDEX;
           req.if.ifi_change = 0xffffffff; /* ??? */
           rta = (struct rtattr *)(((char *) &req) +
                                    NLMSG_ALIGN(req.nh.nlmsg_len));
           rta->rta_type = IFLA_MTU;
           rta->rta_len = RTA_LENGTH(sizeof(unsigned int));
           req.n.nlmsg_len = NLMSG_ALIGN(req.nh.nlmsg_len) +
                                         RTA_LENGTH(sizeof(mtu));
           memcpy(RTA_DATA(rta), &mtu, sizeof(mtu));
           send(rtnetlink_sk, &req, req.nh.nlmsg_len);

SEE ALSO top

       netlink(3), netlink(7), rtnetlink(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-24                        RTNETLINK(3)


rtnetlink(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

RTNETLINK(7)                 Linux Programmer's Manual                RTNETLINK(7)

NAME top

       rtnetlink - Linux IPv4 routing socket

SYNOPSIS top

       #include <asm/types.h>
       #include <linux/netlink.h>
       #include <linux/rtnetlink.h>
       #include <sys/socket.h>

       rtnetlink_socket = socket(AF_NETLINK, int socket_type, NETLINK_ROUTE);

DESCRIPTION top

       Rtnetlink allows the kernel's routing tables to be read and altered.  It is
       used within the kernel to communicate between various subsystems, though
       this usage is not documented here, and for communication with user-space
       programs.  Network routes, IP addresses, link parameters, neighbor setups,
       queueing disciplines, traffic classes and packet classifiers may all be
       controlled through NETLINK_ROUTE sockets.  It is based on netlink messages;
       see netlink(7) for more information.

Routing Attributes

       Some rtnetlink messages have optional attributes after the initial header:

           struct rtattr {
               unsigned short rta_len;    /* Length of option */
               unsigned short rta_type;   /* Type of option */
               /* Data follows */
           };

       These attributes should be only manipulated using the RTA_* macros or
       libnetlink, see rtnetlink(3).

Messages

       Rtnetlink consists of these message types (in addition to standard netlink
       messages):

       RTM_NEWLINK, RTM_DELLINK, RTM_GETLINK
              Create, remove or get information about a specific network
              interface.  These messages contain an ifinfomsg structure followed
              by a series of rtattr structures.

              struct ifinfomsg {
                  unsigned char  ifi_family; /* AF_UNSPEC */
                  unsigned short ifi_type;   /* Device type */
                  int            ifi_index;  /* Interface index */
                  unsigned int   ifi_flags;  /* Device flags  */
                  unsigned int   ifi_change; /* change mask */
              };

              ifi_flags contains the device flags, see netdevice(7); ifi_index is
              the unique interface index, ifi_change is reserved for future use
              and should be always set to 0xFFFFFFFF.

                                 Routing attributes
              rta_type         value type         description
              ----------------------------------------------------------
              IFLA_UNSPEC      -                  unspecified.
              IFLA_ADDRESS     hardware address   interface L2 address
              IFLA_BROADCAST   hardware address   L2 broadcast address.
              IFLA_IFNAME      asciiz string      Device name.
              IFLA_MTU         unsigned int       MTU of the device.

              IFLA_LINK        int                Link type.
              IFLA_QDISC       asciiz string      Queueing discipline.
              IFLA_STATS       see below          Interface Statistics.

              The  value  type  for  IFLA_STATS  is struct rtnl_link_stats (struct
              net_device_stats in Linux 2.4 and earlier).

       RTM_NEWADDR, RTM_DELADDR, RTM_GETADDR
              Add, remove or receive information about an  IP  address  associated
              with an interface.  In Linux 2.2, an interface can carry multiple IP
              addresses, this replaces the alias device concept in 2.0.  In  Linux
              2.2,  these  messages support IPv4 and IPv6 addresses.  They contain
              an  ifaddrmsg  structure,  optionally  followed  by  rtattr  routing
              attributes.

              struct ifaddrmsg {
                  unsigned char ifa_family;    /* Address type */
                  unsigned char ifa_prefixlen; /* Prefixlength of address */
                  unsigned char ifa_flags;     /* Address flags */
                  unsigned char ifa_scope;     /* Address scope */
                  int           ifa_index;     /* Interface index */
              };

              ifa_family   is  the  address  family  type  (currently  AF_INET  or
              AF_INET6), ifa_prefixlen is the length of the address  mask  of  the
              address  if defined for the family (like for IPv4), ifa_scope is the
              address scope, ifa_index is the interface index of the interface the
              address   is   associated   with.   ifa_flags  is  a  flag  word  of
              IFA_F_SECONDARY  for  secondary  address  (old   alias   interface),
              IFA_F_PERMANENT  for  a  permanent address set by the user and other
              undocumented flags.

                                       Attributes
              rta_type        value type             description
              -------------------------------------------------------------
              IFA_UNSPEC      -                      unspecified.
              IFA_ADDRESS     raw protocol address   interface address
              IFA_LOCAL       raw protocol address   local address
              IFA_LABEL       asciiz string          name of the interface
              IFA_BROADCAST   raw protocol address   broadcast address.
              IFA_ANYCAST     raw protocol address   anycast address
              IFA_CACHEINFO   struct ifa_cacheinfo   Address information.

       RTM_NEWROUTE, RTM_DELROUTE, RTM_GETROUTE
              Create, remove or receive information about a network route.   These
              messages  contain  an  rtmsg  structure with an optional sequence of
              rtattr structures following.  For RTM_GETROUTE, setting  rtm_dst_len
              and  rtm_src_len  to  0  means you get all entries for the specified
              routing  table.   For  the  other  fields,  except   rtm_table   and
              rtm_protocol, 0 is the wildcard.

              struct rtmsg {
                  unsigned char rtm_family;   /* Address family of route */
                  unsigned char rtm_dst_len;  /* Length of destination */
                  unsigned char rtm_src_len;  /* Length of source */
                  unsigned char rtm_tos;      /* TOS filter */

                  unsigned char rtm_table;    /* Routing table ID */
                  unsigned char rtm_protocol; /* Routing protocol; see below */
                  unsigned char rtm_scope;    /* See below */
                  unsigned char rtm_type;     /* See below */

                  unsigned int  rtm_flags;
              };

              rtm_type          Route type
              -----------------------------------------------------------
              RTN_UNSPEC        unknown route
              RTN_UNICAST       a gateway or direct route
              RTN_LOCAL         a local interface route
              RTN_BROADCAST     a local broadcast route (sent as a
                                broadcast)
              RTN_ANYCAST       a local broadcast route (sent as a
                                unicast)
              RTN_MULTICAST     a multicast route
              RTN_BLACKHOLE     a packet dropping route
              RTN_UNREACHABLE   an unreachable destination
              RTN_PROHIBIT      a packet rejection route
              RTN_THROW         continue routing lookup in another table
              RTN_NAT           a network address translation rule
              RTN_XRESOLVE      refer to an external resolver (not
                                implemented)

              rtm_protocol      Route origin.
              ---------------------------------------
              RTPROT_UNSPEC     unknown
              RTPROT_REDIRECT   by an ICMP redirect
                                (currently unused)
              RTPROT_KERNEL     by the kernel
              RTPROT_BOOT       during boot
              RTPROT_STATIC     by the administrator

              Values  larger than RTPROT_STATIC are not interpreted by the kernel,
              they are just for user information.  They may be  used  to  tag  the
              source  of  a routing information or to distinguish between multiple
              routing daemons.  See <linux/rtnetlink.h>  for  the  routing  daemon
              identifiers which are already assigned.

              rtm_scope is the distance to the destination:

              RT_SCOPE_UNIVERSE   global route
              RT_SCOPE_SITE       interior route in the local
                                  autonomous system
              RT_SCOPE_LINK       route on this link
              RT_SCOPE_HOST       route on the local host
              RT_SCOPE_NOWHERE    destination doesn't exist

              The values between RT_SCOPE_UNIVERSE and RT_SCOPE_SITE are available
              to the user.

              The rtm_flags have the following meanings:

              RTM_F_NOTIFY     if the route changes, notify the user via
                               rtnetlink
              RTM_F_CLONED     route is cloned from another route
              RTM_F_EQUALIZE   a multipath equalizer (not yet implemented)

              rtm_table specifies the routing table

              RT_TABLE_UNSPEC    an unspecified routing table
              RT_TABLE_DEFAULT   the default table
              RT_TABLE_MAIN      the main table
              RT_TABLE_LOCAL     the local table

              The user may assign arbitrary  values  between  RT_TABLE_UNSPEC  and
              RT_TABLE_DEFAULT.

                                       Attributes
              rta_type        value type         description
              --------------------------------------------------------------
              RTA_UNSPEC      -                  ignored.
              RTA_DST         protocol address   Route destination address.
              RTA_SRC         protocol address   Route source address.
              RTA_IIF         int                Input interface index.
              RTA_OIF         int                Output interface index.
              RTA_GATEWAY     protocol address   The gateway of the route
              RTA_PRIORITY    int                Priority of route.
              RTA_PREFSRC
              RTA_METRICS     int                Route metric
              RTA_MULTIPATH
              RTA_PROTOINFO
              RTA_FLOW
              RTA_CACHEINFO

              Fill these values in!

       RTM_NEWNEIGH, RTM_DELNEIGH, RTM_GETNEIGH
              Add,  remove  or  receive  information  about a neighbor table entry
              (e.g., an ARP entry).  The message contains an ndmsg structure.

              struct ndmsg {
                  unsigned char ndm_family;
                  int           ndm_ifindex;  /* Interface index */
                  __u16         ndm_state;    /* State */
                  __u8          ndm_flags;    /* Flags */
                  __u8          ndm_type;
              };

              struct nda_cacheinfo {
                  __u32         ndm_confirmed;
                  __u32         ndm_used;
                  __u32         ndm_updated;
                  __u32         ndm_refcnt;
              };

              ndm_state is a bit mask of the following states:

              NUD_INCOMPLETE   a currently resolving cache entry
              NUD_REACHABLE    a confirmed working cache entry
              NUD_STALE        an expired cache entry
              NUD_DELAY        an entry waiting for a timer
              NUD_PROBE        a cache entry that is currently reprobed
              NUD_FAILED       an invalid cache entry
              NUD_NOARP        a device with no destination cache
              NUD_PERMANENT    a static entry

              Valid ndm_flags are:

              NTF_PROXY    a proxy arp entry
              NTF_ROUTER   an IPv6 router

              The rtattr struct has the following meanings for the rta_type field:

              NDA_UNSPEC      unknown type
              NDA_DST         a neighbor cache n/w layer destination address
              NDA_LLADDR      a neighbor cache link layer address

              NDA_CACHEINFO   cache statistics.

              If the rta_type field is NDA_CACHEINFO then a  struct  nda_cacheinfo
              header follows

       RTM_NEWRULE, RTM_DELRULE, RTM_GETRULE
              Add, delete or retrieve a routing rule.  Carries a struct rtmsg

       RTM_NEWQDISC, RTM_DELQDISC, RTM_GETQDISC
              Add,  remove  or  get a queueing discipline.  The message contains a
              struct tcmsg and may be followed by a series of attributes.

              struct tcmsg {
                  unsigned char    tcm_family;
                  int              tcm_ifindex;   /* interface index */
                  __u32            tcm_handle;    /* Qdisc handle */
                  __u32            tcm_parent;    /* Parent qdisc */
                  __u32            tcm_info;
              };

                                        Attributes
              rta_type     value type           Description
              ----------------------------------------------------------------
              TCA_UNSPEC   -                    unspecified
              TCA_KIND     asciiz string        Name of queueing discipline
              TCA_OPTIONS  byte sequence        Qdisc-specific options follow
              TCA_STATS    struct tc_stats      Qdisc statistics.
              TCA_XSTATS   qdisc specific       Module-specific statistics.
              TCA_RATE     struct tc_estimator  Rate limit.

              In addition various  other  qdisc  module  specific  attributes  are
              allowed.  For more information see the appropriate include files.

       RTM_NEWTCLASS, RTM_DELTCLASS, RTM_GETTCLASS
              Add, remove or get a traffic class.  These messages contain a struct
              tcmsg as described above.

       RTM_NEWTFILTER, RTM_DELTFILTER, RTM_GETTFILTER
              Add, remove or receive information about a  traffic  filter.   These
              messages contain a struct tcmsg as described above.

VERSIONS top

       rtnetlink is a new feature of Linux 2.2.

BUGS top

       This manual page is incomplete.

SEE ALSO top

       cmsg(3), rtnetlink(3), ip(7), netlink(7)

COLOPHON top

       This  page  is  part  of  release  3.45  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                               2012-11-11                        RTNETLINK(7)


sigaction(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SIGACTION(2)                 Linux Programmer's Manual                SIGACTION(2)

NAME top

       sigaction - examine and change a signal action

SYNOPSIS top

       #include <signal.h>

       int sigaction(int signum, const struct sigaction *act,
                     struct sigaction *oldact);

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

       sigaction(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The sigaction() system call is used to change the action taken by a process
       on receipt of a specific signal.  (See signal(7) for an overview of
       signals.)

       signum specifies the signal and can be any valid signal except SIGKILL and
       SIGSTOP.

       If act is non-NULL, the new action for signal signum is installed from act.
       If oldact is non-NULL, the previous action is saved in oldact.

       The sigaction structure is defined as something like:

           struct sigaction {
               void     (*sa_handler)(int);
               void     (*sa_sigaction)(int, siginfo_t *, void *);
               sigset_t   sa_mask;
               int        sa_flags;
               void     (*sa_restorer)(void);
           };

       On some architectures a union is involved: do not assign to both sa_handler
       and sa_sigaction.

       The sa_restorer element is obsolete and should not be used.  POSIX does not
       specify a sa_restorer element.

       sa_handler specifies the action to be associated with signum and may be
       SIG_DFL for the default action, SIG_IGN to ignore this signal, or a pointer
       to a signal handling function.  This function receives the signal number as
       its only argument.

       If SA_SIGINFO is specified in sa_flags, then sa_sigaction (instead of
       sa_handler) specifies the signal-handling function for signum.  This
       function receives the signal number as its first argument, a pointer to a
       siginfo_t as its second argument and a pointer to a ucontext_t (cast to
       void *) as its third argument.  (Commonly, the handler function doesn't
       make any use of the third argument.  See getcontext(2) for further
       information about ucontext_t.)

       sa_mask specifies a mask of signals which should be blocked (i.e., added to
       the signal mask of the thread in which the signal handler is invoked)
       during execution of the signal handler.  In addition, the signal which
       triggered the handler will be blocked, unless the SA_NODEFER flag is used.

       sa_flags specifies a set of flags which modify the behavior of the signal.
       It is formed by the bitwise OR of zero or more of the following:

           SA_NOCLDSTOP
                  If signum is SIGCHLD, do not receive notification when child
                  processes stop (i.e., when they receive one of SIGSTOP, SIGTSTP,
                  SIGTTIN or SIGTTOU) or resume (i.e., they receive SIGCONT) (see
                  wait(2)).  This flag is only meaningful when establishing a
                  handler for SIGCHLD.

           SA_NOCLDWAIT (since Linux 2.6)
                  If signum is SIGCHLD, do not transform children into zombies
                  when they terminate.  See also waitpid(2).  This flag is only
                  meaningful when establishing a handler for SIGCHLD, or when
                  setting that signal's disposition to SIG_DFL.

                  If the SA_NOCLDWAIT flag is set when establishing a handler for
                  SIGCHLD, POSIX.1 leaves it unspecified whether a SIGCHLD signal
                  is generated when a child process terminates.  On Linux, a
                  SIGCHLD signal is generated in this case; on some other
                  implementations, it is not.

           SA_NODEFER
                  Do not prevent the signal from being received from within its
                  own signal handler.  This flag is only meaningful when
                  establishing a signal handler.  SA_NOMASK is an obsolete,
                  nonstandard synonym for this flag.

           SA_ONSTACK
                  Call the signal handler on an alternate signal stack provided by
                  sigaltstack(2).  If an alternate stack is not available, the
                  default stack will be used.  This flag is only meaningful when
                  establishing a signal handler.

           SA_RESETHAND
                  Restore the signal action to the default upon entry to the
                  signal handler.  This flag is only meaningful when establishing
                  a signal handler.  SA_ONESHOT is an obsolete, nonstandard
                  synonym for this flag.

           SA_RESTART
                  Provide behavior compatible with BSD signal semantics by making
                  certain system calls restartable across signals.  This flag is
                  only meaningful when establishing a signal handler.  See
                  signal(7) for a discussion of system call restarting.

           SA_SIGINFO (since Linux 2.2)
                  The signal handler takes three arguments, not one.  In this
                  case, sa_sigaction should be set instead of sa_handler.  This
                  flag is only meaningful when establishing a signal handler.

       The siginfo_t argument to sa_sigaction is a struct with the following
       elements:

           siginfo_t {
               int      si_signo;    /* Signal number */
               int      si_errno;    /* An errno value */
               int      si_code;     /* Signal code */
               int      si_trapno;   /* Trap number that caused
                                        hardware-generated signal
                                        (unused on most architectures) */
               pid_t    si_pid;      /* Sending process ID */
               uid_t    si_uid;      /* Real user ID of sending process */
               int      si_status;   /* Exit value or signal */
               clock_t  si_utime;    /* User time consumed */
               clock_t  si_stime;    /* System time consumed */
               sigval_t si_value;    /* Signal value */
               int      si_int;      /* POSIX.1b signal */
               void    *si_ptr;      /* POSIX.1b signal */
               int      si_overrun;  /* Timer overrun count; POSIX.1b timers */
               int      si_timerid;  /* Timer ID; POSIX.1b timers */
               void    *si_addr;     /* Memory location which caused fault */
               long     si_band;     /* Band event (was int in
                                        glibc 2.3.2 and earlier) */
               int      si_fd;       /* File descriptor */
               short    si_addr_lsb; /* Least significant bit of address
                                        (since kernel 2.6.32) */
           }

       si_signo, si_errno and si_code are defined for all signals.  (si_errno is
       generally unused on Linux.)  The rest of the struct may be a union, so that
       one should only read the fields that are meaningful for the given signal:

       * Signals sent with kill(2) and sigqueue(3) fill in si_pid and si_uid.  In
         addition, signals sent with sigqueue(3) fill in si_int and si_ptr with
         the values specified by the sender of the signal; see sigqueue(3) for
         more details.

       * Signals sent by POSIX.1b timers (since Linux 2.6) fill in si_overrun and
         si_timerid.  The si_timerid field is an internal ID used by the kernel to
         identify the timer; it is not the same as the timer ID returned by
         timer_create(2).  The si_overrun field is the timer overrun count; this
         is the same information as is obtained by a call to timer_getoverrun(2).
         These fields are nonstandard Linux extensions.

       * Signals sent for message queue notification (see the description of
         SIGEV_SIGNAL in mq_notify(3)) fill in si_int/si_ptr, with the sigev_value
         supplied to mq_notify(3); si_pid, with the process ID of the message
         sender; and si_uid, with the real user ID of the message sender.

       * SIGCHLD fills in si_pid, si_uid, si_status, si_utime and si_stime,
         providing information about the child.  The si_pid field is the process
         ID of the child; si_uid is the child's real user ID.  The si_status field
         contains the exit status of the child (if si_code is CLD_EXITED), or the
         signal number that caused the process to change state.  The si_utime and
         si_stime contain the user and system CPU time used by the child process;
         these fields do not include the times used by waited-for children (unlike
         getrusage(2) and time(2)).  In kernels up to 2.6, and since 2.6.27, these
         fields report CPU time in units of sysconf(_SC_CLK_TCK).  In 2.6 kernels
         before 2.6.27, a bug meant that these fields reported time in units of
         the (configurable) system jiffy (see time(7)).

       * SIGILL, SIGFPE, SIGSEGV, SIGBUS, and SIGTRAP fill in si_addr with the
         address of the fault.  On some architectures, these signals also fill in
         the si_trapno filed.  Some suberrors of SIGBUS, in particular
         BUS_MCEERR_AO and BUS_MCEERR_AR, also fill in si_addr_lsb.  This field
         indicates the least significant bit of the reported address and therefore
         the extent of the corruption.  For example, if a full page was corrupted,
         si_addr_lsb contains log2(sysconf(_SC_PAGESIZE)).  BUS_MCERR_* and
         si_addr_lsb are Linux-specific extensions.

       * SIGIO/SIGPOLL (the two names are synonyms on Linux) fills in si_band and
         si_fd.  The si_band event is a bit mask containing the same values as are
         filled in the revents field by poll(2).  The si_fd field indicates the
         file descriptor for which the I/O event occurred.

       si_code is a value (not a bit mask) indicating why this signal was sent.
       The following list shows the values which can be placed in si_code for any
       signal, along with reason that the signal was generated.

           SI_USER        kill(2)

           SI_KERNEL      Sent by the kernel.

           SI_QUEUE       sigqueue(3)

           SI_TIMER       POSIX timer expired

           SI_MESGQ       POSIX message queue state changed (since Linux 2.6.6);
                          see mq_notify(3)

           SI_ASYNCIO     AIO completed

           SI_SIGIO       Queued SIGIO (only in kernels up to Linux 2.2; from
                          Linux 2.4 onward SIGIO/SIGPOLL fills in si_code as
                          described below).

           SI_TKILL       tkill(2) or tgkill(2) (since Linux 2.4.19)

       The following values can be placed in si_code for a SIGILL signal:

           ILL_ILLOPC     illegal opcode

           ILL_ILLOPN     illegal operand

           ILL_ILLADR     illegal addressing mode

           ILL_ILLTRP     illegal trap

           ILL_PRVOPC     privileged opcode

           ILL_PRVREG     privileged register

           ILL_COPROC     coprocessor error

           ILL_BADSTK     internal stack error

       The following values can be placed in si_code for a SIGFPE signal:

           FPE_INTDIV     integer divide by zero

           FPE_INTOVF     integer overflow

           FPE_FLTDIV     floating-point divide by zero

           FPE_FLTOVF     floating-point overflow

           FPE_FLTUND     floating-point underflow

           FPE_FLTRES     floating-point inexact result

           FPE_FLTINV     floating-point invalid operation

           FPE_FLTSUB     subscript out of range

       The following values can be placed in si_code for a SIGSEGV signal:

           SEGV_MAPERR    address not mapped to object

           SEGV_ACCERR    invalid permissions for mapped object

       The following values can be placed in si_code for a SIGBUS signal:

           BUS_ADRALN     invalid address alignment

           BUS_ADRERR     nonexistent physical address

           BUS_OBJERR     object-specific hardware error

           BUS_MCEERR_AR (since Linux 2.6.32)
                          Hardware memory error consumed on a machine check;
                          action required.

           BUS_MCEERR_AO (since Linux 2.6.32)
                          Hardware memory error detected in process but not
                          consumed; action optional.

       The following values can be placed in si_code for a SIGTRAP signal:

           TRAP_BRKPT     process breakpoint

           TRAP_TRACE     process trace trap

           TRAP_BRANCH (since Linux 2.4)
                          process taken branch trap

           TRAP_HWBKPT (since Linux 2.4)
                          hardware breakpoint/watchpoint

       The following values can be placed in si_code for a SIGCHLD signal:

           CLD_EXITED     child has exited

           CLD_KILLED     child was killed

           CLD_DUMPED     child terminated abnormally

           CLD_TRAPPED    traced child has trapped

           CLD_STOPPED    child has stopped

           CLD_CONTINUED  stopped child has continued (since Linux 2.6.9)

       The following values can be placed in si_code for a SIGIO/SIGPOLL signal:

           POLL_IN        data input available

           POLL_OUT       output buffers available

           POLL_MSG       input message available

           POLL_ERR       I/O error

           POLL_PRI       high priority input available

           POLL_HUP       device disconnected

RETURN VALUE top

       sigaction() returns 0 on success and -1 on error.

ERRORS top

       EFAULT act or oldact points to memory which is not a valid part of the
              process address space.

       EINVAL An invalid signal was specified.  This will also be generated if an
              attempt is made to change the action for SIGKILL or SIGSTOP, which
              cannot be caught or ignored.

CONFORMING TO top

       POSIX.1-2001, SVr4.

NOTES top

       A child created via fork(2) inherits a copy of its parent's signal
       dispositions.  During an execve(2), the dispositions of handled signals are
       reset to the default; the dispositions of ignored signals are left
       unchanged.

       According to POSIX, the behavior of a process is undefined after it ignores
       a SIGFPE, SIGILL, or SIGSEGV signal that was not generated by kill(2) or
       raise(3).  Integer division by zero has undefined result.  On some
       architectures it will generate a SIGFPE signal.  (Also dividing the most
       negative integer by -1 may generate SIGFPE.)  Ignoring this signal might
       lead to an endless loop.

       POSIX.1-1990 disallowed setting the action for SIGCHLD to SIG_IGN.
       POSIX.1-2001 allows this possibility, so that ignoring SIGCHLD can be used
       to prevent the creation of zombies (see wait(2)).  Nevertheless, the
       historical BSD and System V behaviors for ignoring SIGCHLD differ, so that
       the only completely portable method of ensuring that terminated children do
       not become zombies is to catch the SIGCHLD signal and perform a wait(2) or
       similar.

       POSIX.1-1990 only specified SA_NOCLDSTOP.  POSIX.1-2001 added SA_NOCLDWAIT,
       SA_RESETHAND, SA_NODEFER, and SA_SIGINFO.  Use of these latter values in
       sa_flags may be less portable in applications intended for older UNIX
       implementations.

       The SA_RESETHAND flag is compatible with the SVr4 flag of the same name.

       The SA_NODEFER flag is compatible with the SVr4 flag of the same name under
       kernels 1.3.9 and newer.  On older kernels the Linux implementation allowed
       the receipt of any signal, not just the one we are installing (effectively
       overriding any sa_mask settings).

       sigaction() can be called with a NULL second argument to query the current
       signal handler.  It can also be used to check whether a given signal is
       valid for the current machine by calling it with NULL second and third
       arguments.

       It is not possible to block SIGKILL or SIGSTOP (by specifying them in
       sa_mask).  Attempts to do so are silently ignored.

       See sigsetops(3) for details on manipulating signal sets.

       See signal(7) for a list of the async-signal-safe functions that can be
       safely called inside from inside a signal handler.

Undocumented

       Before the introduction of SA_SIGINFO it was also possible to get some
       additional information, namely by using a sa_handler with second argument
       of type struct sigcontext.  See the relevant Linux kernel sources for
       details.  This use is obsolete now.

BUGS top

       In kernels up to and including 2.6.13, specifying SA_NODEFER in sa_flags
       prevents not only the delivered signal from being masked during execution
       of the handler, but also the signals specified in sa_mask.  This bug was
       fixed in kernel 2.6.14.

EXAMPLE top

       See mprotect(2).

SEE ALSO top

       kill(1), kill(2), killpg(2), pause(2), sigaltstack(2), signal(2),
       signalfd(2), sigpending(2), sigprocmask(2), sigsuspend(2), wait(2),
       raise(3), siginterrupt(3), sigqueue(3), sigsetops(3), sigvec(3), core(5),
       signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-09-23                        SIGACTION(2)


sigpending(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SIGPENDING(2)                Linux Programmer's Manual               SIGPENDING(2)

NAME top

       sigpending - examine pending signals

SYNOPSIS top

       #include <signal.h>

       int sigpending(sigset_t *set);

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

       sigpending(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       sigpending() returns the set of signals that are pending for delivery to
       the calling thread (i.e., the signals which have been raised while
       blocked).  The mask of pending signals is returned in set.

RETURN VALUE top

       sigpending() returns 0 on success and -1 on error.

ERRORS top

       EFAULT set points to memory which is not a valid part of the process
              address space.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       See sigsetops(3) for details on manipulating signal sets.

       The set of signals that is pending for a thread is the union of the set of
       signals that is pending for that thread and the set of signals that is
       pending for the process as a whole; see signal(7).

       A child created via fork(2) initially has an empty pending signal set; the
       pending signal set is preserved across an execve(2).

BUGS top

       In versions of glibc up to and including 2.2.1, there is a bug in the
       wrapper function for sigpending() which means that information about
       pending real-time signals is not correctly returned.

SEE ALSO top

       kill(2), sigaction(2), signal(2), sigprocmask(2), sigsuspend(2),
       sigsetops(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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-10-04                       SIGPENDING(2)


sigprocmask(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGPROCMASK(2)               Linux Programmer's Manual              SIGPROCMASK(2)

NAME top

       sigprocmask - examine and change blocked signals

SYNOPSIS top

       #include <signal.h>

       int sigprocmask(int how, const sigset_t *set, sigset_t *oldset);

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

       sigprocmask(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       sigprocmask() is used to fetch and/or change the signal mask of the calling
       thread.  The signal mask is the set of signals whose delivery is currently
       blocked for the caller (see also signal(7) for more details).

       The behavior of the call is dependent on the value of how, as follows.

       SIG_BLOCK
              The set of blocked signals is the union of the current set and the
              set argument.

       SIG_UNBLOCK
              The signals in set are removed from the current set of blocked
              signals.  It is permissible to attempt to unblock a signal which is
              not blocked.

       SIG_SETMASK
              The set of blocked signals is set to the argument set.

       If oldset is non-NULL, the previous value of the signal mask is stored in
       oldset.

       If set is NULL, then the signal mask is unchanged (i.e., how is ignored),
       but the current value of the signal mask is nevertheless returned in oldset
       (if it is not NULL).

       The use of sigprocmask() is unspecified in a multithreaded process; see
       pthread_sigmask(3).

RETURN VALUE top

       sigprocmask() returns 0 on success and -1 on error.

ERRORS top

       EFAULT the set or oldset argument points outside the process's allocated
              address space.

       EINVAL The value specified in how was invalid.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       It is not possible to block SIGKILL or SIGSTOP.  Attempts to do so are
       silently ignored.

       Each of the threads in a process has its own signal mask.

       A child created via fork(2) inherits a copy of its parent's signal mask;
       the signal mask is preserved across execve(2).

       If SIGBUS, SIGFPE, SIGILL, or SIGSEGV are generated while they are blocked,
       the result is undefined, unless the signal was generated by kill(2),
       sigqueue(3), or raise(3).

       See sigsetops(3) for details on manipulating signal sets.

SEE ALSO top

       kill(2), pause(2), sigaction(2), signal(2), sigpending(2), sigsuspend(2),
       pthread_sigmask(3), sigqueue(3), sigsetops(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-15                      SIGPROCMASK(2)


rt_sigqueueinfo(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

RT_SIGQUEUEINFO(2)           Linux Programmer's Manual          RT_SIGQUEUEINFO(2)

NAME top

       rt_sigqueueinfo, rt_tgsigqueueinfo - queue a signal and data

SYNOPSIS top

       int rt_sigqueueinfo(pid_t tgid, int sig, siginfo_t *uinfo);

       int rt_tgsigqueueinfo(pid_t tgid, pid_t tid, int sig,
                             siginfo_t *uinfo);

       Note: There are no glibc wrappers for these system calls; see NOTES.

DESCRIPTION top

       The rt_sigqueueinfo() and rt_tgsigqueueinfo() system calls are the low-
       level interfaces used to send a signal plus data to a process or thread.
       The receiver of the signal can obtain the accompanying data by establishing
       a signal handler with the sigaction(2) SA_SIGINFO flag.

       These system calls are not intended for direct application use; they are
       provided to allow the implementation of sigqueue(3) and
       pthread_sigqueue(3).

       The rt_sigqueueinfo() system call sends the signal sig to the thread group
       with the ID tgid.  (The term "thread group" is synonymous with "process",
       and tid corresponds to the traditional UNIX process ID.)  The signal will
       be delivered to an arbitrary member of the thread group (i.e., one of the
       threads that is not currently blocking the signal).

       The uinfo argument specifies the data to accompany the signal.  This
       argument is a pointer to a structure of type siginfo_t, described in
       sigaction(2) (and defined by including <sigaction.h>).  The caller should
       set the following fields in this structure:

       si_code
              This must be one of the SI_* codes in the Linux kernel source file
              include/asm-generic/siginfo.h, with the restriction that the code
              must be negative (i.e., cannot be SI_USER, which is used by the
              kernel to indicate a signal sent by kill(2)) and cannot (since Linux
              2.6.39) be SI_TKILL (which is used by the kernel to indicate a
              signal sent using tgkill(2)).

       si_pid This should be set to a process ID, typically the process ID of the
              sender.

       si_uid This should be set to a user ID, typically the real user ID of the
              sender.

       si_value
              This field contains the user data to accompany the signal.  For more
              information, see the description of the last (union sigval) argument
              of sigqueue(3).

       Internally, the kernel sets the si_signo field to the value specified in
       sig, so that the receiver of the signal can also obtain the signal number
       via that field.

       The rt_tgsigqueueinfo() system call is like rt_sigqueueinfo(), but sends
       the signal and data to the single thread specified by the combination of
       tgid, a thread group ID, and tid, a thread in that thread group.

RETURN VALUE top

       On success, these system calls return 0.  On error, they return -1 and
       errno is set to indicate the error.

ERRORS top

       EAGAIN The limit of signals which may be queued has been reached.  (See
              signal(7) for further information.)

       EINVAL sig, tgid, or tid was invalid.

       EPERM  The caller does not have permission to send the signal to the
              target.  For the required permissions, see kill(2).  Or:
              uinfo->si_code is invalid.

       ESRCH  rt_sigqueueinfo(): No thread group matching tgid was found.
              rt_tgsigqueinfo(): No thread matching tgid and tid was found.

VERSIONS top

       The rt_sigqueueinfo() system call was added to Linux in version 2.2.  The
       rt_tgsigqueueinfo() system call was added to Linux in version 2.6.31.

CONFORMING TO top

       These system calls are Linux-specific.

NOTES top

       Since these system calls are not intended for application use, there are no
       glibc wrapper functions; use syscall(2) in the unlikely case that you want
       to call them directly.

       As with kill(2), the null signal (0) can be used to check if the specified
       process or thread exists.

SEE ALSO top

       kill(2), sigaction(2), sigprocmask(2), tgkill(2), pthread_sigqueue(3),
       sigqueue(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                  RT_SIGQUEUEINFO(2)


sigreturn(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGRETURN(2)                 Linux Programmer's Manual                SIGRETURN(2)

NAME top

       sigreturn - return from signal handler and cleanup stack frame

SYNOPSIS top

       int sigreturn(unsigned long __unused);

DESCRIPTION top

       When the Linux kernel creates the stack frame for a signal handler, a call
       to sigreturn() is inserted into the stack frame so that upon return from
       the signal handler, sigreturn() will be called.

       This sigreturn() call undoes everything that was done--changing the
       process's signal mask, switching stacks (see sigaltstack(2))--in order to
       invoke the signal handler: it restores the process's signal mask, switches
       stacks, and restores the process's context (registers, processor flags), so
       that the process directly resumes execution at the point where it was
       interrupted by the signal.

RETURN VALUE top

       sigreturn() never returns.

FILES top

       /usr/src/linux/arch/i386/kernel/signal.c
       /usr/src/linux/arch/alpha/kernel/entry.S

CONFORMING TO top

       sigreturn() is specific to Linux and should not be used in programs
       intended to be portable.

NOTES top

       The sigreturn() call is used by the kernel to implement signal handlers.
       It should never be called directly.  Better yet, the specific use of the
       __unused argument varies depending on the architecture.

SEE ALSO top

       kill(2), sigaltstack(2), signal(2), signal(7)

COLOPHON top

       This page is part of release 3.45 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-06-26                        SIGRETURN(2)


sigsuspend(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGSUSPEND(2)                Linux Programmer's Manual               SIGSUSPEND(2)

NAME top

       sigsuspend - wait for a signal

SYNOPSIS top

       #include <signal.h>

       int sigsuspend(const sigset_t *mask);

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

       sigsuspend(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       sigsuspend() temporarily replaces the signal mask of the calling process
       with the mask given by mask and then suspends the process until delivery of
       a signal whose action is to invoke a signal handler or to terminate a
       process.

       If the signal terminates the process, then sigsuspend() does not return.
       If the signal is caught, then sigsuspend() returns after the signal handler
       returns, and the signal mask is restored to the state before the call to
       sigsuspend().

       It is not possible to block SIGKILL or SIGSTOP; specifying these signals in
       mask, has no effect on the process's signal mask.

RETURN VALUE top

       sigsuspend() always returns -1, normally with the error EINTR.

ERRORS top

       EFAULT mask points to memory which is not a valid part of the process
              address space.

       EINTR  The call was interrupted by a signal.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Normally, sigsuspend() is used in conjunction with sigprocmask(2) in order
       to prevent delivery of a signal during the execution of a critical code
       section.  The caller first blocks the signals with sigprocmask(2).  When
       the critical code has completed, the caller then waits for the signals by
       calling sigsuspend() with the signal mask that was returned by
       sigprocmask(2) (in the oldset argument).

       See sigsetops(3) for details on manipulating signal sets.

SEE ALSO top

       kill(2), pause(2), sigaction(2), signal(2), sigprocmask(2), sigwaitinfo(2),
       sigsetops(3), sigwait(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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-29                       SIGSUSPEND(2)


sigwaitinfo(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGWAITINFO(2)               Linux Programmer's Manual              SIGWAITINFO(2)

NAME top

       sigwaitinfo, sigtimedwait - synchronously wait for queued signals

SYNOPSIS top

       #include <signal.h>

       int sigwaitinfo(const sigset_t *set, siginfo_t *info);

       int sigtimedwait(const sigset_t *set, siginfo_t *info,
                        const struct timespec *timeout);

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

       sigwaitinfo(), sigtimedwait(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       sigwaitinfo() suspends execution of the calling thread until one of the
       signals in set is pending (If one of the signals in set is already pending
       for the calling thread, sigwaitinfo() will return immediately.)

       sigwaitinfo() removes the signal from the set of pending signals and
       returns the signal number as its function result.  If the info argument is
       not NULL, then the buffer that it points to is used to return a structure
       of type siginfo_t (see sigaction(2)) containing information about the
       signal.

       If multiple signals in set are pending for the caller, the signal that is
       retrieved by sigwaitinfo() is determined according to the usual ordering
       rules; see signal(7) for further details.

       sigtimedwait() operates in exactly the same way as sigwaitinfo() except
       that it has an additional argument, timeout, which specifies a minimum
       interval for which the thread is suspended waiting for a signal.  (This
       interval will be rounded up to the system clock granularity, and kernel
       scheduling delays mean that the interval may overrun by a small amount.)
       This argument is of the following type:

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

       If both fields of this structure are specified as 0, a poll is performed:
       sigtimedwait() returns immediately, either with information about a signal
       that was pending for the caller, or with an error if none of the signals in
       set was pending.

RETURN VALUE top

       On success, both sigwaitinfo() and sigtimedwait() return a signal number
       (i.e., a value greater than zero).  On failure both calls return -1, with
       errno set to indicate the error.

ERRORS top

       EAGAIN No signal in set was became pending within the timeout period
              specified to sigtimedwait().

       EINTR  The wait was interrupted by a signal handler; see signal(7).  (This
              handler was for a signal other than one of those in set.)

       EINVAL timeout was invalid.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       In normal usage, the calling program blocks the signals in set via a prior
       call to sigprocmask(2) (so that the default disposition for these signals
       does not occur if they become pending between successive calls to
       sigwaitinfo() or sigtimedwait()) and does not establish handlers for these
       signals.  In a multithreaded program, the signal should be blocked in all
       threads, in order to prevent the signal being treated according to its
       default disposition in a thread other than the one calling sigwaitinfo() or
       sigtimedwait()).

       The set of signals that is pending for a given thread is the union of the
       set of signals that is pending specifically for that thread and the set of
       signals that is pending for the process as a whole (see signal(7)).

       Attempts to wait for SIGKILL and SIGSTOP are silently ignored.

       If multiple threads of a process are blocked waiting for the same signal(s)
       in sigwaitinfo() or sigtimedwait(), then exactly one of the threads will
       actually receive the signal if it becomes pending for the process as a
       whole; which of the threads receives the signal is indeterminate.

       POSIX leaves the meaning of a NULL value for the timeout argument of
       sigtimedwait() unspecified, permitting the possibility that this has the
       same meaning as a call to sigwaitinfo(), and indeed this is what is done on
       Linux.

       On Linux, sigwaitinfo() is a library function implemented on top of
       sigtimedwait().

SEE ALSO top

       kill(2), sigaction(2), signal(2), signalfd(2), sigpending(2),
       sigprocmask(2), sigqueue(3), sigsetops(3), sigwait(3), signal(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-21                      SIGWAITINFO(2)


s390_runtime_instr(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

S390_RUNTIME_INSTR(2)                                        S390_RUNTIME_INSTR(2)

NAME top

       s390_runtime_instr - enable/disable s390 CPU run-time instrumentation

SYNOPSIS top

       #include <asm/runtime_instr.h>

       int s390_runtime_instr(int command, int signum);

DESCRIPTION top

       The s390_runtime_instr() system call starts or stops CPU run-time
       instrumentation for the calling thread.

       The command argument controls whether run-time instrumentation is started
       (S390_RUNTIME_INSTR_START, 1) or stopped (S390_RUNTIME_INSTR_STOP, 2) for
       the calling thread.

       The signum argument specifies the number of a real-time signal.  The real-
       time signal is sent to the thread if the run-time instrumentation buffer is
       full or if the run-time-instrumentation-halted interrupt occurred.

RETURN VALUE top

       On success, s390_runtime_instr() returns 0 and enables the thread for run-
       time instrumentation by assigning the thread a default run-time
       instrumentation control block.  The caller can then read and modify the
       control block and start the run-time instrumentation.  On error, -1 is
       returned and errno is set to one of the error codes listed below.

ERRORS top

       EINVAL The value specified in command is not a valid command or the value
              specified in signum is not a real-time signal number.

       ENOMEM Allocating memory for the run-time instrumentation control block
              failed.

       EOPNOTSUPP
              The run-time instrumentation facility is not available.

VERSIONS top

       This system call is available since Linux 3.7.

CONFORMING TO top

       This Linux-specific system call is only available on the s390 architecture.
       The run-time instrumentation facility is available beginning with System z
       EC12.

NOTES top

       Glibc does not provide a wrapper for this system call, use syscall(2) to
       call it.

SEE ALSO top

       syscall(2), signal(7)

COLOPHON top

       This page is part of release 3.45 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 Programmer's Manual           2012-12-17               S390_RUNTIME_INSTR(2)


scalb(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SCALB(3)                     Linux Programmer's Manual                    SCALB(3)

NAME top

       scalb, scalbf, scalbl - multiply floating-point number by integral power of
       radix (OBSOLETE)

SYNOPSIS top

       #include <math.h>

       double scalb(double x, double exp);
       float scalbf(float x, double exp);
       long double scalbl(long double x, double exp);

       Link with -lm.

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

       scalb():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
       scalbf(), scalbl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600

DESCRIPTION top

       These functions multiply their first argument x by FLT_RADIX (probably 2)
       to the power of exp, that is:

           x * FLT_RADIX ** exp

       The definition of FLT_RADIX can be obtained by including <float.h>.

RETURN VALUE top

       On success, these functions return x * FLT_RADIX ** exp.

       If x or exp is a NaN, a NaN is returned.

       If x is positive infinity (negative infinity), and exp is not negative
       infinity, positive infinity (negative infinity) is returned.

       If x is +0 (-0), and exp is not positive infinity, +0 (-0) is returned.

       If x is zero, and exp is positive infinity, a domain error occurs, and a
       NaN is returned.

       If x is an infinity, and exp is negative infinity, a domain error occurs,
       and a NaN is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with a sign the same as x.

       If the result underflows, a range error occurs, and the functions return
       zero, with a sign the same as x.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is 0, and exp is positive infinity, or x is positive
       infinity and exp is negative infinity and the other argument is not a NaN
              An invalid floating-point exception (FE_INVALID) is raised.

       Range error, overflow
              An overflow floating-point exception (FE_OVERFLOW) is raised.

       Range error, underflow
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

       These functions do not set errno.

CONFORMING TO top

       scalb() is specified in POSIX.1-2001, but marked obsolescent.  POSIX.1-2008
       removes the specification of scalb(), recommending the use of scalbln(3),
       scalblnf(3), or scalblnl(3) instead.  The scalb() function is from 4.3BSD.

       scalbf() and scalbl() are unstandardized; scalbf() is nevertheless present
       on several other systems

SEE ALSO top

       ldexp(3), scalbln(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            SCALB(3)


scalbln(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SCALBLN(3)                   Linux Programmer's Manual                  SCALBLN(3)

NAME top

       scalbn,  scalbnf, scalbnl, scalbln, scalblnf, scalblnl - multiply floating-
       point number by integral power of radix

SYNOPSIS top

       #include <math.h>

       double scalbln(double x, long int exp);
       float scalblnf(float x, long int exp);
       long double scalblnl(long double x, long int exp);

       double scalbn(double x, int exp);
       float scalbnf(float x, int exp);
       long double scalbnl(long double x, int exp);

       Link with -lm.

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

       scalbln(), scalblnf(), scalblnl():
              _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
              _POSIX_C_SOURCE >= 200112L;
              or cc -std=c99
       scalbn(), scalbnf(), scalbnl():
              _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 ||
              _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
              or cc -std=c99

DESCRIPTION top

       These functions multiply their first argument x by FLT_RADIX (probably 2)
       to the power of exp, that is:

           x * FLT_RADIX ** exp

       The definition of FLT_RADIX can be obtained by including <float.h>.

RETURN VALUE top

       On success, these functions return x * FLT_RADIX ** exp.

       If x is a NaN, a NaN is returned.

       If x is positive infinity (negative infinity), positive infinity (negative
       infinity) is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with a sign the same as x.

       If the result underflows, a range error occurs, and the functions return
       zero, with a sign the same as x.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error, overflow
              An overflow floating-point exception (FE_OVERFLOW) is raised.

       Range error, underflow
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       These functions differ from the obsolete functions described in scalb(3) in
       the type of their second argument.  The functions described on this page
       have a second argument of an integral type, while those in scalb(3) have a
       second argument of type double.

       If FLT_RADIX equals 2 (which is usual), then scalbn() is equivalent to
       ldexp(3).

SEE ALSO top

       ldexp(3), scalb(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                          SCALBLN(3)


scandirat(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SCANDIRAT(3)                 Linux Programmer's Manual                SCANDIRAT(3)

NAME top

       scandirat - scan a directory relative to a directory file descriptor

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */

       #include <fcntl.h>          /* Definition of AT_* constants */
       #include <dirent.h>

       int scandirat(int dirfd, const char *dirp, struct dirent ***namelist,
              int (*filter)(const struct dirent *),
              int (*compar)(const struct dirent **, const struct dirent **));

DESCRIPTION top

       The scandirat() system call operates in exactly the same way as scandir(3),
       except for the differences described in this manual page.

       If the pathname given in dirp is relative, then it is interpreted relative
       to the directory referred to by the file descriptor dirfd (rather than
       relative to the current working directory of the calling process, as is
       done by scandir(3) for a relative pathname).

       If dirp is relative and dirfd is the special value AT_FDCWD, then dirp is
       interpreted relative to the current working directory of the calling
       process (like scandir(3)).

       If dirp is absolute, then dirfd is ignored.

RETURN VALUE top

       On success, scandirat() returns the number of directory entries selected.
       On error, -1 is returned and errno is set to indicate the error.

ERRORS top

       The same errors that occur for scandir(3) can also occur for scandirat().
       The following additional errors can occur for scandirat():

       EBADF  dirfd is not a valid file descriptor.

       ENOTDIR
              dirp is a relative path and dirfd is a file descriptor referring to
              a file other than a directory.

VERSIONS top

       scandirat() was added to glibc in version 2.15.

CONFORMING TO top

       This function is a GNU extension.

NOTES top

       See openat(2) for an explanation of the need for scandirat().

SEE ALSO top

       openat(2), scandir(3), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-17                        SCANDIRAT(3)


sched_setaffinity(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_SETAFFINITY(2)         Linux Programmer's Manual        SCHED_SETAFFINITY(2)

NAME top

       sched_setaffinity, sched_getaffinity - set and get a process's CPU affinity
       mask

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sched.h>

       int sched_setaffinity(pid_t pid, size_t cpusetsize,
                             cpu_set_t *mask);

       int sched_getaffinity(pid_t pid, size_t cpusetsize,
                             cpu_set_t *mask);

DESCRIPTION top

       A process's CPU affinity mask determines the set of CPUs on which it is
       eligible to run.  On a multiprocessor system, setting the CPU affinity mask
       can be used to obtain performance benefits.  For example, by dedicating one
       CPU to a particular process (i.e., setting the affinity mask of that
       process to specify a single CPU, and setting the affinity mask of all other
       processes to exclude that CPU), it is possible to ensure maximum execution
       speed for that process.  Restricting a process to run on a single CPU also
       avoids the performance cost caused by the cache invalidation that occurs
       when a process ceases to execute on one CPU and then recommences execution
       on a different CPU.

       A CPU affinity mask is represented by the cpu_set_t structure, a "CPU set",
       pointed to by mask.  A set of macros for manipulating CPU sets is described
       in CPU_SET(3).

       sched_setaffinity() sets the CPU affinity mask of the process whose ID is
       pid to the value specified by mask.  If pid is zero, then the calling
       process is used.  The argument cpusetsize is the length (in bytes) of the
       data pointed to by mask.  Normally this argument would be specified as
       sizeof(cpu_set_t).

       If the process specified by pid is not currently running on one of the CPUs
       specified in mask, then that process is migrated to one of the CPUs
       specified in mask.

       sched_getaffinity() writes the affinity mask of the process whose ID is pid
       into the cpu_set_t structure pointed to by mask.  The cpusetsize argument
       specifies the size (in bytes) of mask.  If pid is zero, then the mask of
       the calling process is returned.

RETURN VALUE top

       On success, sched_setaffinity() and sched_getaffinity() return 0.  On
       error, -1 is returned, and errno is set appropriately.

ERRORS top

       EFAULT A supplied memory address was invalid.

       EINVAL The affinity bit mask mask contains no processors that are currently
              physically on the system and permitted to the process according to
              any restrictions that may be imposed by the "cpuset" mechanism
              described in cpuset(7).

       EINVAL (sched_getaffinity() and, in kernels before 2.6.9,
              sched_setaffinity()) cpusetsize is smaller than the size of the
              affinity mask used by the kernel.

       EPERM  (sched_setaffinity()) The calling process does not have appropriate
              privileges.  The caller needs an effective user ID equal to the real
              user ID or effective user ID of the process identified by pid, or it
              must possess the CAP_SYS_NICE capability.

       ESRCH  The process whose ID is pid could not be found.

VERSIONS top

       The CPU affinity system calls were introduced in Linux kernel 2.5.8.  The
       system call wrappers were introduced in glibc 2.3.  Initially, the glibc
       interfaces included a cpusetsize argument, typed as unsigned int.  In glibc
       2.3.3, the cpusetsize argument was removed, but was then restored in glibc
       2.3.4, with type size_t.

CONFORMING TO top

       These system calls are Linux-specific.

NOTES top

       After a call to sched_setaffinity(), the set of CPUs on which the process
       will actually run is the intersection of the set specified in the mask
       argument and the set of CPUs actually present on the system.  The system
       may further restrict the set of CPUs on which the process runs if the
       "cpuset" mechanism described in cpuset(7) is being used.  These
       restrictions on the actual set of CPUs on which the process will run are
       silently imposed by the kernel.

       sched_setscheduler(2) has a description of the Linux scheduling scheme.

       The affinity mask is actually a per-thread attribute that can be adjusted
       independently for each of the threads in a thread group.  The value
       returned from a call to gettid(2) can be passed in the argument pid.
       Specifying pid as 0 will set the attribute for the calling thread, and
       passing the value returned from a call to getpid(2) will set the attribute
       for the main thread of the thread group.  (If you are using the POSIX
       threads API, then use pthread_setaffinity_np(3) instead of
       sched_setaffinity().)

       A child created via fork(2) inherits its parent's CPU affinity mask.  The
       affinity mask is preserved across an execve(2).

       This manual page describes the glibc interface for the CPU affinity calls.
       The actual system call interface is slightly different, with the mask being
       typed as unsigned long *, reflecting the fact that the underlying
       implementation of CPU sets is a simple bit mask.  On success, the raw
       sched_getaffinity() system call returns the size (in bytes) of the
       cpumask_t data type that is used internally by the kernel to represent the
       CPU set bit mask.

SEE ALSO top

       clone(2), getcpu(2), getpriority(2), gettid(2), nice(2),
       sched_get_priority_max(2), sched_get_priority_min(2),
       sched_getscheduler(2), sched_setscheduler(2), setpriority(2), CPU_SET(3),
       pthread_setaffinity_np(3), sched_getcpu(3), capabilities(7), cpuset(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-06                SCHED_SETAFFINITY(2)


sched_getcpu(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_GETCPU(3)              Linux Programmer's Manual             SCHED_GETCPU(3)

NAME top

       sched_getcpu - determine CPU on which the calling thread is running

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <sched.h>

       int sched_getcpu(void);

DESCRIPTION top

       sched_getcpu() returns the number of the CPU on which the calling thread is
       currently executing.

RETURN VALUE top

       On success, sched_getcpu() returns a nonnegative CPU number.  On error, -1
       is returned and errno is set to indicate the error.

ERRORS top

       ENOSYS This kernel does not implement getcpu(2).

VERSIONS top

       This function is available since glibc 2.6.

CONFORMING TO top

       sched_getcpu() is glibc specific.

NOTES top

       The call

           cpu = sched_getcpu();

       is equivalent to the following getcpu(2) call:

           int c, s;
           s = getcpu(&c, NULL, NULL);
           cpu = (s == -1) ? s : c;

SEE ALSO top

       getcpu(2)

COLOPHON top

       This page is part of release 3.45 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                               2010-10-31                     SCHED_GETCPU(3)


sched_setparam(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_SETPARAM(2)            Linux Programmer's Manual           SCHED_SETPARAM(2)

NAME top

       sched_setparam, sched_getparam - set and get scheduling parameters

SYNOPSIS top

       #include <sched.h>

       int sched_setparam(pid_t pid, const struct sched_param *param);

       int sched_getparam(pid_t pid, struct sched_param *param);

       struct sched_param {
           ...
           int sched_priority;
           ...
       };

DESCRIPTION top

       sched_setparam() sets the scheduling parameters associated with the
       scheduling policy for the process identified by pid.  If pid is zero, then
       the parameters of the calling process are set.  The interpretation of the
       argument param depends on the scheduling policy of the process identified
       by pid.  See sched_setscheduler(2) for a description of the scheduling
       policies supported under Linux.

       sched_getparam() retrieves the scheduling parameters for the process
       identified by pid.  If pid is zero, then the parameters of the calling
       process are retrieved.

       sched_setparam() checks the validity of param for the scheduling policy of
       the process.  The value param->sched_priority must lie within the range
       given by sched_get_priority_min(2) and sched_get_priority_max(2).

       For a discussion of the privileges and resource limits related to
       scheduling priority and policy, see sched_setscheduler(2).

       POSIX systems on which sched_setparam() and sched_getparam() are available
       define _POSIX_PRIORITY_SCHEDULING in <unistd.h>.

RETURN VALUE top

       On success, sched_setparam() and sched_getparam() return 0.  On error, -1
       is returned, and errno is set appropriately.

ERRORS top

       EINVAL The argument param does not make sense for the current scheduling
              policy.

       EPERM  The calling process does not have appropriate privileges (Linux:
              does not have the CAP_SYS_NICE capability).

       ESRCH  The process whose ID is pid could not be found.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       getpriority(2), nice(2), sched_get_priority_max(2),
       sched_get_priority_min(2), sched_getaffinity(2), sched_getscheduler(2),
       sched_setaffinity(2), sched_setscheduler(2), setpriority(2),
       capabilities(7)

       Programming for the real world - POSIX.4 by Bill O. Gallmeister, O'Reilly &
       Associates, Inc., ISBN 1-56592-074-0.

COLOPHON top

       This page is part of release 3.45 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                               2006-03-23                   SCHED_SETPARAM(2)


sched_setscheduler(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_SETSCHEDULER(2)        Linux Programmer's Manual       SCHED_SETSCHEDULER(2)

NAME top

       sched_setscheduler,  sched_getscheduler  -  set  and  get  scheduling  pol-
       icy/parameters

SYNOPSIS top

       #include <sched.h>

       int sched_setscheduler(pid_t pid, int policy,
                              const struct sched_param *param);

       int sched_getscheduler(pid_t pid);

       struct sched_param {
           ...
           int sched_priority;
           ...
       };

DESCRIPTION top

       sched_setscheduler() sets both the scheduling policy and the associated
       parameters for the process whose ID is specified in pid.  If pid equals
       zero, the scheduling policy and parameters of the calling process will be
       set.  The interpretation of the argument param depends on the selected
       policy.  Currently, Linux supports the following "normal" (i.e., non-real-
       time) scheduling policies:

       SCHED_OTHER   the standard round-robin time-sharing policy;

       SCHED_BATCH   for "batch" style execution of processes; and

       SCHED_IDLE    for running very low priority background jobs.

       The following "real-time" policies are also supported, for special time-
       critical applications that need precise control over the way in which
       runnable processes are selected for execution:

       SCHED_FIFO    a first-in, first-out policy; and

       SCHED_RR      a round-robin policy.

       The semantics of each of these policies are detailed below.

       sched_getscheduler() queries the scheduling policy currently applied to the
       process identified by pid.  If pid equals zero, the policy of the calling
       process will be retrieved.

Scheduling Policies

       The scheduler is the kernel component that decides which runnable process
       will be executed by the CPU next.  Each process has an associated
       scheduling policy and a static scheduling priority, sched_priority; these
       are the settings that are modified by sched_setscheduler().  The scheduler
       makes it decisions based on knowledge of the scheduling policy and static
       priority of all processes on the system.

       For processes scheduled under one of the normal scheduling policies
       (SCHED_OTHER, SCHED_IDLE, SCHED_BATCH), sched_priority is not used in
       scheduling decisions (it must be specified as 0).

       Processes scheduled under one of the real-time policies (SCHED_FIFO,
       SCHED_RR) have a sched_priority value in the range 1 (low) to 99 (high).
       (As the numbers imply, real-time processes always have higher priority than
       normal processes.)  Note well: POSIX.1-2001 only requires an implementation
       to support a minimum 32 distinct priority levels for the real-time
       policies, and some systems supply just this minimum.  Portable programs
       should use sched_get_priority_min(2) and sched_get_priority_max(2) to find
       the range of priorities supported for a particular policy.

       Conceptually, the scheduler maintains a list of runnable processes for each
       possible sched_priority value.  In order to determine which process runs
       next, the scheduler looks for the nonempty list with the highest static
       priority and selects the process at the head of this list.

       A process's scheduling policy determines where it will be inserted into the
       list of processes with equal static priority and how it will move inside
       this list.

       All scheduling is preemptive: if a process with a higher static priority
       becomes ready to run, the currently running process will be preempted and
       returned to the wait list for its static priority level.  The scheduling
       policy only determines the ordering within the list of runnable processes
       with equal static priority.

SCHED_FIFO: First In-First Out scheduling

       SCHED_FIFO can only be used with static priorities higher than 0, which
       means that when a SCHED_FIFO processes becomes runnable, it will always
       immediately preempt any currently running SCHED_OTHER, SCHED_BATCH, or
       SCHED_IDLE process.  SCHED_FIFO is a simple scheduling algorithm without
       time slicing.  For processes scheduled under the SCHED_FIFO policy, the
       following rules apply:

       *  A SCHED_FIFO process that has been preempted by another process of
          higher priority will stay at the head of the list for its priority and
          will resume execution as soon as all processes of higher priority are
          blocked again.

       *  When a SCHED_FIFO process becomes runnable, it will be inserted at the
          end of the list for its priority.

       *  A call to sched_setscheduler() or sched_setparam(2) will put the
          SCHED_FIFO (or SCHED_RR) process identified by pid at the start of the
          list if it was runnable.  As a consequence, it may preempt the currently
          running process if it has the same priority.  (POSIX.1-2001 specifies
          that the process should go to the end of the list.)

       *  A process calling sched_yield(2) will be put at the end of the list.

       No other events will move a process scheduled under the SCHED_FIFO policy
       in the wait list of runnable processes with equal static priority.

       A SCHED_FIFO process runs until either it is blocked by an I/O request, it
       is preempted by a higher priority process, or it calls sched_yield(2).

SCHED_RR: Round Robin scheduling

       SCHED_RR is a simple enhancement of SCHED_FIFO.  Everything described above
       for SCHED_FIFO also applies to SCHED_RR, except that each process is only
       allowed to run for a maximum time quantum.  If a SCHED_RR process has been
       running for a time period equal to or longer than the time quantum, it will
       be put at the end of the list for its priority.  A SCHED_RR process that
       has been preempted by a higher priority process and subsequently resumes
       execution as a running process will complete the unexpired portion of its
       round robin time quantum.  The length of the time quantum can be retrieved
       using sched_rr_get_interval(2).

SCHED_OTHER: Default Linux time-sharing scheduling

       SCHED_OTHER can only be used at static priority 0.  SCHED_OTHER is the
       standard Linux time-sharing scheduler that is intended for all processes
       that do not require the special real-time mechanisms.  The process to run
       is chosen from the static priority 0 list based on a dynamic priority that
       is determined only inside this list.  The dynamic priority is based on the
       nice value (set by nice(2) or setpriority(2)) and increased for each time
       quantum the process is ready to run, but denied to run by the scheduler.
       This ensures fair progress among all SCHED_OTHER processes.

SCHED_BATCH: Scheduling batch processes

       (Since Linux 2.6.16.)  SCHED_BATCH can only be used at static priority 0.
       This policy is similar to SCHED_OTHER in that it schedules the process
       according to its dynamic priority (based on the nice value).  The
       difference is that this policy will cause the scheduler to always assume
       that the process is CPU-intensive.  Consequently, the scheduler will apply
       a small scheduling penalty with respect to wakeup behaviour, so that this
       process is mildly disfavored in scheduling decisions.

       This policy is useful for workloads that are noninteractive, but do not
       want to lower their nice value, and for workloads that want a deterministic
       scheduling policy without interactivity causing extra preemptions (between
       the workload's tasks).

SCHED_IDLE: Scheduling very low priority jobs

       (Since Linux 2.6.23.)  SCHED_IDLE can only be used at static priority 0;
       the process nice value has no influence for this policy.

       This policy is intended for running jobs at extremely low priority (lower
       even than a +19 nice value with the SCHED_OTHER or SCHED_BATCH policies).

Resetting scheduling policy for child processes

       Since Linux 2.6.32, the SCHED_RESET_ON_FORK flag can be ORed in policy when
       calling sched_setscheduler().  As a result of including this flag, children
       created by fork(2) do not inherit privileged scheduling policies.  This
       feature is intended for media-playback applications, and can be used to
       prevent applications evading the RLIMIT_RTTIME resource limit (see
       getrlimit(2)) by creating multiple child processes.

       More precisely, if the SCHED_RESET_ON_FORK flag is specified, the following
       rules apply for subsequently created children:

       *  If the calling process has a scheduling policy of SCHED_FIFO or
          SCHED_RR, the policy is reset to SCHED_OTHER in child processes.

       *  If the calling process has a negative nice value, the nice value is
          reset to zero in child processes.

       After the SCHED_RESET_ON_FORK flag has been enabled, it can only be reset
       if the process has the CAP_SYS_NICE capability.  This flag is disabled in
       child processes created by fork(2).

       The SCHED_RESET_ON_FORK flag is visible in the policy value returned by
       sched_getscheduler()

Privileges and resource limits

       In Linux kernels before 2.6.12, only privileged (CAP_SYS_NICE) processes
       can set a nonzero static priority (i.e., set a real-time scheduling
       policy).  The only change that an unprivileged process can make is to set
       the SCHED_OTHER policy, and this can only be done if the effective user ID
       of the caller of sched_setscheduler() matches the real or effective user ID
       of the target process (i.e., the process specified by pid) whose policy is
       being changed.

       Since Linux 2.6.12, the RLIMIT_RTPRIO resource limit defines a ceiling on
       an unprivileged process's static priority for the SCHED_RR and SCHED_FIFO
       policies.  The rules for changing scheduling policy and priority are as
       follows:

       *  If an unprivileged process has a nonzero RLIMIT_RTPRIO soft limit, then
          it can change its scheduling policy and priority, subject to the
          restriction that the priority cannot be set to a value higher than the
          maximum of its current priority and its RLIMIT_RTPRIO soft limit.

       *  If the RLIMIT_RTPRIO soft limit is 0, then the only permitted changes
          are to lower the priority, or to switch to a non-real-time policy.

       *  Subject to the same rules, another unprivileged process can also make
          these changes, as long as the effective user ID of the process making
          the change matches the real or effective user ID of the target process.

       *  Special rules apply for the SCHED_IDLE.  In Linux kernels before 2.6.39,
          an unprivileged process operating under this policy cannot change its
          policy, regardless of the value of its RLIMIT_RTPRIO resource limit.  In
          Linux kernels since 2.6.39, an unprivileged process can switch to either
          the SCHED_BATCH or the SCHED_NORMAL policy so long as its nice value
          falls within the range permitted by its RLIMIT_NICE resource limit (see
          getrlimit(2)).

       Privileged (CAP_SYS_NICE) processes ignore the RLIMIT_RTPRIO limit; as with
       older kernels, they can make arbitrary changes to scheduling policy and
       priority.  See getrlimit(2) for further information on RLIMIT_RTPRIO.

Response time

       A blocked high priority process waiting for the I/O has a certain response
       time before it is scheduled again.  The device driver writer can greatly
       reduce this response time by using a "slow interrupt" interrupt handler.

Miscellaneous

       Child processes inherit the scheduling policy and parameters across a
       fork(2).  The scheduling policy and parameters are preserved across
       execve(2).

       Memory locking is usually needed for real-time processes to avoid paging
       delays; this can be done with mlock(2) or mlockall(2).

       Since a nonblocking infinite loop in a process scheduled under SCHED_FIFO
       or SCHED_RR will block all processes with lower priority forever, a
       software developer should always keep available on the console a shell
       scheduled under a higher static priority than the tested application.  This
       will allow an emergency kill of tested real-time applications that do not
       block or terminate as expected.  See also the description of the
       RLIMIT_RTTIME resource limit in getrlimit(2).

       POSIX systems on which sched_setscheduler() and sched_getscheduler() are
       available define _POSIX_PRIORITY_SCHEDULING in <unistd.h>.

RETURN VALUE top

       On success, sched_setscheduler() returns zero.  On success,
       sched_getscheduler() returns the policy for the process (a nonnegative
       integer).  On error, -1 is returned, and errno is set appropriately.

ERRORS top

       EINVAL The scheduling policy is not one of the recognized policies, param
              is NULL, or param does not make sense for the policy.

       EPERM  The calling process does not have appropriate privileges.

       ESRCH  The process whose ID is pid could not be found.

CONFORMING TO top

       POSIX.1-2001 (but see BUGS below).  The SCHED_BATCH and SCHED_IDLE policies
       are Linux-specific.

NOTES top

       POSIX.1 does not detail the permissions that an unprivileged process
       requires in order to call sched_setscheduler(), and details vary across
       systems.  For example, the Solaris 7 manual page says that the real or
       effective user ID of the calling process must match the real user ID or the
       save set-user-ID of the target process.

       Originally, Standard Linux was intended as a general-purpose operating
       system being able to handle background processes, interactive applications,
       and less demanding real-time applications (applications that need to
       usually meet timing deadlines).  Although the Linux kernel 2.6 allowed for
       kernel preemption and the newly introduced O(1) scheduler ensures that the
       time needed to schedule is fixed and deterministic irrespective of the
       number of active tasks, true real-time computing was not possible up to
       kernel version 2.6.17.

Real-time features in the mainline Linux kernel

       From kernel version 2.6.18 onward, however, Linux is gradually becoming
       equipped with real-time capabilities, most of which are derived from the
       former realtime-preempt patches developed by Ingo Molnar, Thomas Gleixner,
       Steven Rostedt, and others.  Until the patches have been completely merged
       into the mainline kernel (this is expected to be around kernel version
       2.6.30), they must be installed to achieve the best real-time performance.
       These patches are named:

           patch-kernelversion-rtpatchversion

       and can be downloaded from <http://www.kernel.org/pub/linux/kernel/projects
       /rt/>.

       Without the patches and prior to their full inclusion into the mainline
       kernel, the kernel configuration offers only the three preemption classes
       CONFIG_PREEMPT_NONE, CONFIG_PREEMPT_VOLUNTARY, and CONFIG_PREEMPT_DESKTOP
       which respectively provide no, some, and considerable reduction of the
       worst-case scheduling latency.

       With the patches applied or after their full inclusion into the mainline
       kernel, the additional configuration item CONFIG_PREEMPT_RT becomes avail-
       able.  If this is selected, Linux is transformed into a regular real-time
       operating system.  The FIFO and RR scheduling policies that can be selected
       using sched_setscheduler() are then used to run a process with true real-
       time priority and a minimum worst-case scheduling latency.

BUGS top

       POSIX says that on success, sched_setscheduler() should return the previous
       scheduling policy.  Linux sched_setscheduler() does not conform to this
       requirement, since it always returns 0 on success.

SEE ALSO top

       getpriority(2), mlock(2), mlockall(2), munlock(2), munlockall(2), nice(2),
       sched_get_priority_max(2), sched_get_priority_min(2), sched_getaffinity(2),
       sched_getparam(2), sched_rr_get_interval(2), sched_setaffinity(2),
       sched_setparam(2), sched_yield(2), setpriority(2), capabilities(7),
       cpuset(7)

       Programming for the real world - POSIX.4 by Bill O. Gallmeister, O'Reilly &
       Associates, Inc., ISBN 1-56592-074-0.

       Documentation/scheduler/sched-rt-group.txt  in the Linux kernel source tree
       (since kernel 2.6.25).

COLOPHON top

       This page is part of release  3.45  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                               2012-08-05               SCHED_SETSCHEDULER(2)


sched_get_priority_max(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_GET_PRIORITY_MAX(2)    Linux Programmer's Manual   SCHED_GET_PRIORITY_MAX(2)

NAME top

       sched_get_priority_max, sched_get_priority_min  - get static priority range

SYNOPSIS top

       #include <sched.h>

       int sched_get_priority_max(int policy);

       int sched_get_priority_min(int policy);

DESCRIPTION top

       sched_get_priority_max() returns the maximum priority value that can be
       used with the scheduling algorithm identified by policy.
       sched_get_priority_min() returns the minimum priority value that can be
       used with the scheduling algorithm identified by policy.  Supported policy
       values are SCHED_FIFO, SCHED_RR, SCHED_OTHER, and SCHED_BATCH.  Further
       details about these policies can be found in sched_setscheduler(2).

       Processes with numerically higher priority values are scheduled before
       processes with numerically lower priority values.  Thus, the value returned
       by sched_get_priority_max() will be greater than the value returned by
       sched_get_priority_min().

       Linux allows the static priority value range 1 to 99 for SCHED_FIFO and
       SCHED_RR and the priority 0 for SCHED_OTHER and SCHED_BATCH.  Scheduling
       priority ranges for the various policies are not alterable.

       The range of scheduling priorities may vary on other POSIX systems, thus it
       is a good idea for portable applications to use a virtual priority range
       and map it to the interval given by sched_get_priority_max() and
       sched_get_priority_min().  POSIX.1-2001 requires a spread of at least 32
       between the maximum and the minimum values for SCHED_FIFO and SCHED_RR.

       POSIX systems on which sched_get_priority_max() and
       sched_get_priority_min() are available define _POSIX_PRIORITY_SCHEDULING in
       <unistd.h>.

RETURN VALUE top

       On success, sched_get_priority_max() and sched_get_priority_min() return
       the maximum/minimum priority value for the named scheduling policy.  On
       error, -1 is returned, and errno is set appropriately.

ERRORS top

       EINVAL The argument policy does not identify a defined scheduling policy.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       sched_getaffinity(2), sched_getparam(2), sched_getscheduler(2),
       sched_setaffinity(2), sched_setparam(2), sched_setscheduler(2)

       Programming for the real world - POSIX.4 by Bill O. Gallmeister, O'Reilly &
       Associates, Inc., ISBN 1-56592-074-0.

COLOPHON top

       This page is part of release 3.45 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                               2006-03-23           SCHED_GET_PRIORITY_MAX(2)


sched_rr_get_interval(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_RR_GET_INTERVAL(2)     Linux Programmer's Manual    SCHED_RR_GET_INTERVAL(2)

NAME top

       sched_rr_get_interval - get the SCHED_RR interval for the named process

SYNOPSIS top

       #include <sched.h>

       int sched_rr_get_interval(pid_t pid, struct timespec * tp);

DESCRIPTION top

       sched_rr_get_interval() writes into the timespec structure pointed to by tp
       the round-robin time quantum for the process identified by pid.  The
       specified process should be running under the SCHED_RR scheduling policy.

       The timespec structure has the following form:

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

       If pid is zero, the time quantum for the calling process is written into
       *tp.

RETURN VALUE top

       On success, sched_rr_get_interval() returns 0.  On error, -1 is returned,
       and errno is set appropriately.

ERRORS top

       EFAULT Problem with copying information to user space.

       EINVAL Invalid pid.

       ENOSYS The system call is not yet implemented (only on rather old kernels).

       ESRCH  Could not find a process with the ID pid.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       POSIX systems on which sched_rr_get_interval() is available define
       _POSIX_PRIORITY_SCHEDULING in <unistd.h>.

Linux Notes

       POSIX does not specify any mechanism for controlling the size of the round-
       robin time quantum.  Older Linux kernels provide a (nonportable) method of
       doing this.  The quantum can be controlled by adjusting the process's nice
       value (see setpriority(2)).  Assigning a negative (i.e., high) nice value
       results in a longer quantum; assigning a positive (i.e., low) nice value
       results in a shorter quantum.  The default quantum is 0.1 seconds; the
       degree to which changing the nice value affects the quantum has varied
       somewhat across kernel versions.  Since Linux 2.6.24, the SCHED_RR quantum
       cannot be modified.

SEE ALSO top

       sched_setscheduler(2) has a description of the Linux scheduling scheme.

       Programming for the real world - POSIX.4 by Bill O. Gallmeister, O'Reilly &
       Associates, Inc., ISBN 1-56592-074-0.

COLOPHON top

       This page is part of release 3.45 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                               2011-10-16            SCHED_RR_GET_INTERVAL(2)


sched_yield(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SCHED_YIELD(2)               Linux Programmer's Manual              SCHED_YIELD(2)

NAME top

       sched_yield - yield the processor

SYNOPSIS top

       #include <sched.h>

       int sched_yield(void);

DESCRIPTION top

       sched_yield() causes the calling thread to relinquish the CPU.  The thread
       is moved to the end of the queue for its static priority and a new thread
       gets to run.

RETURN VALUE top

       On success, sched_yield() returns 0.  On error, -1 is returned, and errno
       is set appropriately.

ERRORS top

       In the Linux implementation, sched_yield() always succeeds.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       If the calling thread is the only thread in the highest priority list at
       that time, it will continue to run after a call to sched_yield().

       POSIX systems on which sched_yield() is available define
       _POSIX_PRIORITY_SCHEDULING in <unistd.h>.

       Strategic calls to sched_yield() can improve performance by giving other
       threads or processes a chance to run when (heavily) contended resources
       (e.g., mutexes) have been released by the caller.  Avoid calling
       sched_yield() unnecessarily or inappropriately (e.g., when resources needed
       by other schedulable threads are still held by the caller), since doing so
       will result in unnecessary context switches, which will degrade system
       performance.

SEE ALSO top

       sched_setscheduler(2) for a description of Linux scheduling

       Programming for the real world - POSIX.4 by Bill O. Gallmeister, O'Reilly &
       Associates, Inc., ISBN 1-56592-074-0.

COLOPHON top

       This page is part of release 3.45 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-10-18                      SCHED_YIELD(2)


sd(4) - Linux manual page

NAME | SYNOPSIS | CONFIGURATION | DESCRIPTION | FILES | COLOPHON The Linux Programming Interface

SD(4)                        Linux Programmer's Manual                       SD(4)

NAME top

       sd - driver for SCSI disk drives

SYNOPSIS top

       #include <linux/hdreg.h>        /* for HDIO_GETGEO */
       #include <linux/fs.h>           /* for BLKGETSIZE and BLKRRPART */

CONFIGURATION top

       The  block  device  name  has the following form: sdlp, where l is a letter
       denoting the physical drive, and p is a number denoting  the  partition  on
       that physical drive.  Often, the partition number, p, will be left off when
       the device corresponds to the whole drive.

       SCSI disks have a major device number of 8, and a minor  device  number  of
       the  form (16 * drive_number) + partition_number, where drive_number is the
       number of the physical drive in order of detection, and partition_number is
       as follows:

       partition 0 is the whole drive
       partitions 1-4 are the DOS "primary" partitions
       partitions 5-8 are the DOS "extended" (or "logical") partitions

       For  example, /dev/sda will have major 8, minor 0, and will refer to all of
       the first SCSI drive in the system; and /dev/sdb3 will have major 8,  minor
       19,  and will refer to the third DOS "primary" partition on the second SCSI
       drive in the system.

       At this time, only block devices are provided.  Raw devices  have  not  yet
       been implemented.

DESCRIPTION top

       The following ioctls are provided:

       HDIO_GETGEO
              Returns the BIOS disk parameters in the following structure:

                  struct hd_geometry {
                      unsigned char  heads;
                      unsigned char  sectors;
                      unsigned short cylinders;
                      unsigned long  start;
                  };

              A pointer to this structure is passed as the ioctl(2) parameter.

              The information returned in the parameter is the disk geometry of
              the drive as understood by DOS!  This geometry is not the physical
              geometry of the drive.  It is used when constructing the drive's
              partition table, however, and is needed for convenient operation of
              fdisk(1), efdisk(1), and lilo(1).  If the geometry information is
              not available, zero will be returned for all of the parameters.

       BLKGETSIZE
              Returns the device size in sectors.  The ioctl(2) parameter should
              be a pointer to a long.

       BLKRRPART
              Forces a reread of the SCSI disk partition tables.  No parameter is
              needed.

              The SCSI ioctl(2) operations are also supported.  If the ioctl(2)
              parameter is required, and it is NULL, then ioctl(2) will fail with
              the error EINVAL.

FILES top

       /dev/sd[a-h]: the whole device
       /dev/sd[a-h][0-8]: individual block partitions

COLOPHON top

       This page is part of release 3.45 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                               2012-05-03                               SD(4)


securetty(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

SECURETTY(5)                 Linux Programmer's Manual                SECURETTY(5)

NAME top

       securetty - file which lists ttys from which root can log in

DESCRIPTION top

       The file /etc/securetty is used by (some versions of) login(1).  The file
       contains the device names of tty lines (one per line, without leading
       /dev/) on which root is allowed to login.  See login.defs(5) if you use the
       shadow suite.

FILES top

       /etc/securetty

SEE ALSO top

       login(1), login.defs(5)

COLOPHON top

       This page is part of release 3.45 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                               1992-12-29                        SECURETTY(5)


seekdir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SEEKDIR(3)                   Linux Programmer's Manual                  SEEKDIR(3)

NAME top

       seekdir  -  set  the  position  of the next readdir() call in the directory
       stream.

SYNOPSIS top

       #include <dirent.h>

       void seekdir(DIR *dirp, long offset);

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

       seekdir(): _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       The seekdir() function sets the location in the directory stream from which
       the next readdir(2) call will start.  seekdir() should be used with an
       offset returned by telldir(3).

RETURN VALUE top

       The seekdir() function returns no value.

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

NOTES top

       In glibc up to version 2.1.1, the type of the offset argument was off_t.
       POSIX.1-2001 specifies long, and this is the type used since glibc 2.1.2.

SEE ALSO top

       lseek(2), closedir(3), opendir(3), readdir(3), rewinddir(3), scandir(3),
       telldir(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-03-11                          SEEKDIR(3)


select_tut(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SELECT_TUT(2)                Linux Programmer's Manual               SELECT_TUT(2)

NAME top

       select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O multi-
       plexing

SYNOPSIS top

       /* According to POSIX.1-2001 */
       #include <sys/select.h>

       /* According to earlier standards */
       #include <sys/time.h>
       #include <sys/types.h>
       #include <unistd.h>

       int select(int nfds, fd_set *readfds, fd_set *writefds,
                  fd_set *exceptfds, struct timeval *utimeout);

       void FD_CLR(int fd, fd_set *set);
       int  FD_ISSET(int fd, fd_set *set);
       void FD_SET(int fd, fd_set *set);
       void FD_ZERO(fd_set *set);

       #include <sys/select.h>

       int pselect(int nfds, fd_set *readfds, fd_set *writefds,
                   fd_set *exceptfds, const struct timespec *ntimeout,
                   const sigset_t *sigmask);

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

       pselect(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       select() (or pselect()) is used to efficiently monitor multiple file
       descriptors, to see if any of them is, or becomes, "ready"; that is, to see
       whether I/O becomes possible, or an "exceptional condition" has occurred on
       any of the descriptors.

       Its principal arguments are three "sets" of file descriptors: readfds,
       writefds, and exceptfds.  Each set is declared as type fd_set, and its
       contents can be manipulated with the macros FD_CLR(), FD_ISSET(), FD_SET(),
       and FD_ZERO().  A newly declared set should first be cleared using
       FD_ZERO().  select() modifies the contents of the sets according to the
       rules described below; after calling select() you can test if a file
       descriptor is still present in a set with the FD_ISSET() macro.  FD_ISSET()
       returns nonzero if a specified file descriptor is present in a set and zero
       if it is not.  FD_CLR() removes a file descriptor from a set.

Arguments

       readfds
              This set is watched to see if data is available for reading from any
              of its file descriptors.  After select() has returned, readfds will
              be cleared of all file descriptors except for those that are
              immediately available for reading.

       writefds
              This set is watched to see if there is space to write data to any of
              its file descriptors.  After select() has returned, writefds will be
              cleared of all file descriptors except for those that are
              immediately available for writing.

       exceptfds
              This set is watched for "exceptional conditions".  In practice, only
              one such exceptional condition is common: the availability of out-
              of-band (OOB) data for reading from a TCP socket.  See recv(2),
              send(2), and tcp(7) for more details about OOB data.  (One other
              less common case where select(2) indicates an exceptional condition
              occurs with pseudoterminals in packet mode; see tty_ioctl(4).)
              After select() has returned, exceptfds will be cleared of all file
              descriptors except for those for which an exceptional condition has
              occurred.

       nfds   This is an integer one more than the maximum of any file descriptor
              in any of the sets.  In other words, while adding file descriptors
              to each of the sets, you must calculate the maximum integer value of
              all of them, then increment this value by one, and then pass this as
              nfds.

       utimeout
              This is the longest time select() may wait before returning, even if
              nothing interesting happened.  If this value is passed as NULL, then
              select() blocks indefinitely waiting for a file descriptor to become
              ready.  utimeout can be set to zero seconds, which causes select()
              to return immediately, with information about the readiness of file
              descriptors at the time of the call.  The structure struct timeval
              is defined as:

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

       ntimeout
              This argument for pselect() has the same meaning as utimeout, but
              struct timespec has nanosecond precision as follows:

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

       sigmask
              This argument holds a set of signals that the kernel should unblock
              (i.e., remove from the signal mask of the calling thread), while the
              caller is blocked inside the pselect() call (see sigaddset(3) and
              sigprocmask(2)).  It may be NULL, in which case the call does not
              modify the signal mask on entry and exit to the function.  In this
              case, pselect() will then behave just like select().

Combining Signal and Data Events

       pselect() is useful if you are waiting for a signal as well as for file
       descriptor(s) to become ready for I/O.  Programs that receive signals
       normally use the signal handler only to raise a global flag.  The global
       flag will indicate that the event must be processed in the main loop of the
       program.  A signal will cause the select() (or pselect()) call to return
       with errno set to EINTR.  This behavior is essential so that signals can be
       processed in the main loop of the program, otherwise select() would block
       indefinitely.  Now, somewhere in the main loop will be a conditional to
       check the global flag.  So we must ask: what if a signal arrives after the
       conditional, but before the select() call?  The answer is that select()
       would block indefinitely, even though an event is actually pending.  This
       race condition is solved by the pselect() call.  This call can be used to
       set the signal mask to a set of signals that are only to be received within
       the pselect() call.  For instance, let us say that the event in question
       was the exit of a child process.  Before the start of the main loop, we
       would block SIGCHLD using sigprocmask(2).  Our pselect() call would enable
       SIGCHLD by using an empty signal mask.  Our program would look like:

       static volatile sig_atomic_t got_SIGCHLD = 0;

       static void
       child_sig_handler(int sig)
       {
           got_SIGCHLD = 1;
       }

       int
       main(int argc, char *argv[])
       {
           sigset_t sigmask, empty_mask;
           struct sigaction sa;
           fd_set readfds, writefds, exceptfds;
           int r;

           sigemptyset(&sigmask);
           sigaddset(&sigmask, SIGCHLD);
           if (sigprocmask(SIG_BLOCK, &sigmask, NULL) == -1) {
               perror("sigprocmask");
               exit(EXIT_FAILURE);
           }

           sa.sa_flags = 0;
           sa.sa_handler = child_sig_handler;
           sigemptyset(&sa.sa_mask);
           if (sigaction(SIGCHLD, &sa, NULL) == -1) {
               perror("sigaction");
               exit(EXIT_FAILURE);
           }

           sigemptyset(&empty_mask);

           for (;;) {          /* main loop */
               /* Initialize readfds, writefds, and exceptfds
                  before the pselect() call. (Code omitted.) */

               r = pselect(nfds, &readfds, &writefds, &exceptfds,
                           NULL, &empty_mask);
               if (r == -1 && errno != EINTR) {
                   /* Handle error */
               }

               if (got_SIGCHLD) {
                   got_SIGCHLD = 0;

                   /* Handle signalled event here; e.g., wait() for all
                      terminated children. (Code omitted.) */
               }

               /* main body of program */
           }
       }

Practical

       So what is the point of select()?  Can't I just read and write to my
       descriptors whenever I want?  The point of select() is that it watches
       multiple descriptors at the same time and properly puts the process to
       sleep if there is no activity.  UNIX programmers often find themselves in a
       position where they have to handle I/O from more than one file descriptor
       where the data flow may be intermittent.  If you were to merely create a
       sequence of read(2) and write(2) calls, you would find that one of your
       calls may block waiting for data from/to a file descriptor, while another
       file descriptor is unused though ready for I/O.  select() efficiently copes
       with this situation.

Select Law

       Many people who try to use select() come across behavior that is difficult
       to understand and produces nonportable or borderline results.  For
       instance, the above program is carefully written not to block at any point,
       even though it does not set its file descriptors to nonblocking mode.  It
       is easy to introduce subtle errors that will remove the advantage of using
       select(), so here is a list of essentials to watch for when using select().

       1.  You should always try to use select() without a timeout.  Your program
           should have nothing to do if there is no data available.  Code that
           depends on timeouts is not usually portable and is difficult to debug.

       2.  The value nfds must be properly calculated for efficiency as explained
           above.

       3.  No file descriptor must be added to any set if you do not intend to
           check its result after the select() call, and respond appropriately.
           See next rule.

       4.  After select() returns, all file descriptors in all sets should be
           checked to see if they are ready.

       5.  The functions read(2), recv(2), write(2), and send(2) do not
           necessarily read/write the full amount of data that you have requested.
           If they do read/write the full amount, it's because you have a low
           traffic load and a fast stream.  This is not always going to be the
           case.  You should cope with the case of your functions only managing to
           send or receive a single byte.

       6.  Never read/write only in single bytes at a time unless you are really
           sure that you have a small amount of data to process.  It is extremely
           inefficient not to read/write as much data as you can buffer each time.
           The buffers in the example below are 1024 bytes although they could
           easily be made larger.

       7.  The functions read(2), recv(2), write(2), and send(2) as well as the
           select() call can return -1 with errno set to EINTR, or with errno set
           to EAGAIN (EWOULDBLOCK).  These results must be properly managed (not
           done properly above).  If your program is not going to receive any
           signals, then it is unlikely you will get EINTR.  If your program does
           not set nonblocking I/O, you will not get EAGAIN.

       8.  Never call read(2), recv(2), write(2), or send(2) with a buffer length
           of zero.

       9.  If the functions read(2), recv(2), write(2), and send(2) fail with
           errors other than those listed in 7., or one of the input functions
           returns 0, indicating end of file, then you should not pass that
           descriptor to select() again.  In the example below, I close the
           descriptor immediately, and then set it to -1 to prevent it being
           included in a set.

       10. The timeout value must be initialized with each new call to select(),
           since some operating systems modify the structure.  pselect() however
           does not modify its timeout structure.

       11. Since select() modifies its file descriptor sets, if the call is being
           used in a loop, then the sets must be reinitialized before each call.

Usleep Emulation

       On systems that do not have a usleep(3) function, you can call select()
       with a finite timeout and no file descriptors as follows:

           struct timeval tv;
           tv.tv_sec = 0;
           tv.tv_usec = 200000;  /* 0.2 seconds */
           select(0, NULL, NULL, NULL, &tv);

       This is only guaranteed to work on UNIX systems, however.

RETURN VALUE top

       On success, select() returns the total number of file descriptors still
       present in the file descriptor sets.

       If select() timed out, then the return value will be zero.  The file
       descriptors set should be all empty (but may not be on some systems).

       A return value of -1 indicates an error, with errno being set
       appropriately.  In the case of an error, the contents of the returned sets
       and the struct timeout contents are undefined and should not be used.
       pselect() however never modifies ntimeout.

NOTES top

       Generally speaking, all operating systems that support sockets also support
       select().  select() can be used to solve many problems in a portable and
       efficient way that naive programmers try to solve in a more complicated
       manner using threads, forking, IPCs, signals, memory sharing, and so on.

       The poll(2) system call has the same functionality as select(), and is
       somewhat more efficient when monitoring sparse file descriptor sets.  It is
       nowadays widely available, but historically was less portable than
       select().

       The Linux-specific epoll(7) API provides an interface that is more
       efficient than select(2) and poll(2) when monitoring large numbers of file
       descriptors.

EXAMPLE top

       Here is an example that better demonstrates the true utility of select().
       The listing below is a TCP forwarding program that forwards from one TCP
       port to another.

       #include <stdlib.h>
       #include <stdio.h>
       #include <unistd.h>
       #include <sys/time.h>
       #include <sys/types.h>
       #include <string.h>
       #include <signal.h>
       #include <sys/socket.h>
       #include <netinet/in.h>
       #include <arpa/inet.h>
       #include <errno.h>

       static int forward_port;

       #undef max
       #define max(x,y) ((x) > (y) ? (x) : (y))

       static int
       listen_socket(int listen_port)
       {
           struct sockaddr_in a;
           int s;
           int yes;

           if ((s = socket(AF_INET, SOCK_STREAM, 0)) == -1) {
               perror("socket");
               return -1;
           }
           yes = 1;
           if (setsockopt(s, SOL_SOCKET, SO_REUSEADDR,
                   &yes, sizeof(yes)) == -1) {
               perror("setsockopt");
               close(s);
               return -1;
           }
           memset(&a, 0, sizeof(a));
           a.sin_port = htons(listen_port);
           a.sin_family = AF_INET;
           if (bind(s, (struct sockaddr *) &a, sizeof(a)) == -1) {
               perror("bind");
               close(s);
               return -1;
           }
           printf("accepting connections on port %d\n", listen_port);
           listen(s, 10);
           return s;
       }

       static int
       connect_socket(int connect_port, char *address)
       {
           struct sockaddr_in a;
           int s;

           if ((s = socket(AF_INET, SOCK_STREAM, 0)) == -1) {
               perror("socket");
               close(s);
               return -1;
           }

           memset(&a, 0, sizeof(a));
           a.sin_port = htons(connect_port);
           a.sin_family = AF_INET;

           if (!inet_aton(address, (struct in_addr *) &a.sin_addr.s_addr)) {
               perror("bad IP address format");
               close(s);
               return -1;
           }

           if (connect(s, (struct sockaddr *) &a, sizeof(a)) == -1) {
               perror("connect()");
               shutdown(s, SHUT_RDWR);
               close(s);
               return -1;
           }
           return s;
       }

       #define SHUT_FD1 do {                                \
                            if (fd1 >= 0) {                 \
                                shutdown(fd1, SHUT_RDWR);   \
                                close(fd1);                 \
                                fd1 = -1;                   \
                            }                               \
                        } while (0)

       #define SHUT_FD2 do {                                \
                            if (fd2 >= 0) {                 \
                                shutdown(fd2, SHUT_RDWR);   \
                                close(fd2);                 \
                                fd2 = -1;                   \
                            }                               \
                        } while (0)

       #define BUF_SIZE 1024

       int
       main(int argc, char *argv[])
       {
           int h;
           int fd1 = -1, fd2 = -1;
           char buf1[BUF_SIZE], buf2[BUF_SIZE];
           int buf1_avail, buf1_written;
           int buf2_avail, buf2_written;

           if (argc != 4) {
               fprintf(stderr, "Usage\n\tfwd <listen-port> "
                        "<forward-to-port> <forward-to-ip-address>\n");
               exit(EXIT_FAILURE);
           }

           signal(SIGPIPE, SIG_IGN);

           forward_port = atoi(argv[2]);

           h = listen_socket(atoi(argv[1]));
           if (h == -1)
               exit(EXIT_FAILURE);

           for (;;) {
               int r, nfds = 0;
               fd_set rd, wr, er;

               FD_ZERO(&rd);
               FD_ZERO(&wr);
               FD_ZERO(&er);
               FD_SET(h, &rd);
               nfds = max(nfds, h);
               if (fd1 > 0 && buf1_avail < BUF_SIZE) {
                   FD_SET(fd1, &rd);
                   nfds = max(nfds, fd1);
               }
               if (fd2 > 0 && buf2_avail < BUF_SIZE) {
                   FD_SET(fd2, &rd);
                   nfds = max(nfds, fd2);
               }
               if (fd1 > 0 && buf2_avail - buf2_written > 0) {
                   FD_SET(fd1, &wr);
                   nfds = max(nfds, fd1);
               }
               if (fd2 > 0 && buf1_avail - buf1_written > 0) {
                   FD_SET(fd2, &wr);
                   nfds = max(nfds, fd2);
               }
               if (fd1 > 0) {
                   FD_SET(fd1, &er);
                   nfds = max(nfds, fd1);
               }
               if (fd2 > 0) {
                   FD_SET(fd2, &er);
                   nfds = max(nfds, fd2);
               }

               r = select(nfds + 1, &rd, &wr, &er, NULL);

               if (r == -1 && errno == EINTR)
                   continue;

               if (r == -1) {
                   perror("select()");
                   exit(EXIT_FAILURE);
               }

               if (FD_ISSET(h, &rd)) {
                   unsigned int l;
                   struct sockaddr_in client_address;

                   memset(&client_address, 0, l = sizeof(client_address));
                   r = accept(h, (struct sockaddr *) &client_address, &l);
                   if (r == -1) {
                       perror("accept()");
                   } else {
                       SHUT_FD1;
                       SHUT_FD2;
                       buf1_avail = buf1_written = 0;
                       buf2_avail = buf2_written = 0;
                       fd1 = r;
                       fd2 = connect_socket(forward_port, argv[3]);
                       if (fd2 == -1)
                           SHUT_FD1;
                       else
                           printf("connect from %s\n",
                                   inet_ntoa(client_address.sin_addr));
                   }
               }

               /* NB: read oob data before normal reads */

               if (fd1 > 0)
                   if (FD_ISSET(fd1, &er)) {
                       char c;

                       r = recv(fd1, &c, 1, MSG_OOB);
                       if (r < 1)
                           SHUT_FD1;
                       else
                           send(fd2, &c, 1, MSG_OOB);
                   }
               if (fd2 > 0)
                   if (FD_ISSET(fd2, &er)) {
                       char c;

                       r = recv(fd2, &c, 1, MSG_OOB);
                       if (r < 1)
                           SHUT_FD2;
                       else
                           send(fd1, &c, 1, MSG_OOB);
                   }
               if (fd1 > 0)
                   if (FD_ISSET(fd1, &rd)) {
                       r = read(fd1, buf1 + buf1_avail,
                                 BUF_SIZE - buf1_avail);
                       if (r < 1)
                           SHUT_FD1;
                       else
                           buf1_avail += r;
                   }
               if (fd2 > 0)
                   if (FD_ISSET(fd2, &rd)) {
                       r = read(fd2, buf2 + buf2_avail,
                                 BUF_SIZE - buf2_avail);
                       if (r < 1)
                           SHUT_FD2;
                       else
                           buf2_avail += r;
                   }
               if (fd1 > 0)
                   if (FD_ISSET(fd1, &wr)) {
                       r = write(fd1, buf2 + buf2_written,
                                  buf2_avail - buf2_written);
                       if (r < 1)
                           SHUT_FD1;
                       else
                           buf2_written += r;
                   }
               if (fd2 > 0)
                   if (FD_ISSET(fd2, &wr)) {
                       r = write(fd2, buf1 + buf1_written,
                                  buf1_avail - buf1_written);
                       if (r < 1)
                           SHUT_FD2;
                       else
                           buf1_written += r;
                   }

               /* check if write data has caught read data */

               if (buf1_written == buf1_avail)
                   buf1_written = buf1_avail = 0;
               if (buf2_written == buf2_avail)
                   buf2_written = buf2_avail = 0;

               /* one side has closed the connection, keep
                  writing to the other side until empty */

               if (fd1 < 0 && buf1_avail - buf1_written == 0)
                   SHUT_FD2;
               if (fd2 < 0 && buf2_avail - buf2_written == 0)
                   SHUT_FD1;
           }
           exit(EXIT_SUCCESS);
       }

       The above program properly forwards most kinds of TCP connections including
       OOB signal data transmitted by telnet servers.  It handles the tricky
       problem of having data flow in both directions simultaneously.  You might
       think it more efficient to use a fork(2) call and devote a thread to each
       stream.  This becomes more tricky than you might suspect.  Another idea is
       to set nonblocking I/O using fcntl(2).  This also has its problems because
       you end up using inefficient timeouts.

       The program does not handle more than one simultaneous connection at a
       time, although it could easily be extended to do this with a linked list of
       buffers--one for each connection.  At the moment, new connections cause the
       current connection to be dropped.

SEE ALSO top

       accept(2), connect(2), ioctl(2), poll(2), read(2), recv(2), select(2),
       send(2), sigprocmask(2), write(2), sigaddset(3), sigdelset(3),
       sigemptyset(3), sigfillset(3), sigismember(3), epoll(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-03                       SELECT_TUT(2)


semctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SEMCTL(2)                    Linux Programmer's Manual                   SEMCTL(2)

NAME top

       semctl - semaphore control operations

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/sem.h>

       int semctl(int semid, int semnum, int cmd, ...);

DESCRIPTION top

       semctl() performs the control operation specified by cmd on the semaphore
       set identified by semid, or on the semnum-th semaphore of that set.  (The
       semaphores in a set are numbered starting at 0.)

       This function has three or four arguments, depending on cmd.  When there
       are four, the fourth has the type union semun.  The calling program must
       define this union as follows:

           union semun {
               int              val;    /* Value for SETVAL */
               struct semid_ds *buf;    /* Buffer for IPC_STAT, IPC_SET */
               unsigned short  *array;  /* Array for GETALL, SETALL */
               struct seminfo  *__buf;  /* Buffer for IPC_INFO
                                           (Linux-specific) */
           };

       The semid_ds data structure is defined in <sys/sem.h> as follows:

           struct semid_ds {
               struct ipc_perm sem_perm;  /* Ownership and permissions */
               time_t          sem_otime; /* Last semop time */
               time_t          sem_ctime; /* Last change time */
               unsigned short  sem_nsems; /* No. of semaphores in set */
           };

       The ipc_perm structure is defined as follows (the highlighted fields are
       settable using IPC_SET):

           struct ipc_perm {
               key_t          __key; /* Key supplied to semget(2) */
               uid_t          uid;   /* Effective UID of owner */
               gid_t          gid;   /* Effective GID of owner */
               uid_t          cuid;  /* Effective UID of creator */
               gid_t          cgid;  /* Effective GID of creator */
               unsigned short mode;  /* Permissions */
               unsigned short __seq; /* Sequence number */
           };

       Valid values for cmd are:

       IPC_STAT  Copy information from the kernel data structure associated with
                 semid into the semid_ds structure pointed to by arg.buf.  The
                 argument semnum is ignored.  The calling process must have read
                 permission on the semaphore set.

       IPC_SET   Write the values of some members of the semid_ds structure
                 pointed to by arg.buf to the kernel data structure associated
                 with this semaphore set, updating also its sem_ctime member.  The
                 following members of the structure are updated: sem_perm.uid,
                 sem_perm.gid, and (the least significant 9 bits of)
                 sem_perm.mode.  The effective UID of the calling process must
                 match the owner (sem_perm.uid) or creator (sem_perm.cuid) of the
                 semaphore set, or the caller must be privileged.  The argument
                 semnum is ignored.

       IPC_RMID  Immediately remove the semaphore set, awakening all processes
                 blocked in semop(2) calls on the set (with an error return and
                 errno set to EIDRM).  The effective user ID of the calling
                 process must match the creator or owner of the semaphore set, or
                 the caller must be privileged.  The argument semnum is ignored.

       IPC_INFO (Linux-specific)
                 Returns information about system-wide semaphore limits and
                 parameters in the structure pointed to by arg.__buf.  This
                 structure is of type seminfo, defined in <sys/sem.h> if the
                 _GNU_SOURCE feature test macro is defined:

                     struct  seminfo {
                         int semmap;  /* Number of entries in semaphore
                                         map; unused within kernel */
                         int semmni;  /* Maximum number of semaphore sets */
                         int semmns;  /* Maximum number of semaphores in all
                                         semaphore sets */
                         int semmnu;  /* System-wide maximum number of undo
                                         structures; unused within kernel */
                         int semmsl;  /* Maximum number of semaphores in a
                                         set */
                         int semopm;  /* Maximum number of operations for
                                         semop(2) */
                         int semume;  /* Maximum number of undo entries per
                                         process; unused within kernel */
                         int semusz;  /* Size of struct sem_undo */
                         int semvmx;  /* Maximum semaphore value */
                         int semaem;  /* Max. value that can be recorded for
                                         semaphore adjustment (SEM_UNDO) */
                     };

                 The semmsl, semmns, semopm, and semmni settings can be changed
                 via /proc/sys/kernel/sem; see proc(5) for details.

       SEM_INFO (Linux-specific)
                 Returns a seminfo structure containing the same information as
                 for IPC_INFO, except that the following fields are returned with
                 information about system resources consumed by semaphores: the
                 semusz field returns the number of semaphore sets that currently
                 exist on the system; and the semaem field returns the total
                 number of semaphores in all semaphore sets on the system.

       SEM_STAT (Linux-specific)
                 Returns a semid_ds structure as for IPC_STAT.  However, the semid
                 argument is not a semaphore identifier, but instead an index into
                 the kernel's internal array that maintains information about all
                 semaphore sets on the system.

       GETALL    Return semval (i.e., the current value) for all semaphores of the
                 set into arg.array.  The argument semnum is ignored.  The calling
                 process must have read permission on the semaphore set.

       GETNCNT   The system call returns the value of semncnt for the semnum-th
                 semaphore of the set (i.e., the number of processes waiting for
                 an increase of semval for the semnum-th semaphore of the set).
                 The calling process must have read permission on the semaphore
                 set.

       GETPID    The system call returns the value of sempid for the semnum-th
                 semaphore of the set (i.e., the PID of the process that executed
                 the last semop(2) call for the semnum-th semaphore of the set).
                 The calling process must have read permission on the semaphore
                 set.

       GETVAL    The system call returns the value of semval for the semnum-th
                 semaphore of the set.  The calling process must have read
                 permission on the semaphore set.

       GETZCNT   The system call returns the value of semzcnt for the semnum-th
                 semaphore of the set (i.e., the number of processes waiting for
                 semval of the semnum-th semaphore of the set to become 0).  The
                 calling process must have read permission on the semaphore set.

       SETALL    Set semval for all semaphores of the set using arg.array,
                 updating also the sem_ctime member of the semid_ds structure
                 associated with the set.  Undo entries (see semop(2)) are cleared
                 for altered semaphores in all processes.  If the changes to
                 semaphore values would permit blocked semop(2) calls in other
                 processes to proceed, then those processes are woken up.  The
                 argument semnum is ignored.  The calling process must have alter
                 (write) permission on the semaphore set.

       SETVAL    Set the value of semval to arg.val for the semnum-th semaphore of
                 the set, updating also the sem_ctime member of the semid_ds
                 structure associated with the set.  Undo entries are cleared for
                 altered semaphores in all processes.  If the changes to semaphore
                 values would permit blocked semop(2) calls in other processes to
                 proceed, then those processes are woken up.  The calling process
                 must have alter permission on the semaphore set.

RETURN VALUE top

       On failure semctl() returns -1 with errno indicating the error.

       Otherwise the system call returns a nonnegative value depending on cmd as
       follows:

       GETNCNT     the value of semncnt.

       GETPID      the value of sempid.

       GETVAL      the value of semval.

       GETZCNT     the value of semzcnt.

       IPC_INFO    the index of the highest used entry in the kernel's internal
                   array recording information about all semaphore sets.  (This
                   information can be used with repeated SEM_STAT operations to
                   obtain information about all semaphore sets on the system.)

       SEM_INFO    As for IPC_INFO.

       SEM_STAT    the identifier of the semaphore set whose index was given in
                   semid.

       All other cmd values return 0 on success.

ERRORS top

       On failure, errno will be set to one of the following:

       EACCES The argument cmd has one of the values GETALL, GETPID, GETVAL,
              GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SETALL, or SETVAL and the
              calling process does not have the required permissions on the
              semaphore set and does not have the CAP_IPC_OWNER capability.

       EFAULT The address pointed to by arg.buf or arg.array isn't accessible.

       EIDRM  The semaphore set was removed.

       EINVAL Invalid value for cmd or semid.  Or: for a SEM_STAT operation, the
              index value specified in semid referred to an array slot that is
              currently unused.

       EPERM  The argument cmd has the value IPC_SET or IPC_RMID but the effective
              user ID of the calling process is not the creator (as found in
              sem_perm.cuid) or the owner (as found in sem_perm.uid) of the
              semaphore set, and the process does not have the CAP_SYS_ADMIN
              capability.

       ERANGE The argument cmd has the value SETALL or SETVAL and the value to
              which semval is to be set (for some semaphore of the set) is less
              than 0 or greater than the implementation limit SEMVMX.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       The IPC_INFO, SEM_STAT and SEM_INFO operations are used by the ipcs(1)
       program to provide information on allocated resources.  In the future these
       may modified or moved to a /proc file system interface.

       Various fields in a struct semid_ds were typed as short under Linux 2.2 and
       have become long under Linux 2.4.  To take advantage of this, a
       recompilation under glibc-2.1.91 or later should suffice.  (The kernel
       distinguishes old and new calls by an IPC_64 flag in cmd.)

       In some earlier versions of glibc, the semun union was defined in
       <sys/sem.h>, but POSIX.1-2001 requires that the caller define this union.
       On versions of glibc where this union is not defined, the macro
       _SEM_SEMUN_UNDEFINED is defined in <sys/sem.h>.

       The following system limit on semaphore sets affects a semctl() call:

       SEMVMX Maximum value for semval: implementation dependent (32767).

       For greater portability it is best to always call semctl() with four
       arguments.

SEE ALSO top

       ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7), svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                           SEMCTL(2)


semget(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SEMGET(2)                    Linux Programmer's Manual                   SEMGET(2)

NAME top

       semget - get a semaphore set identifier

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/sem.h>

       int semget(key_t key, int nsems, int semflg);

DESCRIPTION top

       The semget() system call returns the semaphore set identifier associated
       with the argument key.  A new set of nsems semaphores is created if key has
       the value IPC_PRIVATE or if no existing semaphore set is associated with
       key and IPC_CREAT is specified in semflg.

       If semflg specifies both IPC_CREAT and IPC_EXCL and a semaphore set already
       exists for key, then semget() fails with errno set to EEXIST.  (This is
       analogous to the effect of the combination O_CREAT | O_EXCL for open(2).)

       Upon creation, the least significant 9 bits of the argument semflg define
       the permissions (for owner, group and others) for the semaphore set.  These
       bits have the same format, and the same meaning, as the mode argument of
       open(2) (though the execute permissions are not meaningful for semaphores,
       and write permissions mean permission to alter semaphore values).

       The values of the semaphores in a newly created set are indeterminate.
       (POSIX.1-2001 is explicit on this point.)  Although Linux, like many other
       implementations, initializes the semaphore values to 0, a portable
       application cannot rely on this: it should explicitly initialize the
       semaphores to the desired values.

       When creating a new semaphore set, semget() initializes the set's
       associated data structure, semid_ds (see semctl(2)), as follows:

              sem_perm.cuid and sem_perm.uid are set to the effective user ID of
              the calling process.

              sem_perm.cgid and sem_perm.gid are set to the effective group ID of
              the calling process.

              The least significant 9 bits of sem_perm.mode are set to the least
              significant 9 bits of semflg.

              sem_nsems is set to the value of nsems.

              sem_otime is set to 0.

              sem_ctime is set to the current time.

       The argument nsems can be 0 (a don't care) when a semaphore set is not
       being created.  Otherwise nsems must be greater than 0 and less than or
       equal to the maximum number of semaphores per semaphore set (SEMMSL).

       If the semaphore set already exists, the permissions are verified.

RETURN VALUE top

       If successful, the return value will be the semaphore set identifier (a
       nonnegative integer), otherwise -1 is returned, with errno indicating the
       error.

ERRORS top

       On failure errno will be set to one of the following:

       EACCES A semaphore set exists for key, but the calling process does not
              have permission to access the set, and does not have the
              CAP_IPC_OWNER capability.

       EEXIST A semaphore set exists for key and semflg specified both IPC_CREAT
              and IPC_EXCL.

       EINVAL nsems is less than 0 or greater than the limit on the number of
              semaphores per semaphore set (SEMMSL), or a semaphore set
              corresponding to key already exists, and nsems is larger than the
              number of semaphores in that set.

       ENOENT No semaphore set exists for key and semflg did not specify
              IPC_CREAT.

       ENOMEM A semaphore set has to be created but the system does not have
              enough memory for the new data structure.

       ENOSPC A semaphore set has to be created but the system limit for the
              maximum number of semaphore sets (SEMMNI), or the system wide
              maximum number of semaphores (SEMMNS), would be exceeded.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       IPC_PRIVATE isn't a flag field but a key_t type.  If this special value is
       used for key, the system call ignores everything but the least significant
       9 bits of semflg and creates a new semaphore set (on success).

       The following limits on semaphore set resources affect the semget() call:

       SEMMNI System wide maximum number of semaphore sets: policy dependent (on
              Linux, this limit can be read and modified via the fourth field of
              /proc/sys/kernel/sem).

       SEMMSL Maximum number of semaphores per semid: implementation dependent (on
              Linux, this limit can be read and modified via the first field of
              /proc/sys/kernel/sem).

       SEMMNS System wide maximum number of semaphores: policy dependent (on
              Linux, this limit can be read and modified via the second field of
              /proc/sys/kernel/sem).  Values greater than SEMMSL * SEMMNI makes it
              irrelevant.

BUGS top

       The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more
       clearly show its function.

       The semaphores in a set are not initialized by semget().  In order to
       initialize the semaphores, semctl(2) must be used to perform a SETVAL or a
       SETALL operation on the semaphore set.  (Where multiple peers do not know
       who will be the first to initialize the set, checking for a nonzero
       sem_otime in the associated data structure retrieved by a semctl(2)
       IPC_STAT operation can be used to avoid races.)

SEE ALSO top

       semctl(2), semop(2), ftok(3), capabilities(7), sem_overview(7), svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                           SEMGET(2)


semop(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SEMOP(2)                     Linux Programmer's Manual                    SEMOP(2)

NAME top

       semop, semtimedop - semaphore operations

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/sem.h>

       int semop(int semid, struct sembuf *sops, unsigned nsops);

       int semtimedop(int semid, struct sembuf *sops, unsigned nsops,
                      struct timespec *timeout);

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

       semtimedop(): _GNU_SOURCE

DESCRIPTION top

       Each semaphore in a semaphore set has the following associated values:

           unsigned short  semval;   /* semaphore value */
           unsigned short  semzcnt;  /* # waiting for zero */
           unsigned short  semncnt;  /* # waiting for increase */
           pid_t           sempid;   /* ID of process that did last op */

       semop() performs operations on selected semaphores in the set indicated by
       semid.  Each of the nsops elements in the array pointed to by sops
       specifies an operation to be performed on a single semaphore.  The elements
       of this structure are of type struct sembuf, containing the following
       members:

           unsigned short sem_num;  /* semaphore number */
           short          sem_op;   /* semaphore operation */
           short          sem_flg;  /* operation flags */

       Flags recognized in sem_flg are IPC_NOWAIT and SEM_UNDO.  If an operation
       specifies SEM_UNDO, it will be automatically undone when the process
       terminates.

       The set of operations contained in sops is performed in array order, and
       atomically, that is, the operations are performed either as a complete
       unit, or not at all.  The behavior of the system call if not all operations
       can be performed immediately depends on the presence of the IPC_NOWAIT flag
       in the individual sem_flg fields, as noted below.

       Each operation is performed on the sem_num-th semaphore of the semaphore
       set, where the first semaphore of the set is numbered 0.  There are three
       types of operation, distinguished by the value of sem_op.

       If sem_op is a positive integer, the operation adds this value to the
       semaphore value (semval).  Furthermore, if SEM_UNDO is specified for this
       operation, the system updates the undo count (semadj) for this semaphore.
       This operation can always proceed--it never forces a thread to wait.  The
       calling process must have alter permission on the semaphore set.

       If sem_op is zero, the process must have read permission on the semaphore
       set.  This is a "wait-for-zero" operation: if semval is zero, the operation
       can immediately proceed.  Otherwise, if IPC_NOWAIT is specified in sem_flg,
       semop() fails with errno set to EAGAIN (and none of the operations in sops
       is performed).  Otherwise semzcnt (the count of threads waiting until this
       semaphore's value becomes zero) is incremented by one and the thread sleeps
       until one of the following occurs:

       +o  semval becomes 0, at which time the value of semzcnt is decremented.

       +o  The semaphore set is removed: semop() fails, with errno set to EIDRM.

       +o  The calling thread catches a signal: the value of semzcnt is decremented
          and semop() fails, with errno set to EINTR.

       +o  The time limit specified by timeout in a semtimedop() call expires:
          semop() fails, with errno set to EAGAIN.

       If sem_op is less than zero, the process must have alter permission on the
       semaphore set.  If semval is greater than or equal to the absolute value of
       sem_op, the operation can proceed immediately: the absolute value of sem_op
       is subtracted from semval, and, if SEM_UNDO is specified for this
       operation, the system updates the undo count (semadj) for this semaphore.
       If the absolute value of sem_op is greater than semval, and IPC_NOWAIT is
       specified in sem_flg, semop() fails, with errno set to EAGAIN (and none of
       the operations in sops is performed).  Otherwise semncnt (the counter of
       threads waiting for this semaphore's value to increase) is incremented by
       one and the thread sleeps until one of the following occurs:

       +o  semval becomes greater than or equal to the absolute value of sem_op, at
          which time the value of semncnt is decremented, the absolute value of
          sem_op is subtracted from semval and, if SEM_UNDO is specified for this
          operation, the system updates the undo count (semadj) for this
          semaphore.

       +o  The semaphore set is removed from the system: semop() fails, with errno
          set to EIDRM.

       +o  The calling thread catches a signal: the value of semncnt is decremented
          and semop() fails, with errno set to EINTR.

       +o  The time limit specified by timeout in a semtimedop() call expires: the
          system call fails, with errno set to EAGAIN.

       On successful completion, the sempid value for each semaphore specified in
       the array pointed to by sops is set to the caller's process ID.  In
       addition, the sem_otime is set to the current time.

       semtimedop() behaves identically to semop() except that in those cases were
       the calling thread would sleep, the duration of that sleep is limited by
       the amount of elapsed time specified by the timespec structure whose
       address is passed in the timeout argument.  (This sleep interval will be
       rounded up to the system clock granularity, and kernel scheduling delays
       mean that the interval may overrun by a small amount.)  If the specified
       time limit has been reached, semtimedop() fails with errno set to EAGAIN
       (and none of the operations in sops is performed).  If the timeout argument
       is NULL, then semtimedop() behaves exactly like semop().

RETURN VALUE top

       If successful semop() and semtimedop() return 0; otherwise they return -1
       with errno indicating the error.

ERRORS top

       On failure, errno is set to one of the following:

       E2BIG  The argument nsops is greater than SEMOPM, the maximum number of
              operations allowed per system call.

       EACCES The calling process does not have the permissions required to
              perform the specified semaphore operations, and does not have the
              CAP_IPC_OWNER capability.

       EAGAIN An operation could not proceed immediately and either IPC_NOWAIT was
              specified in sem_flg or the time limit specified in timeout expired.

       EFAULT An address specified in either the sops or the timeout argument
              isn't accessible.

       EFBIG  For some operation the value of sem_num is less than 0 or greater
              than or equal to the number of semaphores in the set.

       EIDRM  The semaphore set was removed.

       EINTR  While blocked in this system call, the thread caught a signal; see
              signal(7).

       EINVAL The semaphore set doesn't exist, or semid is less than zero, or
              nsops has a nonpositive value.

       ENOMEM The sem_flg of some operation specified SEM_UNDO and the system does
              not have enough memory to allocate the undo structure.

       ERANGE For some operation sem_op+semval is greater than SEMVMX, the
              implementation dependent maximum value for semval.

VERSIONS top

       semtimedop() first appeared in Linux 2.5.52, and was subsequently
       backported into kernel 2.4.22.  Glibc support for semtimedop() first
       appeared in version 2.3.3.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       The sem_undo structures of a process aren't inherited by the child produced
       by fork(2), but they are inherited across an execve(2) system call.

       semop() is never automatically restarted after being interrupted by a
       signal handler, regardless of the setting of the SA_RESTART flag when
       establishing a signal handler.

       semadj is a per-process integer which is simply the (negative) count of all
       semaphore operations performed specifying the SEM_UNDO flag.  When a
       semaphore's value is directly set using the SETVAL or SETALL request to
       semctl(2), the corresponding semadj values in all processes are cleared.

       The semval, sempid, semzcnt, and semnct values for a semaphore can all be
       retrieved using appropriate semctl(2) calls.

       The following limits on semaphore set resources affect the semop() call:

       SEMOPM Maximum number of operations allowed for one semop() call (32) (on
              Linux, this limit can be read and modified via the third field of
              /proc/sys/kernel/sem).

       SEMVMX Maximum allowable value for semval: implementation dependent
              (32767).

       The implementation has no intrinsic limits for the adjust on exit maximum
       value (SEMAEM), the system wide maximum number of undo structures (SEMMNU)
       and the per-process maximum number of undo entries system parameters.

BUGS top

       When a process terminates, its set of associated semadj structures is used
       to undo the effect of all of the semaphore operations it performed with the
       SEM_UNDO flag.  This raises a difficulty: if one (or more) of these
       semaphore adjustments would result in an attempt to decrease a semaphore's
       value below zero, what should an implementation do?  One possible approach
       would be to block until all the semaphore adjustments could be performed.
       This is however undesirable since it could force process termination to
       block for arbitrarily long periods.  Another possibility is that such
       semaphore adjustments could be ignored altogether (somewhat analogously to
       failing when IPC_NOWAIT is specified for a semaphore operation).  Linux
       adopts a third approach: decreasing the semaphore value as far as possible
       (i.e., to zero) and allowing process termination to proceed immediately.

       In kernels 2.6.x, x <= 10, there is a bug that in some circumstances
       prevents a thread that is waiting for a semaphore value to become zero from
       being woken up when the value does actually become zero.  This bug is fixed
       in kernel 2.6.11.

EXAMPLE top

       The following code segment uses semop() to atomically wait for the value of
       semaphore 0 to become zero, and then increment the semaphore value by one.

           struct sembuf sops[2];
           int semid;

           /* Code to set semid omitted */

           sops[0].sem_num = 0;        /* Operate on semaphore 0 */
           sops[0].sem_op = 0;         /* Wait for value to equal 0 */
           sops[0].sem_flg = 0;

           sops[1].sem_num = 0;        /* Operate on semaphore 0 */
           sops[1].sem_op = 1;         /* Increment value by one */
           sops[1].sem_flg = 0;

           if (semop(semid, sops, 2) == -1) {
               perror("semop");
               exit(EXIT_FAILURE);
           }

SEE ALSO top

       clone(2), semctl(2), semget(2), sigaction(2), capabilities(7),
       sem_overview(7), svipc(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-27                            SEMOP(2)


sem_close(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_CLOSE(3)                 Linux Programmer's Manual                SEM_CLOSE(3)

NAME top

       sem_close - close a named semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_close(sem_t *sem);

       Link with -pthread.

DESCRIPTION top

       sem_close() closes the named semaphore referred to by sem, allowing any
       resources that the system has allocated to the calling process for this
       semaphore to be freed.

RETURN VALUE top

       On success sem_close() returns 0; on error, -1 is returned, with errno set
       to indicate the error.

ERRORS top

       EINVAL sem is not a valid semaphore.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       All open named semaphores are automatically closed on process termination,
       or upon execve(2).

SEE ALSO top

       sem_getvalue(3), sem_open(3), sem_post(3), sem_unlink(3), sem_wait(3),
       sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                        SEM_CLOSE(3)


sem_destroy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_DESTROY(3)               Linux Programmer's Manual              SEM_DESTROY(3)

NAME top

       sem_destroy - destroy an unnamed semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_destroy(sem_t *sem);

       Link with -pthread.

DESCRIPTION top

       sem_destroy() destroys the unnamed semaphore at the address pointed to by
       sem.

       Only a semaphore that has been initialized by sem_init(3) should be
       destroyed using sem_destroy().

       Destroying a semaphore that other processes or threads are currently
       blocked on (in sem_wait(3)) produces undefined behavior.

       Using a semaphore that has been destroyed produces undefined results, until
       the semaphore has been reinitialized using sem_init(3).

RETURN VALUE top

       sem_destroy() returns 0 on success; on error, -1 is returned, and errno is
       set to indicate the error.

ERRORS top

       EINVAL sem is not a valid semaphore.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       An unnamed semaphore should be destroyed with sem_destroy() before the
       memory in which it is located is deallocated.  Failure to do this can
       result in resource leaks on some implementations.

SEE ALSO top

       sem_init(3), sem_post(3), sem_wait(3), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                      SEM_DESTROY(3)


sem_getvalue(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_GETVALUE(3)              Linux Programmer's Manual             SEM_GETVALUE(3)

NAME top

       sem_getvalue - get the value of a semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_getvalue(sem_t *sem, int *sval);

       Link with -pthread.

DESCRIPTION top

       sem_getvalue() places the current value of the semaphore pointed to sem
       into the integer pointed to by sval.

       If one or more processes or threads are blocked waiting to lock the
       semaphore with sem_wait(3), POSIX.1-2001 permits two possibilities for the
       value returned in sval: either 0 is returned; or a negative number whose
       absolute value is the count of the number of processes and threads
       currently blocked in sem_wait(3).  Linux adopts the former behavior.

RETURN VALUE top

       sem_getvalue() returns 0 on success; on error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       EINVAL sem is not a valid semaphore.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The value of the semaphore may already have changed by the time
       sem_getvalue() returns.

SEE ALSO top

       sem_post(3), sem_wait(3), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                     SEM_GETVALUE(3)


sem_init(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_INIT(3)                  Linux Programmer's Manual                 SEM_INIT(3)

NAME top

       sem_init - initialize an unnamed semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_init(sem_t *sem, int pshared, unsigned int value);

       Link with -pthread.

DESCRIPTION top

       sem_init() initializes the unnamed semaphore at the address pointed to by
       sem.  The value argument specifies the initial value for the semaphore.

       The pshared argument indicates whether this semaphore is to be shared
       between the threads of a process, or between processes.

       If pshared has the value 0, then the semaphore is shared between the
       threads of a process, and should be located at some address that is visible
       to all threads (e.g., a global variable, or a variable allocated
       dynamically on the heap).

       If pshared is nonzero, then the semaphore is shared between processes, and
       should be located in a region of shared memory (see shm_open(3), mmap(2),
       and shmget(2)).  (Since a child created by fork(2) inherits its parent's
       memory mappings, it can also access the semaphore.)  Any process that can
       access the shared memory region can operate on the semaphore using
       sem_post(3), sem_wait(3), etc.

       Initializing a semaphore that has already been initialized results in
       undefined behavior.

RETURN VALUE top

       sem_init() returns 0 on success; on error, -1 is returned, and errno is set
       to indicate the error.

ERRORS top

       EINVAL value exceeds SEM_VALUE_MAX.

       ENOSYS pshared is nonzero, but the system does not support process-shared
              semaphores (see sem_overview(7)).

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Bizarrely, POSIX.1-2001 does not specify the value that should be returned
       by a successful call to sem_init().  POSIX.1-2008 rectifies this,
       specifying the zero return on success.

SEE ALSO top

       sem_destroy(3), sem_post(3), sem_wait(3), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                         SEM_INIT(3)


sem_open(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_OPEN(3)                  Linux Programmer's Manual                 SEM_OPEN(3)

NAME top

       sem_open - initialize and open a named semaphore

SYNOPSIS top

       #include <fcntl.h>           /* For O_* constants */
       #include <sys/stat.h>        /* For mode constants */
       #include <semaphore.h>

       sem_t *sem_open(const char *name, int oflag);
       sem_t *sem_open(const char *name, int oflag,
                       mode_t mode, unsigned int value);

       Link with -pthread.

DESCRIPTION top

       sem_open() creates a new POSIX semaphore or opens an existing semaphore.
       The semaphore is identified by name.  For details of the construction of
       name, see sem_overview(7).

       The oflag argument specifies flags that control the operation of the call.
       (Definitions of the flags values can be obtained by including <fcntl.h>.)
       If O_CREAT is specified in oflag, then the semaphore is created if it does
       not already exist.  The owner (user ID) of the semaphore is set to the
       effective user ID of the calling process.  The group ownership (group ID)
       is set to the effective group ID of the calling process.  If both O_CREAT
       and O_EXCL are specified in oflag, then an error is returned if a semaphore
       with the given name already exists.

       If O_CREAT is specified in oflag, then two additional arguments must be
       supplied.  The mode argument specifies the permissions to be placed on the
       new semaphore, as for open(2).  (Symbolic definitions for the permissions
       bits can be obtained by including <sys/stat.h>.)  The permissions settings
       are masked against the process umask.  Both read and write permission
       should be granted to each class of user that will access the semaphore.
       The value argument specifies the initial value for the new semaphore.  If
       O_CREAT is specified, and a semaphore with the given name already exists,
       then mode and value are ignored.

RETURN VALUE top

       On success, sem_open() returns the address of the new semaphore; this
       address is used when calling other semaphore-related functions.  On error,
       sem_open() returns SEM_FAILED, with errno set to indicate the error.

ERRORS top

       EACCES The semaphore exists, but the caller does not have permission to
              open it.

       EEXIST Both O_CREAT and O_EXCL were specified in oflag, but a semaphore
              with this name already exists.

       EINVAL value was greater than SEM_VALUE_MAX.

       EINVAL name consists of just "/", followed by no other characters.

       EMFILE The process already has the maximum number of files and open.

       ENAMETOOLONG
              name was too long.

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

       ENOENT The O_CREAT flag was not specified in oflag and no semaphore with
              this name exists; or, O_CREAT was specified, but name wasn't well
              formed.

       ENOMEM Insufficient memory.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       sem_close(3), sem_getvalue(3), sem_post(3), sem_unlink(3), sem_wait(3),
       sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                         SEM_OPEN(3)


sem_overview(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_OVERVIEW(7)              Linux Programmer's Manual             SEM_OVERVIEW(7)

NAME top

       sem_overview - overview of POSIX semaphores

DESCRIPTION top

       POSIX semaphores allow processes and threads to synchronize their actions.

       A semaphore is an integer whose value is never allowed to fall below zero.
       Two operations can be performed on semaphores: increment the semaphore
       value by one (sem_post(3)); and decrement the semaphore value by one
       (sem_wait(3)).  If the value of a semaphore is currently zero, then a
       sem_wait(3) operation will block until the value becomes greater than zero.

       POSIX semaphores come in two forms: named semaphores and unnamed
       semaphores.

       Named semaphores
              A named semaphore is identified by a name of the form /somename;
              that is, a null-terminated string of up to NAME_MAX-4 (i.e., 251)
              characters consisting of an initial slash, followed by one or more
              characters, none of which are slashes.  Two processes can operate on
              the same named semaphore by passing the same name to sem_open(3).

              The sem_open(3) function creates a new named semaphore or opens an
              existing named semaphore.  After the semaphore has been opened, it
              can be operated on using sem_post(3) and sem_wait(3).  When a
              process has finished using the semaphore, it can use sem_close(3) to
              close the semaphore.  When all processes have finished using the
              semaphore, it can be removed from the system using sem_unlink(3).

       Unnamed semaphores (memory-based semaphores)
              An unnamed semaphore does not have a name.  Instead the semaphore is
              placed in a region of memory that is shared between multiple threads
              (a thread-shared semaphore) or processes (a process-shared
              semaphore).  A thread-shared semaphore is placed in an area of
              memory shared between the threads of a process, for example, a
              global variable.  A process-shared semaphore must be placed in a
              shared memory region (e.g., a System V shared memory segment created
              using shmget(2), or a POSIX shared memory object built created using
              shm_open(3)).

              Before being used, an unnamed semaphore must be initialized using
              sem_init(3).  It can then be operated on using sem_post(3) and
              sem_wait(3).  When the semaphore is no longer required, and before
              the memory in which it is located is deallocated, the semaphore
              should be destroyed using sem_destroy(3).

       The remainder of this section describes some specific details of the Linux
       implementation of POSIX semaphores.

Versions

       Prior to kernel 2.6, Linux only supported unnamed, thread-shared
       semaphores.  On a system with Linux 2.6 and a glibc that provides the NPTL
       threading implementation, a complete implementation of POSIX semaphores is
       provided.

Persistence

       POSIX named semaphores have kernel persistence: if not removed by
       sem_unlink(3), a semaphore will exist until the system is shut down.

Linking

       Programs using the POSIX semaphores API must be compiled with cc -pthread
       to link against the real-time library, librt.

Accessing named semaphores via the file system

       On Linux, named semaphores are created in a virtual file system, normally
       mounted under /dev/shm, with names of the form sem.somename.  (This is the
       reason that semaphore names are limited to NAME_MAX-4 rather than NAME_MAX
       characters.)

       Since Linux 2.6.19, ACLs can be placed on files under this directory, to
       control object permissions on a per-user and per-group basis.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       System V semaphores (semget(2), semop(2), etc.) are an older semaphore API.
       POSIX semaphores provide a simpler, and better designed interface than
       System V semaphores; on the other hand POSIX semaphores are less widely
       available (especially on older systems) than System V semaphores.

EXAMPLE top

       An example of the use of various POSIX semaphore functions is shown in
       sem_wait(3).

SEE ALSO top

       sem_close(3), sem_destroy(3), sem_getvalue(3), sem_init(3), sem_open(3),
       sem_post(3), sem_unlink(3), sem_wait(3), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                     SEM_OVERVIEW(7)


sem_post(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_POST(3)                  Linux Programmer's Manual                 SEM_POST(3)

NAME top

       sem_post - unlock a semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_post(sem_t *sem);

       Link with -pthread.

DESCRIPTION top

       sem_post() increments (unlocks) the semaphore pointed to by sem.  If the
       semaphore's value consequently becomes greater than zero, then another
       process or thread blocked in a sem_wait(3) call will be woken up and
       proceed to lock the semaphore.

RETURN VALUE top

       sem_post() returns 0 on success; on error, the value of the semaphore is
       left unchanged, -1 is returned, and errno is set to indicate the error.

ERRORS top

       EINVAL sem is not a valid semaphore.

       EOVERFLOW
              The maximum allowable value for a semaphore would be exceeded.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       sem_post() is async-signal-safe: it may be safely called within a signal
       handler.

EXAMPLE top

       See sem_wait(3).

SEE ALSO top

       sem_getvalue(3), sem_wait(3), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                         SEM_POST(3)


sem_wait(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_WAIT(3)                  Linux Programmer's Manual                 SEM_WAIT(3)

NAME top

       sem_wait, sem_timedwait, sem_trywait - lock a semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_wait(sem_t *sem);

       int sem_trywait(sem_t *sem);

       int sem_timedwait(sem_t *sem, const struct timespec *abs_timeout);

       Link with -pthread.

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

       sem_timedwait(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       sem_wait() decrements (locks) the semaphore pointed to by sem.  If the
       semaphore's value is greater than zero, then the decrement proceeds, and
       the function returns, immediately.  If the semaphore currently has the
       value zero, then the call blocks until either it becomes possible to
       perform the decrement (i.e., the semaphore value rises above zero), or a
       signal handler interrupts the call.

       sem_trywait() is the same as sem_wait(), except that if the decrement
       cannot be immediately performed, then call returns an error (errno set to
       EAGAIN) instead of blocking.

       sem_timedwait() is the same as sem_wait(), except that abs_timeout
       specifies a limit on the amount of time that the call should block if the
       decrement cannot be immediately performed.  The abs_timeout argument points
       to a structure that specifies an absolute timeout in seconds and
       nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).  This
       structure is defined as follows:

           struct timespec {
               time_t tv_sec;      /* Seconds */
               long   tv_nsec;     /* Nanoseconds [0 .. 999999999] */
           };

       If the timeout has already expired by the time of the call, and the
       semaphore could not be locked immediately, then sem_timedwait() fails with
       a timeout error (errno set to ETIMEDOUT).

       If the operation can be performed immediately, then sem_timedwait() never
       fails with a timeout error, regardless of the value of abs_timeout.
       Furthermore, the validity of abs_timeout is not checked in this case.

RETURN VALUE top

       All of these functions return 0 on success; on error, the value of the
       semaphore is left unchanged, -1 is returned, and errno is set to indicate
       the error.

ERRORS top

       EINTR  The call was interrupted by a signal handler; see signal(7).

       EINVAL sem is not a valid semaphore.

       The following additional error can occur for sem_trywait():

       EAGAIN The operation could not be performed without blocking (i.e., the
              semaphore currently has the value zero).

       The following additional errors can occur for sem_timedwait():

       EINVAL The value of abs_timeout.tv_nsecs is less than 0, or greater than or
              equal to 1000 million.

       ETIMEDOUT
              The call timed out before the semaphore could be locked.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       A signal handler always interrupts a blocked call to one of these
       functions, regardless of the use of the sigaction(2) SA_RESTART flag.

EXAMPLE top

       The (somewhat trivial) program shown below operates on an unnamed
       semaphore.  The program expects two command-line arguments.  The first
       argument specifies a seconds value that is used to set an alarm timer to
       generate a SIGALRM signal.  This handler performs a sem_post(3) to
       increment the semaphore that is being waited on in main() using
       sem_timedwait().  The second command-line argument specifies the length of
       the timeout, in seconds, for sem_timedwait().  The following shows what
       happens on two different runs of the program:

           $ ./a.out 2 3
           About to call sem_timedwait()
           sem_post() from handler
           sem_timedwait() succeeded
           $ ./a.out 2 1
           About to call sem_timedwait()
           sem_timedwait() timed out

Program source

       #include <unistd.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <semaphore.h>
       #include <time.h>
       #include <assert.h>
       #include <errno.h>
       #include <signal.h>

       sem_t sem;

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

       static void
       handler(int sig)
       {
           write(STDOUT_FILENO, "sem_post() from handler\n", 24);
           if (sem_post(&sem) == -1) {
               write(STDERR_FILENO, "sem_post() failed\n", 18);
               _exit(EXIT_FAILURE);
           }
       }

       int
       main(int argc, char *argv[])
       {
           struct sigaction sa;
           struct timespec ts;
           int s;

           if (argc != 3) {
               fprintf(stderr, "Usage: %s <alarm-secs> <wait-secs>\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           if (sem_init(&sem, 0, 0) == -1)
               handle_error("sem_init");

           /* Establish SIGALRM handler; set alarm timer using argv[1] */

           sa.sa_handler = handler;
           sigemptyset(&sa.sa_mask);
           sa.sa_flags = 0;
           if (sigaction(SIGALRM, &sa, NULL) == -1)
               handle_error("sigaction");

           alarm(atoi(argv[1]));

           /* Calculate relative interval as current time plus
              number of seconds given argv[2] */

           if (clock_gettime(CLOCK_REALTIME, &ts) == -1)
               handle_error("clock_gettime");

           ts.tv_sec += atoi(argv[2]);

           printf("main() about to call sem_timedwait()\n");
           while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR)
               continue;       /* Restart if interrupted by handler */

           /* Check what happened */

           if (s == -1) {
               if (errno == ETIMEDOUT)
                   printf("sem_timedwait() timed out\n");
               else
                   perror("sem_timedwait");
           } else
               printf("sem_timedwait() succeeded\n");

           exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
       }

SEE ALSO top

       clock_gettime(2), sem_getvalue(3), sem_post(3), sem_overview(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                         SEM_WAIT(3)


sem_unlink(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SEM_UNLINK(3)                Linux Programmer's Manual               SEM_UNLINK(3)

NAME top

       sem_unlink - remove a named semaphore

SYNOPSIS top

       #include <semaphore.h>

       int sem_unlink(const char *name);

       Link with -pthread.

DESCRIPTION top

       sem_unlink() removes the named semaphore referred to by name.  The
       semaphore name is removed immediately.  The semaphore is destroyed once all
       other processes that have the semaphore open close it.

RETURN VALUE top

       On success sem_unlink() returns 0; on error, -1 is returned, with errno set
       to indicate the error.

ERRORS top

       EACCES The caller does not have permission to unlink this semaphore.

       ENAMETOOLONG
              name was too long.

       ENOENT There is no semaphore with the given name.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       sem_getvalue(3), sem_open(3), sem_post(3), sem_wait(3), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-13                       SEM_UNLINK(3)


send(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SEND(2)                      Linux Programmer's Manual                     SEND(2)

NAME top

       send, sendto, sendmsg - send a message on a socket

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/socket.h>

       ssize_t send(int sockfd, const void *buf, size_t len, int flags);

       ssize_t sendto(int sockfd, const void *buf, size_t len, int flags,
                      const struct sockaddr *dest_addr, socklen_t addrlen);

       ssize_t sendmsg(int sockfd, const struct msghdr *msg, int flags);

DESCRIPTION top

       The system calls send(), sendto(), and sendmsg() are used to transmit a
       message to another socket.

       The send() call may be used only when the socket is in a connected state
       (so that the intended recipient is known).  The only difference between
       send() and write(2) is the presence of flags.  With a zero flags argument,
       send() is equivalent to write(2).  Also, the following call

           send(sockfd, buf, len, flags);

       is equivalent to

           sendto(sockfd, buf, len, flags, NULL, 0);

       The argument sockfd is the file descriptor of the sending socket.

       If sendto() is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET)
       socket, the arguments dest_addr and addrlen are ignored (and the error
       EISCONN may be returned when they are not NULL and 0), and the error
       ENOTCONN is returned when the socket was not actually connected.
       Otherwise, the address of the target is given by dest_addr with addrlen
       specifying its size.  For sendmsg(), the address of the target is given by
       msg.msg_name, with msg.msg_namelen specifying its size.

       For send() and sendto(), the message is found in buf and has length len.
       For sendmsg(), the message is pointed to by the elements of the array
       msg.msg_iov.  The sendmsg() call also allows sending ancillary data (also
       known as control information).

       If the message is too long to pass atomically through the underlying
       protocol, the error EMSGSIZE is returned, and the message is not
       transmitted.

       No indication of failure to deliver is implicit in a send().  Locally
       detected errors are indicated by a return value of -1.

       When the message does not fit into the send buffer of the socket, send()
       normally blocks, unless the socket has been placed in nonblocking I/O mode.
       In nonblocking mode it would fail with the error EAGAIN or EWOULDBLOCK in
       this case.  The select(2) call may be used to determine when it is possible
       to send more data.

       The flags argument is the bitwise OR of zero or more of the following
       flags.

       MSG_CONFIRM (Since Linux 2.3.15)
              Tell the link layer that forward progress happened: you got a
              successful reply from the other side.  If the link layer doesn't get
              this it will regularly reprobe the neighbor (e.g., via a unicast
              ARP).  Only valid on SOCK_DGRAM and SOCK_RAW sockets and currently
              only implemented for IPv4 and IPv6.  See arp(7) for details.

       MSG_DONTROUTE
              Don't use a gateway to send out the packet, only send to hosts on
              directly connected networks.  This is usually used only by
              diagnostic or routing programs.  This is only defined for protocol
              families that route; packet sockets don't.

       MSG_DONTWAIT (since Linux 2.2)
              Enables nonblocking operation; if the operation would block, EAGAIN
              or EWOULDBLOCK is returned (this can also be enabled using the
              O_NONBLOCK flag with the F_SETFL fcntl(2)).

       MSG_EOR (since Linux 2.2)
              Terminates a record (when this notion is supported, as for sockets
              of type SOCK_SEQPACKET).

       MSG_MORE (Since Linux 2.4.4)
              The caller has more data to send.  This flag is used with TCP
              sockets to obtain the same effect as the TCP_CORK socket option (see
              tcp(7)), with the difference that this flag can be set on a per-call
              basis.

              Since Linux 2.6, this flag is also supported for UDP sockets, and
              informs the kernel to package all of the data sent in calls with
              this flag set into a single datagram which is only transmitted when
              a call is performed that does not specify this flag.  (See also the
              UDP_CORK socket option described in udp(7).)

       MSG_NOSIGNAL (since Linux 2.2)
              Requests not to send SIGPIPE on errors on stream oriented sockets
              when the other end breaks the connection.  The EPIPE error is still
              returned.

       MSG_OOB
              Sends out-of-band data on sockets that support this notion (e.g., of
              type SOCK_STREAM); the underlying protocol must also support out-of-
              band data.

       The definition of the msghdr structure follows.  See recv(2) and below for
       an exact description of its fields.

           struct msghdr {
               void         *msg_name;       /* optional address */
               socklen_t     msg_namelen;    /* size of address */
               struct iovec *msg_iov;        /* scatter/gather array */
               size_t        msg_iovlen;     /* # elements in msg_iov */
               void         *msg_control;    /* ancillary data, see below */
               size_t        msg_controllen; /* ancillary data buffer len */
               int           msg_flags;      /* flags on received message */
           };

       You may send control information using the msg_control and msg_controllen
       members.  The maximum control buffer length the kernel can process is
       limited per socket by the value in /proc/sys/net/core/optmem_max; see
       socket(7).

RETURN VALUE top

       On success, these calls return the number of characters sent.  On error, -1
       is returned, and errno is set appropriately.

ERRORS top

       These are some standard errors generated by the socket layer.  Additional
       errors may be generated and returned from the underlying protocol modules;
       see their respective manual pages.

       EACCES (For UNIX domain sockets, which are identified by pathname) Write
              permission is denied on the destination socket file, or search
              permission is denied for one of the directories the path prefix.
              (See path_resolution(7).)

              (For UDP sockets) An attempt was made to send to a network/broadcast
              address as though it was a unicast address.

       EAGAIN or EWOULDBLOCK
              The socket is marked nonblocking and the requested operation would
              block.  POSIX.1-2001 allows either error to be returned for this
              case, and does not require these constants to have the same value,
              so a portable application should check for both possibilities.

       EBADF  An invalid descriptor was specified.

       ECONNRESET
              Connection reset by peer.

       EDESTADDRREQ
              The socket is not connection-mode, and no peer address is set.

       EFAULT An invalid user space address was specified for an argument.

       EINTR  A signal occurred before any data was transmitted; see signal(7).

       EINVAL Invalid argument passed.

       EISCONN
              The connection-mode socket was connected already but a recipient was
              specified.  (Now either this error is returned, or the recipient
              specification is ignored.)

       EMSGSIZE
              The socket type requires that message be sent atomically, and the
              size of the message to be sent made this impossible.

       ENOBUFS
              The output queue for a network interface was full.  This generally
              indicates that the interface has stopped sending, but may be caused
              by transient congestion.  (Normally, this does not occur in Linux.
              Packets are just silently dropped when a device queue overflows.)

       ENOMEM No memory available.

       ENOTCONN
              The socket is not connected, and no target has been given.

       ENOTSOCK
              The argument sockfd is not a socket.

       EOPNOTSUPP
              Some bit in the flags argument is inappropriate for the socket type.

       EPIPE  The local end has been shut down on a connection oriented socket.
              In this case the process will also receive a SIGPIPE unless
              MSG_NOSIGNAL is set.

CONFORMING TO top

       4.4BSD, SVr4, POSIX.1-2001.  These function calls appeared in 4.2BSD.

       POSIX.1-2001 only describes the MSG_OOB and MSG_EOR flags.  POSIX.1-2008
       adds a specification of MSG_NOSIGNAL.  The MSG_CONFIRM flag is a Linux
       extension.

NOTES top

       The prototypes given above follow the Single UNIX Specification, as glibc2
       also does; the flags argument was int in 4.x BSD, but unsigned int in libc4
       and libc5; the len argument was int in 4.x BSD and libc4, but size_t in
       libc5; the addrlen argument was int in 4.x BSD and libc4 and libc5.  See
       also accept(2).

       According to POSIX.1-2001, the msg_controllen field of the msghdr structure
       should be typed as socklen_t, but glibc currently types it as size_t.

       See sendmmsg(2) for information about a Linux-specific system call that can
       be used to transmit multiple datagrams in a single call.

BUGS top

       Linux may return EPIPE instead of ENOTCONN.

EXAMPLE top

       An example of the use of sendto() is shown in getaddrinfo(3).

SEE ALSO top

       fcntl(2), getsockopt(2), recv(2), select(2), sendfile(2), sendmmsg(2),
       shutdown(2), socket(2), write(2), cmsg(3), ip(7), socket(7), tcp(7), udp(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-04-23                             SEND(2)


sendfile(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SENDFILE(2)                  Linux Programmer's Manual                 SENDFILE(2)

NAME top

       sendfile - transfer data between file descriptors

SYNOPSIS top

       #include <sys/sendfile.h>

       ssize_t sendfile(int out_fd, int in_fd, off_t *offset, size_t count);

DESCRIPTION top

       sendfile() copies data between one file descriptor and another.  Because
       this copying is done within the kernel, sendfile() is more efficient than
       the combination of read(2) and write(2), which would require transferring
       data to and from user space.

       in_fd should be a file descriptor opened for reading and out_fd should be a
       descriptor opened for writing.

       If offset is not NULL, then it points to a variable holding the file offset
       from which sendfile() will start reading data from in_fd.  When sendfile()
       returns, this variable will be set to the offset of the byte following the
       last byte that was read.  If offset is not NULL, then sendfile() does not
       modify the current file offset of in_fd; otherwise the current file offset
       is adjusted to reflect the number of bytes read from in_fd.

       If offset is NULL, then data will be read from in_fd starting at the
       current file offset, and the file offset will be updated by the call.

       count is the number of bytes to copy between the file descriptors.

       The in_fd argument must correspond to a file which supports mmap(2)-like
       operations (i.e., it cannot be a socket).

       In Linux kernels before 2.6.33, out_fd must refer to a socket.  Since Linux
       2.6.33 it can be any file.  If it is a regular file, then sendfile()
       changes the file offset appropriately.

RETURN VALUE top

       If the transfer was successful, the number of bytes written to out_fd is
       returned.  On error, -1 is returned, and errno is set appropriately.

ERRORS top

       EAGAIN Nonblocking I/O has been selected using O_NONBLOCK and the write
              would block.

       EBADF  The input file was not opened for reading or the output file was not
              opened for writing.

       EFAULT Bad address.

       EINVAL Descriptor is not valid or locked, or an mmap(2)-like operation is
              not available for in_fd.

       EIO    Unspecified error while reading from in_fd.

       ENOMEM Insufficient memory to read from in_fd.

VERSIONS top

       sendfile() is a new feature in Linux 2.2.  The include file
       <sys/sendfile.h> is present since glibc 2.1.

CONFORMING TO top

       Not specified in POSIX.1-2001, or other standards.

       Other UNIX systems implement sendfile() with different semantics and
       prototypes.  It should not be used in portable programs.

NOTES top

       If you plan to use sendfile() for sending files to a TCP socket, but need
       to send some header data in front of the file contents, you will find it
       useful to employ the TCP_CORK option, described in tcp(7), to minimize the
       number of packets and to tune performance.

       In Linux 2.4 and earlier, out_fd could also refer to a regular file, and
       sendfile() changed the current offset of that file.

       The original Linux sendfile() system call was not designed to handle large
       file offsets.  Consequently, Linux 2.4 added sendfile64(), with a wider
       type for the offset argument.  The glibc sendfile() wrapper function
       transparently deals with the kernel differences.

       Applications may wish to fall back to read(2)/write(2) in the case where
       sendfile() fails with EINVAL or ENOSYS.

       The Linux-specific splice(2) call supports transferring data between
       arbitrary files (e.g., a pair of sockets).

SEE ALSO top

       mmap(2), open(2), socket(2), splice(2)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-14                         SENDFILE(2)


sendmmsg(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SENDMMSG(2)                  Linux Programmer's Manual                 SENDMMSG(2)

NAME top

       sendmmsg - send multiple messages on a socket

SYNOPSIS top

       #define _GNU_SOURCE
       #include <sys/socket.h>

       int sendmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen,
                    unsigned int flags);

DESCRIPTION top

       The sendmmsg() system call is an extension of sendmsg(2) that allows the
       caller to transmit multiple messages on a socket using a single system
       call.  (This has performance benefits for some applications.)

       The sockfd argument is the file descriptor of the socket on which data is
       to be transmitted.

       The msgvec argument is a pointer to an array of mmsghdr structures.  The
       size of this array is specified in vlen.

       The mmsghdr structure is defined in <sys/socket.h> as:

           struct mmsghdr {
               struct msghdr msg_hdr;  /* Message header */
               unsigned int  msg_len;  /* Number of bytes transmitted */
           };

       The msg_hdr field is a msghdr structure, as described in sendmsg(2).  The
       msg_len field is used to return the number of bytes sent from the message
       in msg_hdr (i.e., the same as the return value from a single sendmsg(2)
       call).

       The flags argument contains flags ORed together.  The flags are the same as
       for sendmsg(2).

       A blocking sendmmsg() call blocks until vlen messages have been sent.  A
       nonblocking call sends as many messages as possible (up to the limit
       specified by vlen) and returns immediately.

       On return from sendmmsg(), the msg_len fields of successive elements of
       msgvec are updated to contain the number of bytes transmitted from the
       corresponding msg_hdr.  The return value of the call indicates the number
       of elements of msgvec that have been updated.

RETURN VALUE top

       On success, sendmmsg() returns the number of messages sent from msgvec; if
       this is less than vlen, the caller can retry with a further sendmmsg() call
       to send the remaining messages.

       On error, -1 is returned, and errno is set to indicate the error.

ERRORS top

       Errors are as for sendmsg(2).  An error is returned only if no datagrams
       could be sent.

VERSIONS top

       The sendmmsg() system call was added in Linux 3.0.  Support in glibc was
       added in version 2.14.

CONFORMING TO top

       sendmmsg() is Linux-specific.

NOTES top

       The value specified in vlen is capped to UIO_MAXIOV (1024).

EXAMPLE top

       The example below uses sendmmsg() to send onetwo and three in two distinct
       UDP datagrams using one system call.  The contents of the first datagram
       originates from a pair of buffers.

       #define _GNU_SOURCE
       #include <netinet/ip.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #include <sys/types.h>
       #include <sys/socket.h>

       int
       main()
       {
           int sockfd;
           struct sockaddr_in sa;
           struct mmsghdr msg[2];
           struct iovec msg1[2], msg2;
           int retval;

           sockfd = socket(AF_INET, SOCK_DGRAM, 0);
           if (sockfd == -1) {
               perror("socket()");
               exit(EXIT_FAILURE);
           }

           sa.sin_family = AF_INET;
           sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
           sa.sin_port = htons(1234);
           if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == -1) {
               perror("connect()");
               exit(EXIT_FAILURE);
           }

           memset(msg1, 0, sizeof(msg1));
           msg1[0].iov_base = "one";
           msg1[0].iov_len = 3;
           msg1[1].iov_base = "two";
           msg1[1].iov_len = 3;

           memset(&msg2, 0, sizeof(msg2));
           msg2.iov_base = "three";
           msg2.iov_len = 5;

           memset(msg, 0, sizeof(msg));
           msg[0].msg_hdr.msg_iov = msg1;
           msg[0].msg_hdr.msg_iovlen = 2;

           msg[1].msg_hdr.msg_iov = &msg2;
           msg[1].msg_hdr.msg_iovlen = 1;

           retval = sendmmsg(sockfd, msg, 2, 0);
           if (retval == -1)
               perror("sendmmsg()");
           else
               printf("%d messages sent\n", retval);

           exit(0);
       }

SEE ALSO top

       recvmmsg(2), sendmsg(2), socket(2), socket(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-16                         SENDMMSG(2)


services(5) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

SERVICES(5)                  Linux Programmer's Manual                 SERVICES(5)

NAME top

       services - Internet network services list

DESCRIPTION top

       services is a plain ASCII file providing a mapping between human-friendly
       textual names for internet services, and their underlying assigned port
       numbers and protocol types.  Every networking program should look into this
       file to get the port number (and protocol) for its service.  The C library
       routines getservent(3), getservbyname(3), getservbyport(3), setservent(3),
       and endservent(3) support querying this file from programs.

       Port numbers are assigned by the IANA (Internet Assigned Numbers
       Authority), and their current policy is to assign both TCP and UDP
       protocols when assigning a port number.  Therefore, most entries will have
       two entries, even for TCP-only services.

       Port numbers below 1024 (so-called "low numbered" ports) can only be bound
       to by root (see bind(2), tcp(7), and udp(7)).  This is so clients
       connecting to low numbered ports can trust that the service running on the
       port is the standard implementation, and not a rogue service run by a user
       of the machine.  Well-known port numbers specified by the IANA are normally
       located in this root-only space.

       The presence of an entry for a service in the services file does not
       necessarily mean that the service is currently running on the machine.  See
       inetd.conf(5) for the configuration of Internet services offered.  Note
       that not all networking services are started by inetd(8), and so won't
       appear in inetd.conf(5).  In particular, news (NNTP) and mail (SMTP)
       servers are often initialized from the system boot scripts.

       The location of the services file is defined by _PATH_SERVICES in
       <netdb.h>.  This is usually set to /etc/services.

       Each line describes one service, and is of the form:

              service-name   port/protocol   [aliases ...]

       where:

       service-name
                 is the friendly name the service is known by and looked up under.
                 It is case sensitive.  Often, the client program is named after
                 the service-name.

       port      is the port number (in decimal) to use for this service.

       protocol  is the type of protocol to be used.  This field should match an
                 entry in the protocols(5) file.  Typical values include tcp and
                 udp.

       aliases   is an optional space or tab separated list of other names for
                 this service.  Again, the names are case sensitive.

       Either spaces or tabs may be used to separate the fields.

       Comments are started by the hash sign (#) and continue until the end of the
       line.  Blank lines are skipped.

       The service-name should begin in the first column of the file, since
       leading spaces are not stripped.  service-names can be any printable
       characters excluding space and tab.  However, a conservative choice of
       characters should be used to minimize compatibility problems.  E.g., a-z,
       0-9, and hyphen (-) would seem a sensible choice.

       Lines not matching this format should not be present in the file.
       (Currently, they are silently skipped by getservent(3), getservbyname(3),
       and getservbyport(3).  However, this behavior should not be relied on.)

       This file might be distributed over a network using a network-wide naming
       service like Yellow Pages/NIS or BIND/Hesiod.

       A sample services file might look like this:

              netstat         15/tcp
              qotd            17/tcp          quote
              msp             18/tcp          # message send protocol
              msp             18/udp          # message send protocol
              chargen         19/tcp          ttytst source
              chargen         19/udp          ttytst source
              ftp             21/tcp
              # 22 - unassigned
              telnet          23/tcp

FILES top

       /etc/services
              The Internet network services list

       <netdb.h>
              Definition of _PATH_SERVICES

SEE ALSO top

       listen(2), endservent(3), getservbyname(3), getservbyport(3),
       getservent(3), setservent(3), inetd.conf(5), protocols(5), inetd(8)

       Assigned Numbers RFC, most recently RFC 1700, (AKA STD0002).

COLOPHON top

       This page is part of release 3.45 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                               2010-05-22                         SERVICES(5)


setbuf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SETBUF(3)                    Linux Programmer's Manual                   SETBUF(3)

NAME top

       setbuf, setbuffer, setlinebuf, setvbuf - stream buffering operations

SYNOPSIS top

       #include <stdio.h>

       void setbuf(FILE *stream, char *buf);

       void setbuffer(FILE *stream, char *buf, size_t size);

       void setlinebuf(FILE *stream);

       int setvbuf(FILE *stream, char *buf, int mode, size_t size);

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

       setbuffer(), setlinebuf(): _BSD_SOURCE

DESCRIPTION top

       The three types of buffering available are unbuffered, block buffered, and
       line buffered.  When an output stream is unbuffered, information appears on
       the destination file or terminal as soon as written; when it is block
       buffered many characters are saved up and written as a block; when it is
       line buffered characters are saved up until a newline is output or input is
       read from any stream attached to a terminal device (typically stdin).  The
       function fflush(3) may be used to force the block out early.  (See
       fclose(3).)  Normally all files are block buffered.  When the first I/O
       operation occurs on a file, malloc(3) is called, and a buffer is obtained.
       If a stream refers to a terminal (as stdout normally does) it is line
       buffered.  The standard error stream stderr is always unbuffered by
       default.

       The setvbuf() function may be used on any open stream to change its buffer.
       The mode argument must be one of the following three macros:

              _IONBF unbuffered

              _IOLBF line buffered

              _IOFBF fully buffered

       Except for unbuffered files, the buf argument should point to a buffer at
       least size bytes long; this buffer will be used instead of the current
       buffer.  If the argument buf is NULL, only the mode is affected; a new
       buffer will be allocated on the next read or write operation.  The
       setvbuf() function may only be used after opening a stream and before any
       other operations have been performed on it.

       The other three calls are, in effect, simply aliases for calls to
       setvbuf().  The setbuf() function is exactly equivalent to the call

           setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

       The setbuffer() function is the same, except that the size of the buffer is
       up to the caller, rather than being determined by the default BUFSIZ.  The
       setlinebuf() function is exactly equivalent to the call:

           setvbuf(stream, NULL, _IOLBF, 0);

RETURN VALUE top

       The function setvbuf() returns 0 on success.  It returns nonzero on failure
       (mode is invalid or the request cannot be honored).  It may set errno on
       failure.

       The other functions do not return a value.

CONFORMING TO top

       The setbuf() and setvbuf() functions conform to C89 and C99.

BUGS top

       The setbuffer() and setlinebuf() functions are not portable to versions of
       BSD before 4.2BSD, and are available under Linux since libc 4.5.21.  On
       4.2BSD and 4.3BSD systems, setbuf() always uses a suboptimal buffer size
       and should be avoided.

       You must make sure that the space that buf points to still exists by the
       time stream is closed, which also happens at program termination.  For
       example, the following is invalid:

       #include <stdio.h>

       int
       main(void)
       {
           char buf[BUFSIZ];
           setbuf(stdin, buf);
           printf("Hello, world!\n");
           return 0;
       }

SEE ALSO top

       fclose(3), fflush(3), fopen(3), fread(3), malloc(3), printf(3), puts(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-03                           SETBUF(3)


seteuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETEUID(2)                   Linux Programmer's Manual                  SETEUID(2)

NAME top

       seteuid, setegid - set effective user or group ID

SYNOPSIS top

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

       int seteuid(uid_t euid);
       int setegid(gid_t egid);

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

       seteuid(), setegid():
           _BSD_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       seteuid() sets the effective user ID of the calling process.  Unprivileged
       user processes may only set the effective user ID to the real user ID, the
       effective user ID or the saved set-user-ID.

       Precisely the same holds for setegid() with "group" instead of "user".

RETURN VALUE top

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

ERRORS top

       EPERM  The calling process is not privileged (Linux: does not have the
              CAP_SETUID capability in the case of seteuid(), or the CAP_SETGID
              capability in the case of setegid()) and euid (respectively, egid)
              is not the real user (group) ID, the effective user (group) ID, or
              the saved set-user-ID (saved set-group-ID).

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

NOTES top

       Setting the effective user (group) ID to the saved set-user-ID (saved set-
       group-ID) is possible since Linux 1.1.37 (1.1.38).  On an arbitrary system
       one should check _POSIX_SAVED_IDS.

       Under libc4, libc5 and glibc 2.0 seteuid(euid) is equivalent to
       setreuid(-1, euid) and hence may change the saved set-user-ID.  Under glibc
       2.1 and later it is equivalent to setresuid(-1, euid, -1) and hence does
       not change the saved set-user-ID.  Analogous remarks hold for setegid(),
       with the difference that the change in implementation from setregid(-1,
       egid) to setresgid(-1, egid, -1) occurred in glibc 2.2 or 2.3 (dependeing
       on the hardware architecture).

       According to POSIX.1, seteuid() (setegid()) need not permit euid (egid) to
       be the same value as the current effective user (group) ID, and some
       implementations do not permit this.

SEE ALSO top

       geteuid(2), setresuid(2), setreuid(2), setuid(2), capabilities(7),
       credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-02                          SETEUID(2)


setenv(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SETENV(3)                    Linux Programmer's Manual                   SETENV(3)

NAME top

       setenv - change or add an environment variable

SYNOPSIS top

       #include <stdlib.h>

       int setenv(const char *name, const char *value, int overwrite);

       int unsetenv(const char *name);

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

       setenv(), unsetenv():
           _BSD_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       The setenv() function adds the variable name to the environment with the
       value value, if name does not already exist.  If name does exist in the
       environment, then its value is changed to value if overwrite is nonzero; if
       overwrite is zero, then the value of name is not changed.  This function
       makes copies of the strings pointed to by name and value (by contrast with
       putenv(3)).

       The unsetenv() function deletes the variable name from the environment.  If
       name does not exist in the environment, then the function succeeds, and the
       environment is unchanged.

RETURN VALUE top

       The setenv() function returns zero on success, or -1 on error, with errno
       set to indicate the cause of the error.

       The unsetenv() function returns zero on success, or -1 on error, with errno
       set to indicate the cause of the error.

ERRORS top

       EINVAL name is NULL, points to a string of length 0, or contains an '='
              character.

       ENOMEM Insufficient memory to add a new variable to the environment.

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

NOTES top

       POSIX.1-2001 does not require setenv() or unsetenv() to be reentrant.

       Prior to glibc 2.2.2, unsetenv() was prototyped as returning void; more
       recent glibc versions follow the POSIX.1-2001-compliant prototype shown in
       the SYNOPSIS.

BUGS top

       POSIX.1-2001 specifies that if name contains an '=' character, then
       setenv() should fail with the error EINVAL; however, versions of glibc
       before 2.3.4 allowed an '=' sign in name.

SEE ALSO top

       clearenv(3), getenv(3), putenv(3), environ(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-09-20                           SETENV(3)


setfsgid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SETFSGID(2)                  Linux Programmer's Manual                 SETFSGID(2)

NAME top

       setfsgid - set group identity used for file system checks

SYNOPSIS top

       #include <unistd.h> /* glibc uses <sys/fsuid.h> */

       int setfsgid(uid_t fsgid);

DESCRIPTION top

       The system call setfsgid() sets the group ID that the Linux kernel uses to
       check for all accesses to the file system.  Normally, the value of fsgid
       will shadow the value of the effective group ID.  In fact, whenever the
       effective group ID is changed, fsgid will also be changed to the new value
       of the effective group ID.

       Explicit calls to setfsuid(2) and setfsgid() are usually only used by
       programs such as the Linux NFS server that need to change what user and
       group ID is used for file access without a corresponding change in the real
       and effective user and group IDs.  A change in the normal user IDs for a
       program such as the NFS server is a security hole that can expose it to
       unwanted signals.  (But see below.)

       setfsgid() will only succeed if the caller is the superuser or if fsgid
       matches either the real group ID, effective group ID, saved set-group-ID,
       or the current value of fsgid.

RETURN VALUE top

       On success, the previous value of fsgid is returned.  On error, the current
       value of fsgid is returned.

VERSIONS top

       This system call is present in Linux since version 1.2.

CONFORMING TO top

       setfsgid() is Linux-specific and should not be used in programs intended to
       be portable.

NOTES top

       When glibc determines that the argument is not a valid group ID, it will
       return -1 and set errno to EINVAL without attempting the system call.

       Note that at the time this system call was introduced, a process could send
       a signal to a process with the same effective user ID.  Today signal
       permission handling is slightly different.

       The original Linux setfsgid() system call supported only 16-bit group IDs.
       Subsequently, Linux 2.4 added setfsgid32() supporting 32-bit IDs.  The
       glibc setfsgid() wrapper function transparently deals with the variation
       across kernel versions.

BUGS top

       No error messages of any kind are returned to the caller.  At the very
       least, EPERM should be returned when the call fails (because the caller
       lacks the CAP_SETGID capability).

SEE ALSO top

       kill(2), setfsuid(2), capabilities(7), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                         SETFSGID(2)


setfsuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SETFSUID(2)                  Linux Programmer's Manual                 SETFSUID(2)

NAME top

       setfsuid - set user identity used for file system checks

SYNOPSIS top

       #include <unistd.h> /* glibc uses <sys/fsuid.h> */

       int setfsuid(uid_t fsuid);

DESCRIPTION top

       The system call setfsuid() sets the user ID that the Linux kernel uses to
       check for all accesses to the file system.  Normally, the value of fsuid
       will shadow the value of the effective user ID.  In fact, whenever the
       effective user ID is changed, fsuid will also be changed to the new value
       of the effective user ID.

       Explicit calls to setfsuid() and setfsgid(2) are usually only used by
       programs such as the Linux NFS server that need to change what user and
       group ID is used for file access without a corresponding change in the real
       and effective user and group IDs.  A change in the normal user IDs for a
       program such as the NFS server is a security hole that can expose it to
       unwanted signals.  (But see below.)

       setfsuid() will only succeed if the caller is the superuser or if fsuid
       matches either the real user ID, effective user ID, saved set-user-ID, or
       the current value of fsuid.

RETURN VALUE top

       On success, the previous value of fsuid is returned.  On error, the current
       value of fsuid is returned.

VERSIONS top

       This system call is present in Linux since version 1.2.

CONFORMING TO top

       setfsuid() is Linux-specific and should not be used in programs intended to
       be portable.

NOTES top

       When glibc determines that the argument is not a valid user ID, it will
       return -1 and set errno to EINVAL without attempting the system call.

       Note that at the time this system call was introduced, a process could send
       a signal to a process with the same effective user ID.  Today signal
       permission handling is slightly different.

       The original Linux setfsuid() system call supported only 16-bit user IDs.
       Subsequently, Linux 2.4 added setfsuid32() supporting 32-bit IDs.  The
       glibc setfsuid() wrapper function transparently deals with the variation
       across kernel versions.

BUGS top

       No error messages of any kind are returned to the caller.  At the very
       least, EPERM should be returned when the call fails (because the caller
       lacks the CAP_SETUID capability).

SEE ALSO top

       kill(2), setfsgid(2), capabilities(7), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                         SETFSUID(2)


setgid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | NOTES | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SETGID(2)                    Linux Programmer's Manual                   SETGID(2)

NAME top

       setgid - set group identity

SYNOPSIS top

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

       int setgid(gid_t gid);

DESCRIPTION top

       setgid() sets the effective group ID of the calling process.  If the caller
       is the superuser, the real GID and saved set-group-ID are also set.

       Under Linux, setgid() is implemented like the POSIX version with the
       _POSIX_SAVED_IDS feature.  This allows a set-group-ID program that is not
       set-user-ID-root to drop all of its group privileges, do some un-privileged
       work, and then reengage the original effective group ID in a secure manner.

RETURN VALUE top

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

ERRORS top

       EPERM  The calling process is not privileged (does not have the CAP_SETGID
              capability), and gid does not match the real group ID or saved set-
              group-ID of the calling process.

NOTES top

       The original Linux setgid() system call supported only 16-bit group IDs.
       Subsequently, Linux 2.4 added setgid32() supporting 32-bit IDs.  The glibc
       setgid() wrapper function transparently deals with the variation across
       kernel versions.

CONFORMING TO top

       SVr4, POSIX.1-2001.

SEE ALSO top

       getgid(2), setegid(2), setregid(2), capabilities(7), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                           SETGID(2)


setjmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETJMP(3)                    Linux Programmer's Manual                   SETJMP(3)

NAME top

       setjmp, sigsetjmp - save stack context for nonlocal goto

SYNOPSIS top

       #include <setjmp.h>

       int setjmp(jmp_buf env);

       int sigsetjmp(sigjmp_buf env, int savesigs);

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

       setjmp(): see NOTES.
       sigsetjmp(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_C_SOURCE

DESCRIPTION top

       setjmp() and longjmp(3) are useful for dealing with errors and interrupts
       encountered in a low-level subroutine of a program.  setjmp() saves the
       stack context/environment in env for later use by longjmp(3).  The stack
       context will be invalidated if the function which called setjmp() returns.

       sigsetjmp() is similar to setjmp().  If, and only if, savesigs is nonzero,
       the process's current signal mask is saved in env and will be restored if a
       siglongjmp(3) is later performed with this env.

RETURN VALUE top

       setjmp() and sigsetjmp() return 0 if returning directly, and nonzero when
       returning from longjmp(3) or siglongjmp(3) using the saved context.

CONFORMING TO top

       C89, C99, and POSIX.1-2001 specify setjmp().  POSIX.1-2001 specifies
       sigsetjmp().

NOTES top

       POSIX does not specify whether setjmp() will save the signal mask.  In
       System V it will not.  In 4.3BSD it will, and there is a function _setjmp
       that will not.  By default, Linux/glibc follows the System V behavior, but
       the BSD behavior is provided if the _BSD_SOURCE feature test macro is
       defined and none of _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE,
       _XOPEN_SOURCE_EXTENDED, _GNU_SOURCE, or _SVID_SOURCE is defined.

       If you want to portably save and restore signal masks, use sigsetjmp() and
       siglongjmp(3).

       setjmp() and sigsetjmp() make programs hard to understand and maintain.  If
       possible an alternative should be used.

SEE ALSO top

       longjmp(3), siglongjmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-06-26                           SETJMP(3)


setlocale(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETLOCALE(3)                 Linux Programmer's Manual                SETLOCALE(3)

NAME top

       setlocale - set the current locale

SYNOPSIS top

       #include <locale.h>

       char *setlocale(int category, const char *locale);

DESCRIPTION top

       The setlocale() function is used to set or query the program's current
       locale.

       If locale is not NULL, the program's current locale is modified according
       to the arguments.  The argument category determines which parts of the
       program's current locale should be modified.

       LC_ALL for all of the locale.

       LC_COLLATE
              for regular expression matching (it determines the meaning of range
              expressions and equivalence classes) and string collation.

       LC_CTYPE
              for regular expression matching, character classification,
              conversion, case-sensitive comparison, and wide character functions.

       LC_MESSAGES
              for localizable natural-language messages.

       LC_MONETARY
              for monetary formatting.

       LC_NUMERIC
              for number formatting (such as the decimal point and the thousands
              separator).

       LC_TIME
              for time and date formatting.

       The argument locale is a pointer to a character string containing the
       required setting of category.  Such a string is either a well-known
       constant like "C" or "da_DK" (see below), or an opaque string that was
       returned by another call of setlocale().

       If locale is "", each part of the locale that should be modified is set
       according to the environment variables.  The details are implementation-
       dependent.  For glibc, first (regardless of category), the environment
       variable LC_ALL is inspected, next the environment variable with the same
       name as the category (LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY,
       LC_NUMERIC, LC_TIME) and finally the environment variable LANG.  The first
       existing environment variable is used.  If its value is not a valid locale
       specification, the locale is unchanged, and setlocale() returns NULL.

       The locale "C" or "POSIX" is a portable locale; its LC_CTYPE part
       corresponds to the 7-bit ASCII character set.

       A locale name is typically of the form
       language[_territory][.codeset][@modifier], where language is an ISO 639
       language code, territory is an ISO 3166 country code, and codeset is a
       character set or encoding identifier like ISO-8859-1 or UTF-8.  For a list
       of all supported locales, try "locale -a", cf. locale(1).

       If locale is NULL, the current locale is only queried, not modified.

       On startup of the main program, the portable "C" locale is selected as
       default.  A program may be made portable to all locales by calling:

           setlocale(LC_ALL, "");

       after program initialization, by using the values returned from a
       localeconv(3) call for locale-dependent information, by using the multibyte
       and wide character functions for text processing if MB_CUR_MAX > 1, and by
       using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.

RETURN VALUE top

       A successful call to setlocale() returns an opaque string that corresponds
       to the locale set.  This string may be allocated in static storage.  The
       string returned is such that a subsequent call with that string and its
       associated category will restore that part of the process's locale.  The
       return value is NULL if the request cannot be honored.

CONFORMING TO top

       C89, C99, POSIX.1-2001.

NOTES top

       Linux (that is, glibc) supports the portable locales "C" and "POSIX".  In
       the good old days there used to be support for the European Latin-1
       "ISO-8859-1" locale (e.g., in libc-4.5.21 and libc-4.6.27), and the Russian
       "KOI-8" (more precisely, "koi-8r") locale (e.g., in libc-4.6.27), so that
       having an environment variable LC_CTYPE=ISO-8859-1 sufficed to make
       isprint(3) return the right answer.  These days non-English speaking
       Europeans have to work a bit harder, and must install actual locale files.

SEE ALSO top

       locale(1), localedef(1), isalpha(3), localeconv(3), nl_langinfo(3),
       rpmatch(3), strcoll(3), strftime(3), charsets(7), locale(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-12-05                        SETLOCALE(3)


setlogmask(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SETLOGMASK(3)                Linux Programmer's Manual               SETLOGMASK(3)

NAME top

       setlogmask - set log priority mask

SYNOPSIS top

       #include <syslog.h>

       int setlogmask(int mask);

DESCRIPTION top

       A process has a log priority mask that determines which calls to syslog(3)
       may be logged.  All other calls will be ignored.  Logging is enabled for
       the priorities that have the corresponding bit set in mask.  The initial
       mask is such that logging is enabled for all priorities.

       The setlogmask() function sets this logmask for the calling process, and
       returns the previous mask.  If the mask argument is 0, the current logmask
       is not modified.

       The eight priorities are LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
       LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG.  The bit corresponding to
       a priority p is LOG_MASK(p).  Some systems also provide a macro LOG_UPTO(p)
       for the mask of all priorities in the above list up to and including p.

RETURN VALUE top

       This function returns the previous log priority mask.

ERRORS top

       None.

CONFORMING TO top

       POSIX.1-2001.  Note that the description in POSIX.1-2001 is flawed.

SEE ALSO top

       closelog(3), openlog(3), syslog(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-10-05                       SETLOGMASK(3)


setns(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SETNS(2)                     Linux Programmer's Manual                    SETNS(2)

NAME top

       setns - reassociate thread with a namespace

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sched.h>

       int setns(int fd, int nstype);

DESCRIPTION top

       Given a file descriptor referring to a namespace, reassociate the calling
       thread with that namespace.

       The fd argument is a file descriptor referring to one of the namespace
       entries in a /proc/[pid]/ns/ directory; see proc(5) for further information
       on /proc/[pid]/ns/.  The calling thread will be reassociated with the
       corresponding namespace, subject to any constraints imposed by the nstype
       argument.

       The nstype argument specifies which type of namespace the calling thread
       may be reassociated with.  This argument can have one of the following
       values:

       0      Allow any type of namespace to be joined.

       CLONE_NEWIPC
              fd must refer to an IPC namespace.

       CLONE_NEWNET
              fd must refer to a network namespace.

       CLONE_NEWUTS
              fd must refer to a UTS namespace.

       Specifying nstype as 0 suffices if the caller knows (or does not care) what
       type of namespace is referred to by fd.  Specifying a nonzero value for
       nstype is useful if the caller does not know what type of namespace is
       referred to by fd and wants to ensure that the namespace is of a particular
       type.  (The caller might not know the type of the namespace referred to by
       fd if the file descriptor was opened by another process and, for example,
       passed to the caller via a UNIX domain socket.)

RETURN VALUE top

       On success, setns() returns 0.  On failure, -1 is returned and errno is set
       to indicate the error.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       EINVAL fd refers to a namespace whose type does not match that specified in
              nstype, or there is problem with reassociating the the thread with
              the specified namespace.

       ENOMEM Cannot allocate sufficient memory to change the specified namespace.

       EPERM  The calling thread did not have the required privilege
              (CAP_SYS_ADMIN) for this operation.

VERSIONS top

       The setns() system call first appeared in Linux in kernel 3.0; library
       support was added to glibc in version 2.14.

CONFORMING TO top

       The setns() system call is Linux-specific.

NOTES top

       Not all of the attributes that can be shared when a new thread is created
       using clone(2) can be changed using setns().

BUGS top

       The PID namespace and the mount namespace are not currently supported.
       (See the descriptions of CLONE_NEWPID and CLONE_NEWNS in clone(2).)

SEE ALSO top

       clone(2), fork(2), vfork(2), proc(5), unix(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                            SETNS(2)


setreuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETREUID(2)                  Linux Programmer's Manual                 SETREUID(2)

NAME top

       setreuid, setregid - set real and/or effective user or group ID

SYNOPSIS top

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

       int setreuid(uid_t ruid, uid_t euid);
       int setregid(gid_t rgid, gid_t egid);

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

       setreuid(), setregid():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       setreuid() sets real and effective user IDs of the calling process.

       Supplying a value of -1 for either the real or effective user ID forces the
       system to leave that ID unchanged.

       Unprivileged processes may only set the effective user ID to the real user
       ID, the effective user ID, or the saved set-user-ID.

       Unprivileged users may only set the real user ID to the real user ID or the
       effective user ID.

       If the real user ID is set or the effective user ID is set to a value not
       equal to the previous real user ID, the saved set-user-ID will be set to
       the new effective user ID.

       Completely analogously, setregid() sets real and effective group ID's of
       the calling process, and all of the above holds with "group" instead of
       "user".

RETURN VALUE top

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

ERRORS top

       EPERM  The calling process is not privileged (Linux: does not have the
              CAP_SETUID capability in the case of setreuid(), or the CAP_SETGID
              capability in the case of setregid()) and a change other than (i)
              swapping the effective user (group) ID with the real user (group)
              ID, or (ii) setting one to the value of the other or (iii) setting
              the effective user (group) ID to the value of the saved set-user-ID
              (saved set-group-ID) was specified.

CONFORMING TO top

       POSIX.1-2001, 4.3BSD (the setreuid() and setregid() function calls first
       appeared in 4.2BSD).

NOTES top

       Setting the effective user (group) ID to the saved set-user-ID (saved set-
       group-ID) is possible since Linux 1.1.37 (1.1.38).

       POSIX.1 does not specify all of possible ID changes that are permitted on
       Linux for an unprivileged process.  For setreuid(), the effective user ID
       can be made the same as the real user ID or the save set-user-ID, and it is
       unspecified whether unprivileged processes may set the real user ID to the
       real user ID, the effective user ID, or the saved set-user-ID.  For
       setregid(), the real group ID can be changed to the value of the saved set-
       group-ID, and the effective group ID can be changed to the value of the
       real group ID or the saved set-group-ID.  The precise details of what ID
       changes are permitted vary across implementations.

       POSIX.1 makes no specification about the effect of these calls on the saved
       set-user-ID and saved set-group-ID.

       The original Linux setreuid() and setregid() system calls supported only
       16-bit user and group IDs.  Subsequently, Linux 2.4 added setreuid32() and
       setregid32(), supporting 32-bit IDs.  The glibc setreuid() and setregid()
       wrapper functions transparently deal with the variations across kernel
       versions.

SEE ALSO top

       getgid(2), getuid(2), seteuid(2), setgid(2), setresuid(2), setuid(2),
       capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                         SETREUID(2)


setresuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETRESUID(2)                 Linux Programmer's Manual                SETRESUID(2)

NAME top

       setresuid, setresgid - set real, effective and saved user or group ID

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>

       int setresuid(uid_t ruid, uid_t euid, uid_t suid);
       int setresgid(gid_t rgid, gid_t egid, gid_t sgid);

DESCRIPTION top

       setresuid() sets the real user ID, the effective user ID, and the saved
       set-user-ID of the calling process.

       Unprivileged user processes may change the real UID, effective UID, and
       saved set-user-ID, each to one of: the current real UID, the current
       effective UID or the current saved set-user-ID.

       Privileged processes (on Linux, those having the CAP_SETUID capability) may
       set the real UID, effective UID, and saved set-user-ID to arbitrary values.

       If one of the arguments equals -1, the corresponding value is not changed.

       Regardless of what changes are made to the real UID, effective UID, and
       saved set-user-ID, the file system UID is always set to the same value as
       the (possibly new) effective UID.

       Completely analogously, setresgid() sets the real GID, effective GID, and
       saved set-group-ID of the calling process (and always modifies the file
       system GID to be the same as the effective GID), with the same restrictions
       for unprivileged processes.

RETURN VALUE top

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

ERRORS top

       EAGAIN uid does not match the current UID and this call would bring that
              user ID over its RLIMIT_NPROC resource limit.

       EPERM  The calling process is not privileged (did not have the CAP_SETUID
              capability) and tried to change the IDs to values that are not
              permitted.

VERSIONS top

       These calls are available under Linux since Linux 2.1.44.

CONFORMING TO top

       These calls are nonstandard; they also appear on HP-UX and some of the
       BSDs.

NOTES top

       Under HP-UX and FreeBSD, the prototype is found in <unistd.h>.  Under Linux
       the prototype is provided by glibc since version 2.3.2.

       The original Linux setresuid() and setresgid() system calls supported only
       16-bit user and group IDs.  Subsequently, Linux 2.4 added setresuid32() and
       setresgid32(), supporting 32-bit IDs.  The glibc setresuid() and
       setresgid() wrapper functions transparently deal with the variations across
       kernel versions.

SEE ALSO top

       getresuid(2), getuid(2), setfsgid(2), setfsuid(2), setreuid(2), setuid(2),
       capabilities(7), credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                        SETRESUID(2)


setsid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETSID(2)                    Linux Programmer's Manual                   SETSID(2)

NAME top

       setsid - creates a session and sets the process group ID

SYNOPSIS top

       #include <unistd.h>

       pid_t setsid(void);

DESCRIPTION top

       setsid() creates a new session if the calling process is not a process
       group leader.  The calling process is the leader of the new session, the
       process group leader of the new process group, and has no controlling tty.
       The process group ID and session ID of the calling process are set to the
       PID of the calling process.  The calling process will be the only process
       in this new process group and in this new session.

RETURN VALUE top

       On success, the (new) session ID of the calling process is returned.  On
       error, (pid_t) -1 is returned, and errno is set to indicate the error.

ERRORS top

       EPERM  The process group ID of any process equals the PID of the calling
              process.  Thus, in particular, setsid() fails if the calling process
              is already a process group leader.

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       A child created via fork(2) inherits its parent's session ID.  The session
       ID is preserved across an execve(2).

       A process group leader is a process with process group ID equal to its PID.
       In order to be sure that setsid() will succeed, fork(2) and _exit(2), and
       have the child do setsid().

SEE ALSO top

       getsid(2), setpgid(2), setpgrp(2), tcgetsid(3), credentials(7)

COLOPHON top

       This page is part of release 3.45 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-03                           SETSID(2)


setuid(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SETUID(2)                    Linux Programmer's Manual                   SETUID(2)

NAME top

       setuid - set user identity

SYNOPSIS top

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

       int setuid(uid_t uid);

DESCRIPTION top

       setuid() sets the effective user ID of the calling process.  If the
       effective UID of the caller is root, the real UID and saved set-user-ID are
       also set.

       Under Linux, setuid() is implemented like the POSIX version with the
       _POSIX_SAVED_IDS feature.  This allows a set-user-ID (other than root)
       program to drop all of its user privileges, do some un-privileged work, and
       then reengage the original effective user ID in a secure manner.

       If the user is root or the program is set-user-ID-root, special care must
       be taken.  The setuid() function checks the effective user ID of the caller
       and if it is the superuser, all process-related user ID's are set to uid.
       After this has occurred, it is impossible for the program to regain root
       privileges.

       Thus, a set-user-ID-root program wishing to temporarily drop root
       privileges, assume the identity of an unprivileged user, and then regain
       root privileges afterward cannot use setuid().  You can accomplish this
       with seteuid(2).

RETURN VALUE top

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

ERRORS top

       EAGAIN The uid does not match the current uid and uid brings process over
              its RLIMIT_NPROC resource limit.

       EPERM  The user is not privileged (Linux: does not have the CAP_SETUID
              capability) and uid does not match the real UID or saved set-user-ID
              of the calling process.

CONFORMING TO top

       SVr4, POSIX.1-2001.  Not quite compatible with the 4.4BSD call, which sets
       all of the real, saved, and effective user IDs.

NOTES top

       Linux has the concept of the file system user ID, normally equal to the
       effective user ID.  The setuid() call also sets the file system user ID of
       the calling process.  See setfsuid(2).

       If uid is different from the old effective UID, the process will be
       forbidden from leaving core dumps.

       The original Linux setuid() system call supported only 16-bit user IDs.
       Subsequently, Linux 2.4 added setuid32() supporting 32-bit IDs.  The glibc
       setuid() wrapper function transparently deals with the variation across
       kernel versions.

SEE ALSO top

       getuid(2), seteuid(2), setfsuid(2), setreuid(2), capabilities(7),
       credentials(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-22                           SETUID(2)


setup(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | COLOPHON The Linux Programming Interface

SETUP(2)                     Linux Programmer's Manual                    SETUP(2)

NAME top

       setup - setup devices and file systems, mount root file system

SYNOPSIS top

       #include <unistd.h>

       int setup(void);

DESCRIPTION top

       setup() is called once from within linux/init/main.c.  It calls
       initialization functions for devices and file systems configured into the
       kernel and then mounts the root file system.

       No user process may call setup().  Any user process, even a process with
       superuser permission, will receive EPERM.

RETURN VALUE top

       setup() always returns -1 for a user process.

ERRORS top

       EPERM  Always, for a user process.

VERSIONS top

       Since Linux 2.1.121, no such function exists anymore.

CONFORMING TO top

       This function is Linux-specific, and should not be used in programs
       intended to be portable, or indeed in any programs at all.

NOTES top

       The calling sequence varied: at some times setup () has had a single
       argument void *BIOS and at other times a single argument int magic.

COLOPHON top

       This page is part of release 3.45 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-03                            SETUP(2)


set_mempolicy(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SET_MEMPOLICY(2)             Linux Programmer's Manual            SET_MEMPOLICY(2)

NAME top

       set_mempolicy  - set default NUMA memory policy for a process and its chil-
       dren

SYNOPSIS top

       #include <numaif.h>

       int set_mempolicy(int mode, unsigned long *nodemask,
                         unsigned long maxnode);

       Link with -lnuma.

DESCRIPTION top

       set_mempolicy() sets the NUMA memory policy of the calling process, which
       consists of a policy mode and zero or more nodes, to the values specified
       by the mode, nodemask and maxnode arguments.

       A NUMA machine has different memory controllers with different distances to
       specific CPUs.  The memory policy defines from which node memory is
       allocated for the process.

       This system call defines the default policy for the process.  The process
       policy governs allocation of pages in the process's address space outside
       of memory ranges controlled by a more specific policy set by mbind(2).  The
       process default policy also controls allocation of any pages for memory
       mapped files mapped using the mmap(2) call with the MAP_PRIVATE flag and
       that are only read [loaded] from by the process and of memory mapped files
       mapped using the mmap(2) call with the MAP_SHARED flag, regardless of the
       access type.  The policy is only applied when a new page is allocated for
       the process.  For anonymous memory this is when the page is first touched
       by the application.

       The mode argument must specify one of MPOL_DEFAULT, MPOL_BIND,
       MPOL_INTERLEAVE or MPOL_PREFERRED.  All modes except MPOL_DEFAULT require
       the caller to specify via the nodemask argument one or more nodes.

       The mode argument may also include an optional mode flag.  The supported
       mode flags are:

       MPOL_F_STATIC_NODES (since Linux 2.6.26)
              A nonempty nodemask specifies physical node ids.  Linux does will
              not remap the nodemask when the process moves to a different cpuset
              context, nor when the set of nodes allowed by the process's current
              cpuset context changes.

       MPOL_F_RELATIVE_NODES (since Linux 2.6.26)
              A nonempty nodemask specifies node ids that are relative to the set
              of node ids allowed by the process's current cpuset.

       nodemask points to a bit mask of node IDs that contains up to maxnode bits.
       The bit mask size is rounded to the next multiple of sizeof(unsigned long),
       but the kernel will only use bits up to maxnode.  A NULL value of nodemask
       or a maxnode value of zero specifies the empty set of nodes.  If the value
       of maxnode is zero, the nodemask argument is ignored.

       Where a nodemask is required, it must contain at least one node that is on-
       line, allowed by the process's current cpuset context, [unless the
       MPOL_F_STATIC_NODES mode flag is specified], and contains memory.  If the
       MPOL_F_STATIC_NODES is set in mode and a required nodemask contains no
       nodes that are allowed by the process's current cpuset context, the memory
       policy reverts to local allocation.  This effectively overrides the
       specified policy until the process's cpuset context includes one or more of
       the nodes specified by nodemask.

       The MPOL_DEFAULT mode specifies that any nondefault process memory policy
       be removed, so that the memory policy "falls back" to the system default
       policy.  The system default policy is "local allocation"-- i.e., allocate
       memory on the node of the CPU that triggered the allocation.  nodemask must
       be specified as NULL.  If the "local node" contains no free memory, the
       system will attempt to allocate memory from a "near by" node.

       The MPOL_BIND mode defines a strict policy that restricts memory allocation
       to the nodes specified in nodemask.  If nodemask specifies more than one
       node, page allocations will come from the node with the lowest numeric node
       ID first, until that node contains no free memory.  Allocations will then
       come from the node with the next highest node ID specified in nodemask and
       so forth, until none of the specified nodes contain free memory.  Pages
       will not be allocated from any node not specified in the nodemask.

       MPOL_INTERLEAVE interleaves page allocations across the nodes specified in
       nodemask in numeric node ID order.  This optimizes for bandwidth instead of
       latency by spreading out pages and memory accesses to those pages across
       multiple nodes.  However, accesses to a single page will still be limited
       to the memory bandwidth of a single node.

       MPOL_PREFERRED sets the preferred node for allocation.  The kernel will try
       to allocate pages from this node first and fall back to "near by" nodes if
       the preferred node is low on free memory.  If nodemask specifies more than
       one node ID, the first node in the mask will be selected as the preferred
       node.  If the nodemask and maxnode arguments specify the empty set, then
       the policy specifies "local allocation" (like the system default policy
       discussed above).

       The process memory policy is preserved across an execve(2), and is
       inherited by child processes created using fork(2) or clone(2).

RETURN VALUE top

       On success, set_mempolicy() returns 0; on error, -1 is returned and errno
       is set to indicate the error.

ERRORS top

       EFAULT Part of all of the memory range specified by nodemask and maxnode
              points outside your accessible address space.

       EINVAL mode is invalid.  Or, mode is MPOL_DEFAULT and nodemask is nonempty,
              or mode is MPOL_BIND or MPOL_INTERLEAVE and nodemask is empty.  Or,
              maxnode specifies more than a page worth of bits.  Or, nodemask
              specifies one or more node IDs that are greater than the maximum
              supported node ID.  Or, none of the node IDs specified by nodemask
              are on-line and allowed by the process's current cpuset context, or
              none of the specified nodes contain memory.  Or, the mode argument
              specified both MPOL_F_STATIC_NODES and MPOL_F_RELATIVE_NODES.

       ENOMEM Insufficient kernel memory was available.

VERSIONS top

       The set_mempolicy(), system call was added to the Linux kernel in version
       2.6.7.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       Process policy is not remembered if the page is swapped out.  When such a
       page is paged back in, it will use the policy of the process or memory
       range that is in effect at the time the page is allocated.

       For information on library support, see numa(7).

SEE ALSO top

       get_mempolicy(2), getcpu(2), mbind(2), mmap(2), numa(3), cpuset(7),
       numa(7), numactl(8)

COLOPHON top

       This page is part of release 3.45 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-15                    SET_MEMPOLICY(2)


set_thread_area(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SET_THREAD_AREA(2)           Linux Programmer's Manual          SET_THREAD_AREA(2)

NAME top

       set_thread_area - set a thread local storage (TLS) area

SYNOPSIS top

       #include <linux/unistd.h>
       #include <asm/ldt.h>

       int set_thread_area(struct user_desc *u_info);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       set_thread_area() sets an entry in the current thread's thread-local
       storage (TLS) array.  The TLS array entry set by set_thread_area()
       corresponds to the value of u_info->entry_number passed in by the user.  If
       this value is in bounds, set_thread_area() copies the TLS descriptor
       pointed to by u_info into the thread's TLS array.

       When set_thread_area() is passed an entry_number of -1, it uses a free TLS
       entry.  If set_thread_area() finds a free TLS entry, the value of
       u_info->entry_number is set upon return to show which entry was changed.

RETURN VALUE top

       set_thread_area() returns 0 on success, and -1 on failure, with errno set
       appropriately.

ERRORS top

       EINVAL u_info->entry_number is out of bounds.

       EFAULT u_info is an invalid pointer.

       ESRCH  A free TLS entry could not be located.

VERSIONS top

       A version of set_thread_area() first appeared in Linux 2.5.29.

CONFORMING TO top

       set_thread_area() is Linux-specific and should not be used in programs that
       are intended to be portable.

NOTES top

       Glibc does not provide a wrapper for this system call, since it is
       generally intended only for use by threading libraries.  In the unlikely
       event that you want to call it directly, use syscall(2).

SEE ALSO top

       get_thread_area(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                  SET_THREAD_AREA(2)


set_tid_address(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SET_TID_ADDRESS(2)           Linux Programmer's Manual          SET_TID_ADDRESS(2)

NAME top

       set_tid_address - set pointer to thread ID

SYNOPSIS top

       #include <linux/unistd.h>

       long set_tid_address(int *tidptr);

DESCRIPTION top

       For each process, the kernel maintains two attributes (addresses) called
       set_child_tid and clear_child_tid.  These two attributes contain the value
       NULL by default.

       set_child_tid
              If a process is started using clone(2) with the CLONE_CHILD_SETTID
              flag, set_child_tid is set to the value passed in the ctid argument
              of that system call.

              When set_child_tid is set, the very first thing the new process does
              is writing its PID at this address.

       clear_child_tid
              If a process is started using clone(2) with the CLONE_CHILD_CLEARTID
              flag, clear_child_tid is set to the value passed in the ctid
              argument of that system call.

       The system call set_tid_address() sets the clear_child_tid value for the
       calling process to tidptr.

       When a process whose clear_child_tid is not NULL terminates, then, if the
       process is sharing memory with other processes or threads, then 0 is
       written at the address specified in clear_child_tid and the kernel performs
       the following operation:

           futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);

       The effect of this operation is to wake a single process that is performing
       a futex wait on the memory location.  Errors from the futex wake operation
       are ignored.

RETURN VALUE top

       set_tid_address() always returns the PID of the calling process.

ERRORS top

       set_tid_address() always succeeds.

VERSIONS top

       This call is present since Linux 2.5.48.  Details as given here are valid
       since Linux 2.5.49.

CONFORMING TO top

       This system call is Linux-specific.

SEE ALSO top

       clone(2), futex(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-19                  SET_TID_ADDRESS(2)


sgetmask(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SGETMASK(2)                  Linux Programmer's Manual                 SGETMASK(2)

NAME top

       sgetmask, ssetmask - manipulation of signal mask (obsolete)

SYNOPSIS top

       long sgetmask(void);

       long ssetmask(long newmask);

       Note: There are no glibc wrappers for these system calls; see NOTES.

DESCRIPTION top

       These system calls are obsolete.  Do not use them; use sigprocmask(2)
       instead.

       sgetmask() returns the signal mask of the calling process.

       ssetmask() sets the signal mask of the calling process to the value given
       in newmask.  The previous signal mask is returned.

       The signal masks dealt with by these two system calls are plain bit masks
       (unlike the sigset_t used by sigprocmask(2)); use sigmask(3) to create and
       inspect these masks.

RETURN VALUE top

       sgetmask() always successfully returns the signal mask.  ssetmask() always
       succeeds, and returns the previous signal mask.

ERRORS top

       These system calls always succeed.

CONFORMING TO top

       These system calls are Linux-specific.

NOTES top

       Glibc does not provide wrappers for these obsolete system calls; in the
       unlikely event that you want to call them, use syscall(2).

       These system calls are unaware of signal numbers greater than 31 (i.e.,
       real-time signals).

       It is not possible to block SIGSTOP or SIGKILL.

SEE ALSO top

       sigprocmask(2), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                         SGETMASK(2)


shells(5) - Linux manual page

NAME | DESCRIPTION | FILES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SHELLS(5)                    Linux Programmer's Manual                   SHELLS(5)

NAME top

       shells - pathnames of valid login shells

DESCRIPTION top

       /etc/shells is a text file which contains the full pathnames of valid login
       shells.  This file is consulted by chsh(1) and available to be queried by
       other programs.

       Be aware that there are programs which consult this file to find out if a
       user is a normal user.  E.g.: ftp daemons traditionally disallow access to
       users with shells not included in this file.

FILES top

       /etc/shells

EXAMPLE top

       /etc/shells may contain the following paths:

              /bin/sh
              /bin/csh

SEE ALSO top

       chsh(1), getusershell(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    1993-11-21                           SHELLS(5)


shmop(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SHMOP(2)                     Linux Programmer's Manual                    SHMOP(2)

NAME top

       shmat, shmdt - shared memory operations

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/shm.h>

       void *shmat(int shmid, const void *shmaddr, int shmflg);

       int shmdt(const void *shmaddr);

DESCRIPTION top

       shmat() attaches the shared memory segment identified by shmid to the
       address space of the calling process.  The attaching address is specified
       by shmaddr with one of the following criteria:

       If shmaddr is NULL, the system chooses a suitable (unused) address at which
       to attach the segment.

       If shmaddr isn't NULL and SHM_RND is specified in shmflg, the attach occurs
       at the address equal to shmaddr rounded down to the nearest multiple of
       SHMLBA.  Otherwise shmaddr must be a page-aligned address at which the
       attach occurs.

       If SHM_RDONLY is specified in shmflg, the segment is attached for reading
       and the process must have read permission for the segment.  Otherwise the
       segment is attached for read and write and the process must have read and
       write permission for the segment.  There is no notion of a write-only
       shared memory segment.

       The (Linux-specific) SHM_REMAP flag may be specified in shmflg to indicate
       that the mapping of the segment should replace any existing mapping in the
       range starting at shmaddr and continuing for the size of the segment.
       (Normally an EINVAL error would result if a mapping already exists in this
       address range.)  In this case, shmaddr must not be NULL.

       The brk(2) value of the calling process is not altered by the attach.  The
       segment will automatically be detached at process exit.  The same segment
       may be attached as a read and as a read-write one, and more than once, in
       the process's address space.

       A successful shmat() call updates the members of the shmid_ds structure
       (see shmctl(2)) associated with the shared memory segment as follows:

              shm_atime is set to the current time.

              shm_lpid is set to the process-ID of the calling process.

              shm_nattch is incremented by one.

       shmdt() detaches the shared memory segment located at the address specified
       by shmaddr from the address space of the calling process.  The to-be-
       detached segment must be currently attached with shmaddr equal to the value
       returned by the attaching shmat() call.

       On a successful shmdt() call the system updates the members of the shmid_ds
       structure associated with the shared memory segment as follows:

              shm_dtime is set to the current time.

              shm_lpid is set to the process-ID of the calling process.

              shm_nattch is decremented by one.  If it becomes 0 and the segment
              is marked for deletion, the segment is deleted.

       After a fork(2) the child inherits the attached shared memory segments.

       After an execve(2) all attached shared memory segments are detached from
       the process.

       Upon _exit(2) all attached shared memory segments are detached from the
       process.

RETURN VALUE top

       On success shmat() returns the address of the attached shared memory
       segment; on error (void *) -1 is returned, and errno is set to indicate the
       cause of the error.

       On success shmdt() returns 0; on error -1 is returned, and errno is set to
       indicate the cause of the error.

ERRORS top

       When shmat() fails, errno is set to one of the following:

       EACCES The calling process does not have the required permissions for the
              requested attach type, and does not have the CAP_IPC_OWNER
              capability.

       EINVAL Invalid shmid value, unaligned (i.e., not page-aligned and SHM_RND
              was not specified) or invalid shmaddr value, or can't attach segment
              at shmaddr, or SHM_REMAP was specified and shmaddr was NULL.

       ENOMEM Could not allocate memory for the descriptor or for the page tables.

       When shmdt() fails, errno is set as follows:

       EINVAL There is no shared memory segment attached at shmaddr; or, shmaddr
              is not aligned on a page boundary.

CONFORMING TO top

       SVr4, POSIX.1-2001.

       In SVID 3 (or perhaps earlier) the type of the shmaddr argument was changed
       from char * into const void *, and the returned type of shmat() from char *
       into void *.  (Linux libc4 and libc5 have the char * prototypes; glibc2 has
       void *.)

NOTES top

       Using shmat() with shmaddr equal to NULL is the preferred, portable way of
       attaching a shared memory segment.  Be aware that the shared memory segment
       attached in this way may be attached at different addresses in different
       processes.  Therefore, any pointers maintained within the shared memory
       must be made relative (typically to the starting address of the segment),
       rather than absolute.

       On Linux, it is possible to attach a shared memory segment even if it is
       already marked to be deleted.  However, POSIX.1-2001 does not specify this
       behavior and many other implementations do not support it.

       The following system parameter affects shmat():

       SHMLBA Segment low boundary address multiple.  Must be page aligned.  For
              the current implementation the SHMLBA value is PAGE_SIZE.

       The implementation places no intrinsic limit on the per-process maximum
       number of shared memory segments (SHMSEG).

SEE ALSO top

       brk(2), mmap(2), shmctl(2), shmget(2), capabilities(7), shm_overview(7),
       svipc(7)

COLOPHON top

       This page is part of release 3.45 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-06-03                            SHMOP(2)


shmctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SHMCTL(2)                    Linux Programmer's Manual                   SHMCTL(2)

NAME top

       shmctl - shared memory control

SYNOPSIS top

       #include <sys/ipc.h>
       #include <sys/shm.h>

       int shmctl(int shmid, int cmd, struct shmid_ds *buf);

DESCRIPTION top

       shmctl() performs the control operation specified by cmd on the shared
       memory segment whose identifier is given in shmid.

       The buf argument is a pointer to a shmid_ds structure, defined in
       <sys/shm.h> as follows:

           struct shmid_ds {
               struct ipc_perm shm_perm;    /* Ownership and permissions */
               size_t          shm_segsz;   /* Size of segment (bytes) */
               time_t          shm_atime;   /* Last attach time */
               time_t          shm_dtime;   /* Last detach time */
               time_t          shm_ctime;   /* Last change time */
               pid_t           shm_cpid;    /* PID of creator */
               pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
               shmatt_t        shm_nattch;  /* No. of current attaches */
               ...
           };

       The ipc_perm structure is defined as follows (the highlighted fields are
       settable using IPC_SET):

           struct ipc_perm {
               key_t          __key;    /* Key supplied to shmget(2) */
               uid_t          uid;      /* Effective UID of owner */
               gid_t          gid;      /* Effective GID of owner */
               uid_t          cuid;     /* Effective UID of creator */
               gid_t          cgid;     /* Effective GID of creator */
               unsigned short mode;     /* Permissions + SHM_DEST and
                                           SHM_LOCKED flags */
               unsigned short __seq;    /* Sequence number */
           };

       Valid values for cmd are:

       IPC_STAT  Copy information from the kernel data structure associated with
                 shmid into the shmid_ds structure pointed to by buf.  The caller
                 must have read permission on the shared memory segment.

       IPC_SET   Write the values of some members of the shmid_ds structure
                 pointed to by buf to the kernel data structure associated with
                 this shared memory segment, updating also its shm_ctime member.
                 The following fields can be changed: shm_perm.uid, shm_perm.gid,
                 and (the least significant 9 bits of) shm_perm.mode.  The
                 effective UID of the calling process must match the owner
                 (shm_perm.uid) or creator (shm_perm.cuid) of the shared memory
                 segment, or the caller must be privileged.

       IPC_RMID  Mark the segment to be destroyed.  The segment will only actually
                 be destroyed after the last process detaches it (i.e., when the
                 shm_nattch member of the associated structure shmid_ds is zero).
                 The caller must be the owner or creator, or be privileged.  If a
                 segment has been marked for destruction, then the (nonstandard)
                 SHM_DEST flag of the shm_perm.mode field in the associated data
                 structure retrieved by IPC_STAT will be set.

       The caller must ensure that a segment is eventually destroyed; otherwise
       its pages that were faulted in will remain in memory or swap.

       IPC_INFO (Linux-specific)
                 Returns information about system-wide shared memory limits and
                 parameters in the structure pointed to by buf.  This structure is
                 of type shminfo (thus, a cast is required), defined in
                 <sys/shm.h> if the _GNU_SOURCE feature test macro is defined:

                     struct  shminfo {
                         unsigned long shmmax; /* Maximum segment size */
                         unsigned long shmmin; /* Minimum segment size;
                                                  always 1 */
                         unsigned long shmmni; /* Maximum number of segments */
                         unsigned long shmseg; /* Maximum number of segments
                                                  that a process can attach;
                                                  unused within kernel */
                         unsigned long shmall; /* Maximum number of pages of
                                                  shared memory, system-wide */
                     };

                 The shmmni, shmmax, and shmall settings can be changed via /proc
                 files of the same name; see proc(5) for details.

       SHM_INFO (Linux-specific)
                 Returns a shm_info structure whose fields contain information
                 about system resources consumed by shared memory.  This structure
                 is defined in <sys/shm.h> if the _GNU_SOURCE feature test macro
                 is defined:

                     struct shm_info {
                         int           used_ids; /* # of currently existing
                                                    segments */
                         unsigned long shm_tot;  /* Total number of shared
                                                    memory pages */
                         unsigned long shm_rss;  /* # of resident shared
                                                    memory pages */
                         unsigned long shm_swp;  /* # of swapped shared
                                                    memory pages */
                         unsigned long swap_attempts;
                                                 /* Unused since Linux 2.4 */
                         unsigned long swap_successes;
                                                 /* Unused since Linux 2.4 */
                     };

       SHM_STAT (Linux-specific)
                 Returns a shmid_ds structure as for IPC_STAT.  However, the shmid
                 argument is not a segment identifier, but instead an index into
                 the kernel's internal array that maintains information about all
                 shared memory segments on the system.

       The caller can prevent or allow swapping of a shared memory segment with
       the following cmd values:

       SHM_LOCK (Linux-specific)
                 Prevent swapping of the shared memory segment.  The caller must
                 fault in any pages that are required to be present after locking
                 is enabled.  If a segment has been locked, then the (nonstandard)
                 SHM_LOCKED flag of the shm_perm.mode field in the associated data
                 structure retrieved by IPC_STAT will be set.

       SHM_UNLOCK (Linux-specific)
                 Unlock the segment, allowing it to be swapped out.

       In kernels before 2.6.10, only a privileged process could employ SHM_LOCK
       and SHM_UNLOCK.  Since kernel 2.6.10, an unprivileged process can employ
       these operations if its effective UID matches the owner or creator UID of
       the segment, and (for SHM_LOCK) the amount of memory to be locked falls
       within the RLIMIT_MEMLOCK resource limit (see setrlimit(2)).

RETURN VALUE top

       A successful IPC_INFO or SHM_INFO operation returns the index of the
       highest used entry in the kernel's internal array recording information
       about all shared memory segments.  (This information can be used with
       repeated SHM_STAT operations to obtain information about all shared memory
       segments on the system.)  A successful SHM_STAT operation returns the
       identifier of the shared memory segment whose index was given in shmid.
       Other operations return 0 on success.

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

ERRORS top

       EACCES IPC_STAT or SHM_STAT is requested and shm_perm.mode does not allow
              read access for shmid, and the calling process does not have the
              CAP_IPC_OWNER capability.

       EFAULT The argument cmd has value IPC_SET or IPC_STAT but the address
              pointed to by buf isn't accessible.

       EIDRM  shmid points to a removed identifier.

       EINVAL shmid is not a valid identifier, or cmd is not a valid command.  Or:
              for a SHM_STAT operation, the index value specified in shmid
              referred to an array slot that is currently unused.

       ENOMEM (In kernels since 2.6.9), SHM_LOCK was specified and the size of the
              to-be-locked segment would mean that the total bytes in locked
              shared memory segments would exceed the limit for the real user ID
              of the calling process.  This limit is defined by the RLIMIT_MEMLOCK
              soft resource limit (see setrlimit(2)).

       EOVERFLOW
              IPC_STAT is attempted, and the GID or UID value is too large to be
              stored in the structure pointed to by buf.

       EPERM  IPC_SET or IPC_RMID is attempted, and the effective user ID of the
              calling process is not that of the creator (found in shm_perm.cuid),
              or the owner (found in shm_perm.uid), and the process was not
              privileged (Linux: did not have the CAP_SYS_ADMIN capability).

              Or (in kernels before 2.6.9), SHM_LOCK or SHM_UNLOCK was specified,
              but the process was not privileged (Linux: did not have the
              CAP_IPC_LOCK capability).  (Since Linux 2.6.9, this error can also
              occur if the RLIMIT_MEMLOCK is 0 and the caller is not privileged.)

CONFORMING TO top

       SVr4, POSIX.1-2001.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       The IPC_INFO, SHM_STAT and SHM_INFO operations are used by the ipcs(1)
       program to provide information on allocated resources.  In the future these
       may modified or moved to a /proc file system interface.

       Linux permits a process to attach (shmat(2)) a shared memory segment that
       has already been marked for deletion using shmctl(IPC_RMID).  This feature
       is not available on other UNIX implementations; portable applications
       should avoid relying on it.

       Various fields in a struct shmid_ds were typed as short under Linux 2.2 and
       have become long under Linux 2.4.  To take advantage of this, a
       recompilation under glibc-2.1.91 or later should suffice.  (The kernel
       distinguishes old and new calls by an IPC_64 flag in cmd.)

SEE ALSO top

       mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7), svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                           SHMCTL(2)


shmget(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SHMGET(2)                    Linux Programmer's Manual                   SHMGET(2)

NAME top

       shmget - allocates a shared memory segment

SYNOPSIS top

       #include <sys/ipc.h>
       #include <sys/shm.h>

       int shmget(key_t key, size_t size, int shmflg);

DESCRIPTION top

       shmget() returns the identifier of the shared memory segment associated
       with the value of the argument key.  A new shared memory segment, with size
       equal to the value of size rounded up to a multiple of PAGE_SIZE, is
       created if key has the value IPC_PRIVATE or key isn't IPC_PRIVATE, no
       shared memory segment corresponding to key exists, and IPC_CREAT is
       specified in shmflg.

       If shmflg specifies both IPC_CREAT and IPC_EXCL and a shared memory segment
       already exists for key, then shmget() fails with errno set to EEXIST.
       (This is analogous to the effect of the combination O_CREAT | O_EXCL for
       open(2).)

       The value shmflg is composed of:

       IPC_CREAT   to create a new segment.  If this flag is not used, then
                   shmget() will find the segment associated with key and check to
                   see if the user has permission to access the segment.

       IPC_EXCL    used with IPC_CREAT to ensure failure if the segment already
                   exists.

       mode_flags  (least significant 9 bits) specifying the permissions granted
                   to the owner, group, and world.  These bits have the same
                   format, and the same meaning, as the mode argument of open(2).
                   Presently, the execute permissions are not used by the system.

       SHM_HUGETLB (since Linux 2.6)
                   Allocate the segment using "huge pages."  See the Linux kernel
                   source file Documentation/vm/hugetlbpage.txt for further
                   information.

       SHM_NORESERVE (since Linux 2.6.15)
                   This flag serves the same purpose as the mmap(2) MAP_NORESERVE
                   flag.  Do not reserve swap space for this segment.  When swap
                   space is reserved, one has the guarantee that it is possible to
                   modify the segment.  When swap space is not reserved one might
                   get SIGSEGV upon a write if no physical memory is available.
                   See also the discussion of the file
                   /proc/sys/vm/overcommit_memory in proc(5).

       When a new shared memory segment is created, its contents are initialized
       to zero values, and its associated data structure, shmid_ds (see
       shmctl(2)), is initialized as follows:

              shm_perm.cuid and shm_perm.uid are set to the effective user ID of
              the calling process.

              shm_perm.cgid and shm_perm.gid are set to the effective group ID of
              the calling process.

              The least significant 9 bits of shm_perm.mode are set to the least
              significant 9 bit of shmflg.

              shm_segsz is set to the value of size.

              shm_lpid, shm_nattch, shm_atime and shm_dtime are set to 0.

              shm_ctime is set to the current time.

       If the shared memory segment already exists, the permissions are verified,
       and a check is made to see if it is marked for destruction.

RETURN VALUE top

       A valid segment identifier, shmid, is returned on success, -1 on error.

ERRORS top

       On failure, errno is set to one of the following:

       EACCES The user does not have permission to access the shared memory
              segment, and does not have the CAP_IPC_OWNER capability.

       EEXIST IPC_CREAT | IPC_EXCL was specified and the segment exists.

       EINVAL A new segment was to be created and size < SHMMIN or size > SHMMAX,
              or no new segment was to be created, a segment with given key
              existed, but size is greater than the size of that segment.

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

       ENOENT No segment exists for the given key, and IPC_CREAT was not
              specified.

       ENOMEM No memory could be allocated for segment overhead.

       ENOSPC All possible shared memory IDs have been taken (SHMMNI), or
              allocating a segment of the requested size would cause the system to
              exceed the system-wide limit on shared memory (SHMALL).

       EPERM  The SHM_HUGETLB flag was specified, but the caller was not
              privileged (did not have the CAP_IPC_LOCK capability).

CONFORMING TO top

       SVr4, POSIX.1-2001.

       SHM_HUGETLB is a nonportable Linux extension.

NOTES top

       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux or
       by any version of POSIX.  However, some old implementations required the
       inclusion of these header files, and the SVID also documented their
       inclusion.  Applications intended to be portable to such old systems may
       need to include these header files.

       IPC_PRIVATE isn't a flag field but a key_t type.  If this special value is
       used for key, the system call ignores everything but the least significant
       9 bits of shmflg and creates a new shared memory segment (on success).

       The following limits on shared memory segment resources affect the shmget()
       call:

       SHMALL System wide maximum of shared memory pages (on Linux, this limit can
              be read and modified via /proc/sys/kernel/shmall).

       SHMMAX Maximum size in bytes for a shared memory segment: policy dependent
              (on Linux, this limit can be read and modified via
              /proc/sys/kernel/shmmax).

       SHMMIN Minimum size in bytes for a shared memory segment: implementation
              dependent (currently 1 byte, though PAGE_SIZE is the effective
              minimum size).

       SHMMNI System wide maximum number of shared memory segments: implementation
              dependent (currently 4096, was 128 before Linux 2.3.99; on Linux,
              this limit can be read and modified via /proc/sys/kernel/shmmni).

       The implementation has no specific limits for the per-process maximum
       number of shared memory segments (SHMSEG).

Linux Notes

       Until version 2.3.30 Linux would return EIDRM for a shmget() on a shared
       memory segment scheduled for deletion.

BUGS top

       The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more
       clearly show its function.

SEE ALSO top

       shmat(2), shmctl(2), shmdt(2), ftok(3), capabilities(7), shm_overview(7),
       svipc(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-31                           SHMGET(2)


shm_open(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SHM_OPEN(3)                  Linux Programmer's Manual                 SHM_OPEN(3)

NAME top

       shm_open, shm_unlink - create/open or unlink POSIX shared memory objects

SYNOPSIS top

       #include <sys/mman.h>
       #include <sys/stat.h>        /* For mode constants */
       #include <fcntl.h>           /* For O_* constants */

       int shm_open(const char *name, int oflag, mode_t mode);

       int shm_unlink(const char *name);

       Link with -lrt.

DESCRIPTION top

       shm_open() creates and opens a new, or opens an existing, POSIX shared
       memory object.  A POSIX shared memory object is in effect a handle which
       can be used by unrelated processes to mmap(2) the same region of shared
       memory.  The shm_unlink() function performs the converse operation,
       removing an object previously created by shm_open().

       The operation of shm_open() is analogous to that of open(2).  name
       specifies the shared memory object to be created or opened.  For portable
       use, a shared memory object should be identified by a name of the form
       /somename; that is, a null-terminated string of up to NAME_MAX (i.e., 255)
       characters consisting of an initial slash, followed by one or more
       characters, none of which are slashes.

       oflag is a bit mask created by ORing together exactly one of O_RDONLY or
       O_RDWR and any of the other flags listed here:

       O_RDONLY   Open the object for read access.  A shared memory object opened
                  in this way can only be mmap(2)ed for read (PROT_READ) access.

       O_RDWR     Open the object for read-write access.

       O_CREAT    Create the shared memory object if it does not exist.  The user
                  and group ownership of the object are taken from the
                  corresponding effective IDs of the calling process, and the
                  object's permission bits are set according to the low-order 9
                  bits of mode, except that those bits set in the process file
                  mode creation mask (see umask(2)) are cleared for the new
                  object.  A set of macro constants which can be used to define
                  mode is listed in open(2).  (Symbolic definitions of these
                  constants can be obtained by including <sys/stat.h>.)

                  A new shared memory object initially has zero length--the size
                  of the object can be set using ftruncate(2).  The newly
                  allocated bytes of a shared memory object are automatically
                  initialized to 0.

       O_EXCL     If O_CREAT was also specified, and a shared memory object with
                  the given name already exists, return an error.  The check for
                  the existence of the object, and its creation if it does not
                  exist, are performed atomically.

       O_TRUNC    If the shared memory object already exists, truncate it to zero
                  bytes.

       Definitions of these flag values can be obtained by including <fcntl.h>.

       On successful completion shm_open() returns a new file descriptor referring
       to the shared memory object.  This file descriptor is guaranteed to be the
       lowest-numbered file descriptor not previously opened within the process.
       The FD_CLOEXEC flag (see fcntl(2)) is set for the file descriptor.

       The file descriptor is normally used in subsequent calls to ftruncate(2)
       (for a newly created object) and mmap(2).  After a call to mmap(2) the file
       descriptor may be closed without affecting the memory mapping.

       The operation of shm_unlink() is analogous to unlink(2): it removes a
       shared memory object name, and, once all processes have unmapped the
       object, de-allocates and destroys the contents of the associated memory
       region.  After a successful shm_unlink(), attempts to shm_open() an object
       with the same name will fail (unless O_CREAT was specified, in which case a
       new, distinct object is created).

RETURN VALUE top

       On success, shm_open() returns a nonnegative file descriptor.  On failure,
       shm_open() returns -1.  shm_unlink() returns 0 on success, or -1 on error.

ERRORS top

       On failure, errno is set to indicate the cause of the error.  Values which
       may appear in errno include the following:

       EACCES Permission to shm_unlink() the shared memory object was denied.

       EACCES Permission was denied to shm_open() name in the specified mode, or
              O_TRUNC was specified and the caller does not have write permission
              on the object.

       EEXIST Both O_CREAT and O_EXCL were specified to shm_open() and the shared
              memory object specified by name already exists.

       EINVAL The name argument to shm_open() was invalid.

       EMFILE The process already has the maximum number of files open.

       ENAMETOOLONG
              The length of name exceeds PATH_MAX.

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

       ENOENT An attempt was made to shm_open() a name that did not exist, and
              O_CREAT was not specified.

       ENOENT An attempt was to made to shm_unlink() a name that does not exist.

VERSIONS top

       These functions are provided in glibc 2.2 and later.

CONFORMING TO top

       POSIX.1-2001.

       POSIX.1-2001 says that the group ownership of a newly created shared memory
       object is set to either the calling process's effective group ID or "a
       system default group ID".

NOTES top

       POSIX leaves the behavior of the combination of O_RDONLY and O_TRUNC
       unspecified.  On Linux, this will successfully truncate an existing shared
       memory object--this may not be so on other UNIX systems.

       The POSIX shared memory object implementation on Linux 2.4 makes use of a
       dedicated file system, which is normally mounted under /dev/shm.

SEE ALSO top

       close(2), fchmod(2), fchown(2), fcntl(2), fstat(2), ftruncate(2), mmap(2),
       open(2), umask(2), shm_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-25                         SHM_OPEN(3)


shm_overview(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SHM_OVERVIEW(7)              Linux Programmer's Manual             SHM_OVERVIEW(7)

NAME top

       shm_overview - overview of POSIX shared memory

DESCRIPTION top

       The POSIX shared memory API allows processes to communicate information by
       sharing a region of memory.

       The interfaces employed in the API are:

       shm_open(3)    Create and open a new object, or open an existing object.
                      This is analogous to open(2).  The call returns a file
                      descriptor for use by the other interfaces listed below.

       ftruncate(2)   Set the size of the shared memory object.  (A newly created
                      shared memory object has a length of zero.)

       mmap(2)        Map the shared memory object into the virtual address space
                      of the calling process.

       munmap(2)      Unmap the shared memory object from the virtual address
                      space of the calling process.

       shm_unlink(3)  Remove a shared memory object name.

       close(2)       Close the file descriptor allocated by shm_open(3) when it
                      is no longer needed.

       fstat(2)       Obtain a stat structure that describes the shared memory
                      object.  Among the information returned by this call are the
                      object's size (st_size), permissions (st_mode), owner
                      (st_uid), and group (st_gid).

       fchown(2)      To change the ownership of a shared memory object.

       fchmod(2)      To change the permissions of a shared memory object.

Versions

       POSIX shared memory is supported since Linux 2.4 and glibc 2.2.

Persistence

       POSIX shared memory objects have kernel persistence: a shared memory object
       will exist until the system is shut down, or until all processes have
       unmapped the object and it has been deleted with shm_unlink(3)

Linking

       Programs using the POSIX shared memory API must be compiled with cc -lrt to
       link against the real-time library, librt.

Accessing shared memory objects via the file system

       On Linux, shared memory objects are created in a (tmpfs) virtual file
       system, normally mounted under /dev/shm.  Since kernel 2.6.19, Linux
       supports the use of access control lists (ACLs) to control the permissions
       of objects in the virtual file system.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       Typically, processes must synchronize their access to a shared memory
       object, using, for example, POSIX semaphores.

       System V shared memory (shmget(2), shmop(2), etc.) is an older shared
       memory API.  POSIX shared memory provides a simpler, and better designed
       interface; on the other hand POSIX shared memory is somewhat less widely
       available (especially on older systems) than System V shared memory.

SEE ALSO top

       fchmod(2), fchown(2), fstat(2), ftruncate(2), mmap(2), mprotect(2),
       munmap(2), shmget(2), shmop(2), shm_open(3), shm_unlink(3), sem_overview(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-10                     SHM_OVERVIEW(7)


shutdown(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SHUTDOWN(2)                  Linux Programmer's Manual                 SHUTDOWN(2)

NAME top

       shutdown - shut down part of a full-duplex connection

SYNOPSIS top

       #include <sys/socket.h>

       int shutdown(int sockfd, int how);

DESCRIPTION top

       The shutdown() call causes all or part of a full-duplex connection on the
       socket associated with sockfd to be shut down.  If how is SHUT_RD, further
       receptions will be disallowed.  If how is SHUT_WR, further transmissions
       will be disallowed.  If how is SHUT_RDWR, further receptions and
       transmissions will be disallowed.

RETURN VALUE top

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

ERRORS top

       EBADF  sockfd is not a valid descriptor.

       EINVAL An invalid value was specified in how (but see BUGS).

       ENOTCONN
              The specified socket is not connected.

       ENOTSOCK
              sockfd is a file, not a socket.

CONFORMING TO top

       POSIX.1-2001, 4.4BSD (the shutdown() function call first appeared in
       4.2BSD).

NOTES top

       The constants SHUT_RD, SHUT_WR, SHUT_RDWR have the value 0, 1, 2,
       respectively, and are defined in <sys/socket.h> since glibc-2.1.91.

BUGS top

       As currently implemented, checks for the validity of how are done in
       domain-specific code, and not all domains perform these checks.  Most
       notably, UNIX domain sockets simply ignore invalid values; this may change
       in the future.

SEE ALSO top

       connect(2), socket(2), socket(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-09-06                         SHUTDOWN(2)


sigsetops(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGSETOPS(3)                 Linux Programmer's Manual                SIGSETOPS(3)

NAME top

       sigemptyset,  sigfillset,  sigaddset, sigdelset, sigismember - POSIX signal
       set operations.

SYNOPSIS top

       #include <signal.h>

       int sigemptyset(sigset_t *set);

       int sigfillset(sigset_t *set);

       int sigaddset(sigset_t *set, int signum);

       int sigdelset(sigset_t *set, int signum);

       int sigismember(const sigset_t *set, int signum);

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

       sigemptyset(), sigfillset(), sigaddset(), sigdelset(), sigismember():
           _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       These functions allow the manipulation of POSIX signal sets.

       sigemptyset() initializes the signal set given by set to empty, with all
       signals excluded from the set.

       sigfillset() initializes set to full, including all signals.

       sigaddset() and sigdelset() add and delete respectively signal signum from
       set.

       sigismember() tests whether signum is a member of set.

       Objects of type sigset_t must be initialized by a call to either
       sigemptyset() or sigfillset() before being passed to the functions
       sigaddset(), sigdelset() and sigismember() or the additional glibc
       functions described below (sigisemptyset(), sigandset(), and sigorset()).
       The results are undefined if this is not done.

RETURN VALUE top

       sigemptyset(), sigfillset(), sigaddset(), and sigdelset() return 0 on
       success and -1 on error.

       sigismember() returns 1 if signum is a member of set, 0 if signum is not a
       member, and -1 on error.

ERRORS top

       EINVAL sig is not a valid signal.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

Glibc Notes

       If the _GNU_SOURCE feature test macro is defined, then <signal.h> exposes
       three other functions for manipulating signal sets.

       int sigisemptyset(sigset_t *set);
              returns 1 if set contains no signals, and 0 otherwise.

       int sigorset(sigset_t *dest, sigset_t *left, sigset_t *right);
              places the union of the sets left and right in dest.

       int sigandset(sigset_t *dest, sigset_t *left, sigset_t *right);
              places the intersection of the sets left and right in dest.

       sigorset() and sigandset() return 0 on success, and -1 on failure.

       These functions are nonstandard (a few other systems provide similar
       functions) and their use should be avoided in portable applications.

SEE ALSO          top
       sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2)

COLOPHON          top
       This page is part of release 3.45 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-01                        SIGSETOPS(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


sigaltstack(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SIGALTSTACK(2)               Linux Programmer's Manual              SIGALTSTACK(2)

NAME top

       sigaltstack - set and/or get signal stack context

SYNOPSIS top

       #include <signal.h>

       int sigaltstack(const stack_t *ss, stack_t *oss);

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

       sigaltstack():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       sigaltstack() allows a process to define a new alternate signal stack
       and/or retrieve the state of an existing alternate signal stack.  An
       alternate signal stack is used during the execution of a signal handler if
       the establishment of that handler (see sigaction(2)) requested it.

       The normal sequence of events for using an alternate signal stack is the
       following:

       1. Allocate an area of memory to be used for the alternate signal stack.

       2. Use sigaltstack() to inform the system of the existence and location of
          the alternate signal stack.

       3. When establishing a signal handler using sigaction(2), inform the system
          that the signal handler should be executed on the alternate signal stack
          by specifying the SA_ONSTACK flag.

       The ss argument is used to specify a new alternate signal stack, while the
       oss argument is used to retrieve information about the currently
       established signal stack.  If we are interested in performing just one of
       these tasks then the other argument can be specified as NULL.  Each of
       these arguments is a structure of the following type:

           typedef struct {
               void  *ss_sp;     /* Base address of stack */
               int    ss_flags;  /* Flags */
               size_t ss_size;   /* Number of bytes in stack */
           } stack_t;

       To establish a new alternate signal stack, ss.ss_flags is set to zero, and
       ss.ss_sp and ss.ss_size specify the starting address and size of the stack.
       The constant SIGSTKSZ is defined to be large enough to cover the usual size
       requirements for an alternate signal stack, and the constant MINSIGSTKSZ
       defines the minimum size required to execute a signal handler.

       When a signal handler is invoked on the alternate stack, the kernel
       automatically aligns the address given in ss.ss_sp to a suitable address
       boundary for the underlying hardware architecture.

       To disable an existing stack, specify ss.ss_flags as SS_DISABLE.  In this
       case, the remaining fields in ss are ignored.

       If oss is not NULL, then it is used to return information about the
       alternate signal stack which was in effect prior to the call to
       sigaltstack().  The oss.ss_sp and oss.ss_size fields return the starting
       address and size of that stack.  The oss.ss_flags may return either of the
       following values:

       SS_ONSTACK
              The process is currently executing on the alternate signal stack.
              (Note that it is not possible to change the alternate signal stack
              if the process is currently executing on it.)

       SS_DISABLE
              The alternate signal stack is currently disabled.

RETURN VALUE top

       sigaltstack() returns 0 on success, or -1 on failure with errno set to
       indicate the error.

ERRORS top

       EFAULT Either ss or oss is not NULL and points to an area outside of the
              process's address space.

       EINVAL ss is not NULL and the ss_flags field contains a nonzero value other
              than SS_DISABLE.

       ENOMEM The specified size of the new alternate signal stack (ss.ss_size)
              was less than MINSTKSZ.

       EPERM  An attempt was made to change the alternate signal stack while it
              was active (i.e., the process was already executing on the current
              alternate signal stack).

CONFORMING TO top

       SUSv2, SVr4, POSIX.1-2001.

NOTES top

       The most common usage of an alternate signal stack is to handle the SIGSEGV
       signal that is generated if the space available for the normal process
       stack is exhausted: in this case, a signal handler for SIGSEGV cannot be
       invoked on the process stack; if we wish to handle it, we must use an
       alternate signal stack.

       Establishing an alternate signal stack is useful if a process expects that
       it may exhaust its standard stack.  This may occur, for example, because
       the stack grows so large that it encounters the upwardly growing heap, or
       it reaches a limit established by a call to setrlimit(RLIMIT_STACK, &rlim).
       If the standard stack is exhausted, the kernel sends the process a SIGSEGV
       signal.  In these circumstances the only way to catch this signal is on an
       alternate signal stack.

       On most hardware architectures supported by Linux, stacks grow downward.
       sigaltstack() automatically takes account of the direction of stack growth.

       Functions called from a signal handler executing on an alternate signal
       stack will also use the alternate signal stack.  (This also applies to any
       handlers invoked for other signals while the process is executing on the
       alternate signal stack.)  Unlike the standard stack, the system does not
       automatically extend the alternate signal stack.  Exceeding the allocated
       size of the alternate signal stack will lead to unpredictable results.

       A successful call to execve(2) removes any existing alternate signal stack.
       A child process created via fork(2) inherits a copy of its parent's
       alternate signal stack settings.

       sigaltstack() supersedes the older sigstack() call.  For backward
       compatibility, glibc also provides sigstack().  All new applications should
       be written using sigaltstack().

History

       4.2BSD had a sigstack() system call.  It used a slightly different struct,
       and had the major disadvantage that the caller had to know the direction of
       stack growth.

EXAMPLE top

       The following code segment demonstrates the use of sigaltstack():

           stack_t ss;

           ss.ss_sp = malloc(SIGSTKSZ);
           if (ss.ss_sp == NULL)
               /* Handle error */;
           ss.ss_size = SIGSTKSZ;
           ss.ss_flags = 0;
           if (sigaltstack(&ss, NULL) == -1)
               /* Handle error */;

SEE ALSO top

       execve(2), setrlimit(2), sigaction(2), siglongjmp(3), sigsetjmp(3),
       signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-26                      SIGALTSTACK(2)


sigvec(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGVEC(3)                    Linux Programmer's Manual                   SIGVEC(3)

NAME top

       sigvec, sigblock, sigsetmask, siggetmask, sigmask - BSD signal API

SYNOPSIS top

       #include <signal.h>

       int sigvec(int sig, struct sigvec *vec, struct sigvec *ovec);

       int sigmask(int signum);

       int sigblock(int mask);

       int sigsetmask(int mask);

       int siggetmask(void);

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

       All functions shown above: _BSD_SOURCE

DESCRIPTION top

       These functions are provided in glibc as a compatibility interface for
       programs that make use of the historical BSD signal API.  This API is
       obsolete: new applications should use the POSIX signal API (sigaction(2),
       sigprocmask(2), etc.).

       The sigvec() function sets and/or gets the disposition of the signal sig
       (like the POSIX sigaction(2)).  If vec is not NULL, it points to a sigvec
       structure that defines the new disposition for sig.  If ovec is not NULL,
       it points to a sigvec structure that is used to return the previous
       disposition of sig.  To obtain the current disposition of sig without
       changing it, specify NULL for vec, and a non-NULL pointer for ovec.

       The dispositions for SIGKILL and SIGSTOP cannot be changed.

       The sigvec structure has the following form:

           struct sigvec {
               void (*sv_handler)(int); /* Signal disposition */
               int    sv_mask;          /* Signals to be blocked in handler */
               int    sv_flags;         /* Flags */
           };

       The sv_handler field specifies the disposition of the signal, and is
       either: the address of a signal handler function; SIG_DFL, meaning the
       default disposition applies for the signal; or SIG_IGN, meaning that the
       signal is ignored.

       If sv_handler specifies the address of a signal handler, then sv_mask
       specifies a mask of signals that are to be blocked while the handler is
       executing.  In addition, the signal for which the handler is invoked is
       also blocked.  Attempts to block SIGKILL or SIGSTOP are silently ignored.

       If sv_handler specifies the address of a signal handler, then the sv_flags
       field specifies flags controlling what happens when the handler is called.
       This field may contain zero or more of the following flags:

       SV_INTERRUPT
              If the signal handler interrupts a blocking system call, then upon
              return from the handler the system call will not be restarted:
              instead it will fail with the error EINTR.  If this flag is not
              specified, then system calls are restarted by default.

       SV_RESETHAND
              Reset the disposition of the signal to the default before calling
              the signal handler.  If this flag is not specified, then the handler
              remains established until explicitly removed by a later call to
              sigvec() or until the process performs an execve(2).

       SV_ONSTACK
              Handle the signal on the alternate signal stack (historically
              established under BSD using the obsolete sigstack() function; the
              POSIX replacement is sigaltstack(2)).

       The sigmask() function constructs and returns a "signal mask" for signum.
       For example, we can initialize the vec.sv_mask field given to sigvec()
       using code such as the following:

           vec.sv_mask = sigmask(SIGQUIT) | sigpause(SIGABRT);
                       /* Block SIGQUIT and SIGABRT during
                          handler execution */

       The sigblock() function adds the signals in mask to the process's signal
       mask (like POSIX sigprocmask(SIG_BLOCK)), and returns the process's
       previous signal mask.  Attempts to block SIGKILL or SIGSTOP are silently
       ignored.

       The sigsetmask() function sets the process's signal mask to the value given
       in mask (like POSIX sigprocmask(SIG_SETMASK)), and returns the process's
       previous signal mask.

       The siggetmask() function returns the process's current signal mask.  This
       call is equivalent to sigblock(0).

RETURN VALUE top

       The sigvec() function returns 0 on success; on error, it returns -1 and
       sets errno to indicate the error.

       The sigblock() and sigsetmask() functions return the previous signal mask.

       The sigmask() function returns the signal mask for signum.

ERRORS top

       See the ERRORS under sigaction(2) and sigprocmask(2).

CONFORMING TO top

       All of these functions were in 4.3BSD, except siggetmask(), whose origin is
       unclear.  These functions are obsolete: do not use them in new programs.

NOTES top

       On 4.3BSD, the signal() function provided reliable semantics (as when
       calling sigvec() with vec.sv_mask equal to 0).  On System V, signal()
       provides unreliable semantics.  POSIX.1-2001 leaves these aspects of
       signal() unspecified.  See signal(2) for further details.

       In order to wait for a signal, BSD and System V both provided a function
       named sigpause(3), but this function has a different argument on the two
       systems.  See sigpause(3) for details.

SEE ALSO top

       kill(2), pause(2), sigaction(2), signal(2), sigprocmask(2), raise(3),
       sigpause(3), sigset(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-09-06                           SIGVEC(3)


sigevent(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SIGEVENT(7)                  Linux Programmer's Manual                 SIGEVENT(7)

NAME top

       sigevent - structure for notification from asynchronous routines

SYNOPSIS top

       union sigval {          /* Data passed with notification */
           int     sival_int;         /* Integer value */
           void   *sival_ptr;         /* Pointer value */
       };

       struct sigevent {
           int          sigev_notify; /* Notification method */
           int          sigev_signo;  /* Notification signal */
           union sigval sigev_value;  /* Data passed with
                                         notification */
           void       (*sigev_notify_function) (union sigval);
                            /* Function used for thread
                               notification (SIGEV_THREAD) */
           void        *sigev_notify_attributes;
                            /* Attributes for notification thread
                               (SIGEV_THREAD) */
           pid_t        sigev_notify_thread_id;
                            /* ID of thread to signal (SIGEV_THREAD_ID) */
       };

DESCRIPTION top

       The sigevent structure is used by various APIs to describe the way a
       process is to be notified about an event (e.g., completion of an
       asynchronous request, expiration of a timer, or the arrival of a message).

       The definition shown in the SYNOPSIS is approximate: some of the fields in
       the sigevent structure may be defined as part of a union.  Programs should
       only employ those fields relevant to the value specified in sigev_notify.

       The sigev_notify field specifies how notification is to be performed.  This
       field can have one of the following values:

       SIGEV_NONE
               A "null" notification: don't do anything when the event occurs.

       SIGEV_SIGNAL
               Notify the process by sending the signal specified in sigev_signo.

               If the signal is caught with a signal handler that was registered
               using the sigaction(2) SA_SIGINFO flag, then the following fields
               are set in the siginfo_t structure that is passed as the second
               argument of the handler:

               si_code   This field is set to a value that depends on the API
                         delivering the notification.

               si_signo  This field is set to the signal number (i.e., the same
                         value as in sigev_signo).

               si_value  This field is set to the value specified in sigev_value.

               Depending on the API, other fields may also be set in the siginfo_t
               structure.

               The same information is also available if the signal is accepted
               using sigwaitinfo(2).

       SIGEV_THREAD
               Notify the process by invoking sigev_notify_function "as if" it
               were the start function of a new thread.  (Among the implementation
               possibilities here are that each timer notification could result in
               the creation of a new thread, or that a single thread is created to
               receive all notifications.)  The function is invoked with
               sigev_value as its sole argument.  If sigev_notify_attributes is
               not NULL, it should point to a pthread_attr_t structure that
               defines attributes for the new thread (see pthread_attr_init(3)).

       SIGEV_THREAD_ID (Linux-specific)
               Currently used only by POSIX timers; see timer_create(2).

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       timer_create(2), aio_fsync(3), aio_read(3), aio_write(3), getaddrinfo_a(3),
       lio_listio(3), mq_notify(3), aio(7), pthreads(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-09                         SIGEVENT(7)


sigset(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SIGSET(3)                    Linux Programmer's Manual                   SIGSET(3)

NAME top

       sigset, sighold, sigrelse, sigignore - System V signal API

SYNOPSIS top

       #include <signal.h>

       typedef void (*sighandler_t)(int);

       sighandler_t sigset(int sig, sighandler_t disp);

       int sighold(int sig);

       int sigrelse(int sig);

       int sigignore(int sig);

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

       sigset(), sighold(), sigrelse(), sigignore():
           _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       These functions are provided in glibc as a compatibility interface for
       programs that make use of the historical System V signal API.  This API is
       obsolete: new applications should use the POSIX signal API (sigaction(2),
       sigprocmask(2), etc.)

       The sigset() function modifies the disposition of the signal sig.  The disp
       argument can be the address of a signal handler function, or one of the
       following constants:

       SIG_DFL
              Reset the disposition of sig to the default.

       SIG_IGN
              Ignore sig.

       SIG_HOLD
              Add sig to the process's signal mask, but leave the disposition of
              sig unchanged.

       If disp specifies the address of a signal handler, then sig is added to the
       process's signal mask during execution of the handler.

       If disp was specified as a value other than SIG_HOLD, then sig is removed
       from the process's signal mask.

       The dispositions for SIGKILL and SIGSTOP cannot be changed.

       The sighold() function adds sig to the calling process's signal mask.

       The sigrelse() function removes sig from the calling process's signal mask.

       The sigignore() function sets the disposition of sig to SIG_IGN.

RETURN VALUE top

       On success, sigset() returns SIG_HOLD if sig was blocked before the call,
       or the signal's previous disposition if it was not blocked before the call.
       On error, sigset() returns -1, with errno set to indicate the error.  (But
       see BUGS below.)

       The sighold(), sigrelse(), and sigignore() functions return 0 on success;
       on error, these functions return -1 and set errno to indicate the error.

ERRORS top

       For sigset() see the ERRORS under sigaction(2) and sigprocmask(2).

       For sighold() and sigrelse() see the ERRORS under sigprocmask(2).

       For sigignore(), see the errors under sigaction(2).

CONFORMING TO top

       SVr4, POSIX.1-2001.  These functions are obsolete: do not use them in new
       programs.  POSIX.1-2008 marks sighold(), sigignore(), sigpause(),
       sigrelse(), and sigset() as obsolete, recommending the use of sigaction(2),
       sigprocmask(2), pthread_sigmask(3), and sigsuspend(2) instead.

NOTES top

       These functions appeared in glibc version 2.1.

       The sighandler_t type is a GNU extension; it is only used on this page to
       make the sigset() prototype more easily readable.

       The sigset() function provides reliable signal handling semantics (as when
       calling sigaction(2) with sa_mask equal to 0).

       On System V, the signal() function provides unreliable semantics (as when
       calling sigaction(2) with sa_mask equal to SA_RESETHAND | SA_NODEFER).  On
       BSD, signal() provides reliable semantics.  POSIX.1-2001 leaves these
       aspects of signal() unspecified.  See signal(2) for further details.

       In order to wait for a signal, BSD and System V both provided a function
       named sigpause(3), but this function has a different argument on the two
       systems.  See sigpause(3) for details.

BUGS top

       In versions of glibc before 2.2, sigset() did not unblock sig if disp was
       specified as a value other than SIG_HOLD.

       In versions of glibc before 2.5, sigset() does not correctly return the
       previous disposition of the signal in two cases.  First, if disp is
       specified as SIG_HOLD, then a successful sigset() always returns SIG_HOLD.
       Instead, it should return the previous disposition of the signal (unless
       the signal was blocked, in which case SIG_HOLD should be returned).
       Second, if the signal is currently blocked, then the return value of a
       successful sigset() should be SIG_HOLD.  Instead, the previous disposition
       of the signal is returned.  These problems have been fixed since glibc 2.5.

SEE ALSO top

       kill(2), pause(2), sigaction(2), signal(2), sigprocmask(2), raise(3),
       sigpause(3), sigvec(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                           SIGSET(3)


siginterrupt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SIGINTERRUPT(3)              Linux Programmer's Manual             SIGINTERRUPT(3)

NAME top

       siginterrupt - allow signals to interrupt system calls

SYNOPSIS top

       #include <signal.h>

       int siginterrupt(int sig, int flag);

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

       siginterrupt():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       The siginterrupt() function changes the restart behavior when a system call
       is interrupted by the signal sig.  If the flag argument is false (0), then
       system calls will be restarted if interrupted by the specified signal sig.
       This is the default behavior in Linux.

       If the flag argument is true (1) and no data has been transferred, then a
       system call interrupted by the signal sig will return -1 and errno will be
       set to EINTR.

       If the flag argument is true (1) and data transfer has started, then the
       system call will be interrupted and will return the actual amount of data
       transferred.

RETURN VALUE top

       The siginterrupt() function returns 0 on success, or -1 if the signal
       number sig is invalid.

ERRORS top

       EINVAL The specified signal number is invalid.

CONFORMING TO top

       4.3BSD, POSIX.1-2001.  POSIX.1-2008 marks siginterrupt() as obsolete,
       recommending the use of sigaction(2) with the SA_RESTART flag instead.

SEE ALSO top

       signal(2)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2011-09-09                     SIGINTERRUPT(3)


signal(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGNAL(2)                    Linux Programmer's Manual                   SIGNAL(2)

NAME top

       signal - ANSI C signal handling

SYNOPSIS top

       #include <signal.h>

       typedef void (*sighandler_t)(int);

       sighandler_t signal(int signum, sighandler_t handler);

DESCRIPTION top

       The behavior of signal() varies across UNIX versions, and has also varied
       historically across different versions of Linux.  Avoid its use: use
       sigaction(2) instead.  See Portability below.

       signal() sets the disposition of the signal signum to handler, which is
       either SIG_IGN, SIG_DFL, or the address of a programmer-defined function (a
       "signal handler").

       If the signal signum is delivered to the process, then one of the following
       happens:

       *  If the disposition is set to SIG_IGN, then the signal is ignored.

       *  If the disposition is set to SIG_DFL, then the default action associated
          with the signal (see signal(7)) occurs.

       *  If the disposition is set to a function, then first either the
          disposition is reset to SIG_DFL, or the signal is blocked (see
          Portability below), and then handler is called with argument signum.  If
          invocation of the handler caused the signal to be blocked, then the
          signal is unblocked upon return from the handler.

       The signals SIGKILL and SIGSTOP cannot be caught or ignored.

RETURN VALUE top

       signal() returns the previous value of the signal handler, or SIG_ERR on
       error.

ERRORS top

       EINVAL signum is invalid.

CONFORMING TO top

       C89, C99, POSIX.1-2001.

NOTES top

       The effects of signal() in a multithreaded process are unspecified.

       According to POSIX, the behavior of a process is undefined after it ignores
       a SIGFPE, SIGILL, or SIGSEGV signal that was not generated by kill(2) or
       raise(3).  Integer division by zero has undefined result.  On some
       architectures it will generate a SIGFPE signal.  (Also dividing the most
       negative integer by -1 may generate SIGFPE.)  Ignoring this signal might
       lead to an endless loop.

       See sigaction(2) for details on what happens when SIGCHLD is set to
       SIG_IGN.

       See signal(7) for a list of the async-signal-safe functions that can be
       safely called from inside a signal handler.

       The use of sighandler_t is a GNU extension, exposed if _GNU_SOURCE is
       defined; glibc also defines (the BSD-derived) sig_t if _BSD_SOURCE is
       defined.  Without use of such a type, the declaration of signal() is the
       somewhat harder to read:

           void ( *signal(int signum, void (*handler)(int)) ) (int);

Portability

       The only portable use of signal() is to set a signal's disposition to
       SIG_DFL or SIG_IGN.  The semantics when using signal() to establish a
       signal handler vary across systems (and POSIX.1 explicitly permits this
       variation); do not use it for this purpose.

       POSIX.1 solved the portability mess by specifying sigaction(2), which
       provides explicit control of the semantics when a signal handler is
       invoked; use that interface instead of signal().

       In the original UNIX systems, when a handler that was established using
       signal() was invoked by the delivery of a signal, the disposition of the
       signal would be reset to SIG_DFL, and the system did not block delivery of
       further instances of the signal.  System V also provides these semantics
       for signal().  This was bad because the signal might be delivered again
       before the handler had a chance to reestablish itself.  Furthermore, rapid
       deliveries of the same signal could result in recursive invocations of the
       handler.

       BSD improved on this situation by changing the semantics of signal handling
       (but, unfortunately, silently changed the semantics when establishing a
       handler with signal()).  On BSD, when a signal handler is invoked, the
       signal disposition is not reset, and further instances of the signal are
       blocked from being delivered while the handler is executing.

       The situation on Linux is as follows:

       * The kernel's signal() system call provides System V semantics.

       * By default, in glibc 2 and later, the signal() wrapper function does not
         invoke the kernel system call.  Instead, it calls sigaction(2) using
         flags that supply BSD semantics.  This default behavior is provided as
         long as the _BSD_SOURCE feature test macro is defined.  By default,
         _BSD_SOURCE is defined; it is also implicitly defined if one defines
         _GNU_SOURCE, and can of course be explicitly defined.

         On glibc 2 and later, if the _BSD_SOURCE feature test macro is not
         defined, then signal() provides System V semantics.  (The default
         implicit definition of _BSD_SOURCE is not provided if one invokes gcc(1)
         in one of its standard modes (-std=xxx or -ansi) or defines various other
         feature test macros such as _POSIX_SOURCE, _XOPEN_SOURCE, or
         _SVID_SOURCE; see feature_test_macros(7).)

       * The signal() function in Linux libc4 and libc5 provide System V
         semantics.  If one on a libc5 system includes <bsd/signal.h> instead of
         <signal.h>, then signal() provides BSD semantics.

SEE ALSO top

       kill(1), alarm(2), kill(2), killpg(2), pause(2), sigaction(2), signalfd(2),
       sigpending(2), sigprocmask(2), sigsuspend(2), bsd_signal(3), raise(3),
       siginterrupt(3), sigqueue(3), sigsetops(3), sigvec(3), sysv_signal(3),
       signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-05                           SIGNAL(2)


signal(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SIGNAL(7)                    Linux Programmer's Manual                   SIGNAL(7)

NAME top

       signal - overview of signals

DESCRIPTION top

       Linux supports both POSIX reliable signals (hereinafter "standard signals")
       and POSIX real-time signals.

Signal Dispositions

       Each signal has a current disposition, which determines how the process
       behaves when it is delivered the signal.

       The entries in the "Action" column of the tables below specify the default
       disposition for each signal, as follows:

       Term   Default action is to terminate the process.

       Ign    Default action is to ignore the signal.

       Core   Default action is to terminate the process and dump core (see
              core(5)).

       Stop   Default action is to stop the process.

       Cont   Default action is to continue the process if it is currently
              stopped.

       A process can change the disposition of a signal using sigaction(2) or
       signal(2).  (The latter is less portable when establishing a signal
       handler; see signal(2) for details.)  Using these system calls, a process
       can elect one of the following behaviors to occur on delivery of the
       signal: perform the default action; ignore the signal; or catch the signal
       with a signal handler, a programmer-defined function that is automatically
       invoked when the signal is delivered.  (By default, the signal handler is
       invoked on the normal process stack.  It is possible to arrange that the
       signal handler uses an alternate stack; see sigaltstack(2) for a discussion
       of how to do this and when it might be useful.)

       The signal disposition is a per-process attribute: in a multithreaded
       application, the disposition of a particular signal is the same for all
       threads.

       A child created via fork(2) inherits a copy of its parent's signal
       dispositions.  During an execve(2), the dispositions of handled signals are
       reset to the default; the dispositions of ignored signals are left
       unchanged.

Sending a Signal

       The following system calls and library functions allow the caller to send a
       signal:

       raise(3)        Sends a signal to the calling thread.

       kill(2)         Sends a signal to a specified process, to all members of a
                       specified process group, or to all processes on the system.

       killpg(2)       Sends a signal to all of the members of a specified process
                       group.

       pthread_kill(3) Sends a signal to a specified POSIX thread in the same
                       process as the caller.

       tgkill(2)       Sends a signal to a specified thread within a specific
                       process.  (This is the system call used to implement
                       pthread_kill(3).)

       sigqueue(3)     Sends a real-time signal with accompanying data to a
                       specified process.

Waiting for a Signal to be Caught

       The following system calls suspend execution of the calling process or
       thread until a signal is caught (or an unhandled signal terminates the
       process):

       pause(2)        Suspends execution until any signal is caught.

       sigsuspend(2)   Temporarily changes the signal mask (see below) and
                       suspends execution until one of the unmasked signals is
                       caught.

Synchronously Accepting a Signal

       Rather than asynchronously catching a signal via a signal handler, it is
       possible to synchronously accept the signal, that is, to block execution
       until the signal is delivered, at which point the kernel returns
       information about the signal to the caller.  There are two general ways to
       do this:

       * sigwaitinfo(2), sigtimedwait(2), and sigwait(3) suspend execution until
         one of the signals in a specified set is delivered.  Each of these calls
         returns information about the delivered signal.

       * signalfd(2) returns a file descriptor that can be used to read
         information about signals that are delivered to the caller.  Each read(2)
         from this file descriptor blocks until one of the signals in the set
         specified in the signalfd(2) call is delivered to the caller.  The buffer
         returned by read(2) contains a structure describing the signal.

Signal Mask and Pending Signals

       A signal may be blocked, which means that it will not be delivered until it
       is later unblocked.  Between the time when it is generated and when it is
       delivered a signal is said to be pending.

       Each thread in a process has an independent signal mask, which indicates
       the set of signals that the thread is currently blocking.  A thread can
       manipulate its signal mask using pthread_sigmask(3).  In a traditional
       single-threaded application, sigprocmask(2) can be used to manipulate the
       signal mask.

       A child created via fork(2) inherits a copy of its parent's signal mask;
       the signal mask is preserved across execve(2).

       A signal may be generated (and thus pending) for a process as a whole
       (e.g., when sent using kill(2)) or for a specific thread (e.g., certain
       signals, such as SIGSEGV and SIGFPE, generated as a consequence of
       executing a specific machine-language instruction are thread directed, as
       are signals targeted at a specific thread using pthread_kill(3)).  A
       process-directed signal may be delivered to any one of the threads that
       does not currently have the signal blocked.  If more than one of the
       threads has the signal unblocked, then the kernel chooses an arbitrary
       thread to which to deliver the signal.

       A thread can obtain the set of signals that it currently has pending using
       sigpending(2).  This set will consist of the union of the set of pending
       process-directed signals and the set of signals pending for the calling
       thread.

       A child created via fork(2) initially has an empty pending signal set; the
       pending signal set is preserved across an execve(2).

Standard Signals

       Linux supports the standard signals listed below.  Several signal numbers
       are architecture-dependent, as indicated in the "Value" column.  (Where
       three values are given, the first one is usually valid for alpha and sparc,
       the middle one for x86, arm, and most other architectures, and the last one
       for mips.  (Values for parisc are not shown; see the Linux kernel source
       for signal numbering on that architecture.)  A - denotes that a signal is
       absent on the corresponding architecture.)

       First the signals described in the original POSIX.1-1990 standard.

       Signal     Value     Action   Comment
       ----------------------------------------------------------------------
       SIGHUP        1       Term    Hangup detected on controlling terminal
                                     or death of controlling process
       SIGINT        2       Term    Interrupt from keyboard
       SIGQUIT       3       Core    Quit from keyboard
       SIGILL        4       Core    Illegal Instruction
       SIGABRT       6       Core    Abort signal from abort(3)
       SIGFPE        8       Core    Floating point exception
       SIGKILL       9       Term    Kill signal
       SIGSEGV      11       Core    Invalid memory reference
       SIGPIPE      13       Term    Broken pipe: write to pipe with no
                                     readers
       SIGALRM      14       Term    Timer signal from alarm(2)
       SIGTERM      15       Term    Termination signal
       SIGUSR1   30,10,16    Term    User-defined signal 1
       SIGUSR2   31,12,17    Term    User-defined signal 2
       SIGCHLD   20,17,18    Ign     Child stopped or terminated
       SIGCONT   19,18,25    Cont    Continue if stopped
       SIGSTOP   17,19,23    Stop    Stop process
       SIGTSTP   18,20,24    Stop    Stop typed at tty
       SIGTTIN   21,21,26    Stop    tty input for background process
       SIGTTOU   22,22,27    Stop    tty output for background process

       The signals SIGKILL and SIGSTOP cannot be caught, blocked, or ignored.

       Next the signals not in the POSIX.1-1990 standard but described in SUSv2
       and POSIX.1-2001.

       Signal       Value     Action   Comment
       --------------------------------------------------------------------
       SIGBUS      10,7,10     Core    Bus error (bad memory access)
       SIGPOLL                 Term    Pollable event (Sys V).
                                       Synonym for SIGIO
       SIGPROF     27,27,29    Term    Profiling timer expired
       SIGSYS      12,31,12    Core    Bad argument to routine (SVr4)
       SIGTRAP        5        Core    Trace/breakpoint trap
       SIGURG      16,23,21    Ign     Urgent condition on socket (4.2BSD)
       SIGVTALRM   26,26,28    Term    Virtual alarm clock (4.2BSD)
       SIGXCPU     24,24,30    Core    CPU time limit exceeded (4.2BSD)
       SIGXFSZ     25,25,31    Core    File size limit exceeded (4.2BSD)

       Up to and including Linux 2.2, the default behavior for SIGSYS, SIGXCPU,
       SIGXFSZ, and (on architectures other than SPARC and MIPS) SIGBUS was to
       terminate the process (without a core dump).  (On some other UNIX systems
       the default action for SIGXCPU and SIGXFSZ is to terminate the process
       without a core dump.)  Linux 2.4 conforms to the POSIX.1-2001 requirements
       for these signals, terminating the process with a core dump.

       Next various other signals.

       Signal       Value     Action   Comment
       --------------------------------------------------------------------
       SIGIOT         6        Core    IOT trap. A synonym for SIGABRT
       SIGEMT       7,-,7      Term
       SIGSTKFLT    -,16,-     Term    Stack fault on coprocessor (unused)
       SIGIO       23,29,22    Term    I/O now possible (4.2BSD)
       SIGCLD       -,-,18     Ign     A synonym for SIGCHLD
       SIGPWR      29,30,19    Term    Power failure (System V)

       SIGINFO      29,-,-             A synonym for SIGPWR
       SIGLOST      -,-,-      Term    File lock lost (unused)
       SIGWINCH    28,28,20    Ign     Window resize signal (4.3BSD, Sun)
       SIGUNUSED    -,31,-     Core    Synonymous with SIGSYS

       (Signal 29 is SIGINFO / SIGPWR on an alpha but SIGLOST on a sparc.)

       SIGEMT is not specified in POSIX.1-2001, but nevertheless appears on most
       other UNIX systems, where its default action is typically to terminate the
       process with a core dump.

       SIGPWR (which is not specified in POSIX.1-2001) is typically ignored by
       default on those other UNIX systems where it appears.

       SIGIO (which is not specified in POSIX.1-2001) is ignored by default on
       several other UNIX systems.

       Where defined, SIGUNUSED is synonymous with SIGSYS on most architectures.

Real-time Signals

       Linux supports real-time signals as originally defined in the POSIX.1b
       real-time extensions (and now included in POSIX.1-2001).  The range of
       supported real-time signals is defined by the macros SIGRTMIN and SIGRTMAX.
       POSIX.1-2001 requires that an implementation support at least
       _POSIX_RTSIG_MAX (8) real-time signals.

       The Linux kernel supports a range of 32 different real-time signals,
       numbered 33 to 64.  However, the glibc POSIX threads implementation
       internally uses two (for NPTL) or three (for LinuxThreads) real-time
       signals (see pthreads(7)), and adjusts the value of SIGRTMIN suitably (to
       34 or 35).  Because the range of available real-time signals varies
       according to the glibc threading implementation (and this variation can
       occur at run time according to the available kernel and glibc), and indeed
       the range of real-time signals varies across UNIX systems, programs should
       never refer to real-time signals using hard-coded numbers, but instead
       should always refer to real-time signals using the notation SIGRTMIN+n, and
       include suitable (run-time) checks that SIGRTMIN+n does not exceed
       SIGRTMAX.

       Unlike standard signals, real-time signals have no predefined meanings: the
       entire set of real-time signals can be used for application-defined
       purposes.

       The default action for an unhandled real-time signal is to terminate the
       receiving process.

       Real-time signals are distinguished by the following:

       1.  Multiple instances of real-time signals can be queued.  By contrast, if
           multiple instances of a standard signal are delivered while that signal
           is currently blocked, then only one instance is queued.

       2.  If the signal is sent using sigqueue(3), an accompanying value (either
           an integer or a pointer) can be sent with the signal.  If the receiving
           process establishes a handler for this signal using the SA_SIGINFO flag
           to sigaction(2) then it can obtain this data via the si_value field of
           the siginfo_t structure passed as the second argument to the handler.
           Furthermore, the si_pid and si_uid fields of this structure can be used
           to obtain the PID and real user ID of the process sending the signal.

       3.  Real-time signals are delivered in a guaranteed order.  Multiple real-
           time signals of the same type are delivered in the order they were
           sent.  If different real-time signals are sent to a process, they are
           delivered starting with the lowest-numbered signal.  (I.e., low-
           numbered signals have highest priority.)  By contrast, if multiple
           standard signals are pending for a process, the order in which they are
           delivered is unspecified.

       If both standard and real-time signals are pending for a process, POSIX
       leaves it unspecified which is delivered first.  Linux, like many other
       implementations, gives priority to standard signals in this case.

       According to POSIX, an implementation should permit at least
       _POSIX_SIGQUEUE_MAX (32) real-time signals to be queued to a process.
       However, Linux does things differently.  In kernels up to and including
       2.6.7, Linux imposes a system-wide limit on the number of queued real-time
       signals for all processes.  This limit can be viewed and (with privilege)
       changed via the /proc/sys/kernel/rtsig-max file.  A related file,
       /proc/sys/kernel/rtsig-nr, can be used to find out how many real-time
       signals are currently queued.  In Linux 2.6.8, these /proc interfaces were
       replaced by the RLIMIT_SIGPENDING resource limit, which specifies a per-
       user limit for queued signals; see setrlimit(2) for further details.

Async-signal-safe functions

       A signal handler function must be very careful, since processing elsewhere
       may be interrupted at some arbitrary point in the execution of the program.
       POSIX has the concept of "safe function".  If a signal interrupts the
       execution of an unsafe function, and handler calls an unsafe function, then
       the behavior of the program is undefined.

       POSIX.1-2004 (also known as POSIX.1-2001 Technical Corrigendum 2) requires
       an implementation to guarantee that the following functions can be safely
       called inside a signal handler:

           _Exit()
           _exit()
           abort()
           accept()
           access()
           aio_error()
           aio_return()
           aio_suspend()
           alarm()
           bind()
           cfgetispeed()
           cfgetospeed()
           cfsetispeed()
           cfsetospeed()
           chdir()
           chmod()
           chown()
           clock_gettime()
           close()
           connect()
           creat()
           dup()
           dup2()
           execle()
           execve()
           fchmod()
           fchown()
           fcntl()
           fdatasync()
           fork()
           fpathconf()
           fstat()
           fsync()
           ftruncate()
           getegid()
           geteuid()
           getgid()
           getgroups()
           getpeername()
           getpgrp()
           getpid()
           getppid()
           getsockname()
           getsockopt()
           getuid()
           kill()
           link()
           listen()
           lseek()
           lstat()
           mkdir()
           mkfifo()
           open()
           pathconf()
           pause()
           pipe()
           poll()
           posix_trace_event()
           pselect()
           raise()
           read()
           readlink()
           recv()
           recvfrom()
           recvmsg()
           rename()
           rmdir()
           select()
           sem_post()
           send()
           sendmsg()
           sendto()
           setgid()
           setpgid()
           setsid()
           setsockopt()
           setuid()
           shutdown()
           sigaction()
           sigaddset()
           sigdelset()
           sigemptyset()
           sigfillset()
           sigismember()
           signal()
           sigpause()
           sigpending()
           sigprocmask()
           sigqueue()
           sigset()
           sigsuspend()
           sleep()
           sockatmark()
           socket()
           socketpair()
           stat()
           symlink()
           sysconf()
           tcdrain()
           tcflow()
           tcflush()
           tcgetattr()
           tcgetpgrp()
           tcsendbreak()
           tcsetattr()
           tcsetpgrp()
           time()
           timer_getoverrun()
           timer_gettime()
           timer_settime()
           times()
           umask()
           uname()
           unlink()
           utime()
           wait()
           waitpid()
           write()

       POSIX.1-2008 removes fpathconf(), pathconf(), and sysconf() from the above
       list, and adds the following functions:

           execl()
           execv()
           faccessat()
           fchmodat()
           fchownat()
           fexecve()
           fstatat()
           futimens()
           linkat()
           mkdirat()
           mkfifoat()
           mknod()
           mknodat()
           openat()
           readlinkat()
           renameat()
           symlinkat()
           unlinkat()
           utimensat()
           utimes()

Interruption of System Calls and Library Functions by Signal Handlers

       If a signal handler is invoked while a system call or library function call
       is blocked, then either:

       * the call is automatically restarted after the signal handler returns; or

       * the call fails with the error EINTR.

       Which of these two behaviors occurs depends on the interface and whether or
       not the signal handler was established using the SA_RESTART flag (see
       sigaction(2)).  The details vary across UNIX systems; below, the details
       for Linux.

       If a blocked call to one of the following interfaces is interrupted by a
       signal handler, then the call will be automatically restarted after the
       signal handler returns if the SA_RESTART flag was used; otherwise the call
       will fail with the error EINTR:

           * read(2), readv(2), write(2), writev(2), and ioctl(2) calls on "slow"
             devices.  A "slow" device is one where the I/O call may block for an
             indefinite time, for example, a terminal, pipe, or socket.  (A disk
             is not a slow device according to this definition.)  If an I/O call
             on a slow device has already transferred some data by the time it is
             interrupted by a signal handler, then the call will return a success
             status (normally, the number of bytes transferred).

           * open(2), if it can block (e.g., when opening a FIFO; see fifo(7)).

           * wait(2), wait3(2), wait4(2), waitid(2), and waitpid(2).

           * Socket interfaces: accept(2), connect(2), recv(2), recvfrom(2),
             recvmsg(2), send(2), sendto(2), and sendmsg(2), unless a timeout has
             been set on the socket (see below).

           * File locking interfaces: flock(2) and fcntl(2) F_SETLKW.

           * POSIX message queue interfaces: mq_receive(3), mq_timedreceive(3),
             mq_send(3), and mq_timedsend(3).

           * futex(2) FUTEX_WAIT (since Linux 2.6.22; beforehand, always failed
             with EINTR).

           * POSIX semaphore interfaces: sem_wait(3) and sem_timedwait(3) (since
             Linux 2.6.22; beforehand, always failed with EINTR).

       The following interfaces are never restarted after being interrupted by a
       signal handler, regardless of the use of SA_RESTART; they always fail with
       the error EINTR when interrupted by a signal handler:

           * Socket interfaces, when a timeout has been set on the socket using
             setsockopt(2): accept(2), recv(2), recvfrom(2), and recvmsg(2), if a
             receive timeout (SO_RCVTIMEO) has been set; connect(2), send(2),
             sendto(2), and sendmsg(2), if a send timeout (SO_SNDTIMEO) has been
             set.

           * Interfaces used to wait for signals: pause(2), sigsuspend(2),
             sigtimedwait(2), and sigwaitinfo(2).

           * File descriptor multiplexing interfaces: epoll_wait(2),
             epoll_pwait(2), poll(2), ppoll(2), select(2), and pselect(2).

           * System V IPC interfaces: msgrcv(2), msgsnd(2), semop(2), and
             semtimedop(2).

           * Sleep interfaces: clock_nanosleep(2), nanosleep(2), and usleep(3).

           * read(2) from an inotify(7) file descriptor.

           * io_getevents(2).

       The sleep(3) function is also never restarted if interrupted by a handler,
       but gives a success return: the number of seconds remaining to sleep.

Interruption of System Calls and Library Functions by Stop Signals

       On Linux, even in the absence of signal handlers, certain blocking
       interfaces can fail with the error EINTR after the process is stopped by
       one of the stop signals and then resumed via SIGCONT.  This behavior is not
       sanctioned by POSIX.1, and doesn't occur on other systems.

       The Linux interfaces that display this behavior are:

           * Socket interfaces, when a timeout has been set on the socket using
             setsockopt(2): accept(2), recv(2), recvfrom(2), and recvmsg(2), if a
             receive timeout (SO_RCVTIMEO) has been set; connect(2), send(2),
             sendto(2), and sendmsg(2), if a send timeout (SO_SNDTIMEO) has been
             set.

           * epoll_wait(2), epoll_pwait(2).

           * semop(2), semtimedop(2).

           * sigtimedwait(2), sigwaitinfo(2).

           * read(2) from an inotify(7) file descriptor.

           * Linux 2.6.21 and earlier: futex(2) FUTEX_WAIT, sem_timedwait(3),
             sem_wait(3).

           * Linux 2.6.8 and earlier: msgrcv(2), msgsnd(2).

           * Linux 2.4 and earlier: nanosleep(2).

CONFORMING TO top

       POSIX.1, except as noted.

SEE ALSO top

       kill(1), getrlimit(2), kill(2), killpg(2), rt_sigqueueinfo(2),
       setitimer(2), setrlimit(2), sgetmask(2), sigaction(2), sigaltstack(2),
       signal(2), signalfd(2), sigpending(2), sigprocmask(2), sigsuspend(2),
       sigwaitinfo(2), abort(3), bsd_signal(3), longjmp(3), raise(3),
       pthread_sigqueue(3), sigqueue(3), sigset(3), sigsetops(3), sigvec(3),
       sigwait(3), strsignal(3), sysv_signal(3), core(5), proc(5), pthreads(7),
       sigevent(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-01                           SIGNAL(7)


signalfd(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SIGNALFD(2)                  Linux Programmer's Manual                 SIGNALFD(2)

NAME top

       signalfd - create a file descriptor for accepting signals

SYNOPSIS top

       #include <sys/signalfd.h>

       int signalfd(int fd, const sigset_t *mask, int flags);

DESCRIPTION top

       signalfd() creates a file descriptor that can be used to accept signals
       targeted at the caller.  This provides an alternative to the use of a
       signal handler or sigwaitinfo(2), and has the advantage that the file
       descriptor may be monitored by select(2), poll(2), and epoll(7).

       The mask argument specifies the set of signals that the caller wishes to
       accept via the file descriptor.  This argument is a signal set whose
       contents can be initialized using the macros described in sigsetops(3).
       Normally, the set of signals to be received via the file descriptor should
       be blocked using sigprocmask(2), to prevent the signals being handled
       according to their default dispositions.  It is not possible to receive
       SIGKILL or SIGSTOP signals via a signalfd file descriptor; these signals
       are silently ignored if specified in mask.

       If the fd argument is -1, then the call creates a new file descriptor and
       associates the signal set specified in mask with that descriptor.  If fd is
       not -1, then it must specify a valid existing signalfd file descriptor, and
       mask is used to replace the signal set associated with that descriptor.

       Starting with Linux 2.6.27, the following values may be bitwise ORed in
       flags to change the behaviour of signalfd():

       SFD_NONBLOCK  Set the O_NONBLOCK file status flag on the new open file
                     description.  Using this flag saves extra calls to fcntl(2)
                     to achieve the same result.

       SFD_CLOEXEC   Set the close-on-exec (FD_CLOEXEC) flag on the new file
                     descriptor.  See the description of the O_CLOEXEC flag in
                     open(2) for reasons why this may be useful.

       In Linux up to version 2.6.26, the flags argument is unused, and must be
       specified as zero.

       signalfd() returns a file descriptor that supports the following
       operations:

       read(2)
              If one or more of the signals specified in mask is pending for the
              process, then the buffer supplied to read(2) is used to return one
              or more signalfd_siginfo structures (see below) that describe the
              signals.  The read(2) returns information for as many signals as are
              pending and will fit in the supplied buffer.  The buffer must be at
              least sizeof(struct signalfd_siginfo) bytes.  The return value of
              the read(2) is the total number of bytes read.

              As a consequence of the read(2), the signals are consumed, so that
              they are no longer pending for the process (i.e., will not be caught
              by signal handlers, and cannot be accepted using sigwaitinfo(2)).

              If none of the signals in mask is pending for the process, then the
              read(2) either blocks until one of the signals in mask is generated
              for the process, or fails with the error EAGAIN if the file
              descriptor has been made nonblocking.

       poll(2), select(2) (and similar)
              The file descriptor is readable (the select(2) readfds argument; the
              poll(2) POLLIN flag) if one or more of the signals in mask is
              pending for the process.

              The signalfd file descriptor also supports the other file-descriptor
              multiplexing APIs: pselect(2), ppoll(2), and epoll(7).

       close(2)
              When the file descriptor is no longer required it should be closed.
              When all file descriptors associated with the same signalfd object
              have been closed, the resources for object are freed by the kernel.

The signalfd_siginfo structure

       The format of the signalfd_siginfo structure(s) returned by read(2)s from a
       signalfd file descriptor is as follows:

           struct signalfd_siginfo {
               uint32_t ssi_signo;   /* Signal number */
               int32_t  ssi_errno;   /* Error number (unused) */
               int32_t  ssi_code;    /* Signal code */
               uint32_t ssi_pid;     /* PID of sender */
               uint32_t ssi_uid;     /* Real UID of sender */
               int32_t  ssi_fd;      /* File descriptor (SIGIO) */
               uint32_t ssi_tid;     /* Kernel timer ID (POSIX timers)
               uint32_t ssi_band;    /* Band event (SIGIO) */
               uint32_t ssi_overrun; /* POSIX timer overrun count */
               uint32_t ssi_trapno;  /* Trap number that caused signal */
               int32_t  ssi_status;  /* Exit status or signal (SIGCHLD) */
               int32_t  ssi_int;     /* Integer sent by sigqueue(3) */
               uint64_t ssi_ptr;     /* Pointer sent by sigqueue(3) */
               uint64_t ssi_utime;   /* User CPU time consumed (SIGCHLD) */
               uint64_t ssi_stime;   /* System CPU time consumed (SIGCHLD) */
               uint64_t ssi_addr;    /* Address that generated signal
                                        (for hardware-generated signals) */
               uint8_t  pad[X];      /* Pad size to 128 bytes (allow for
                                         additional fields in the future) */
           };

       Each of the fields in this structure is analogous to the similarly named
       field in the siginfo_t structure.  The siginfo_t structure is described in
       sigaction(2).  Not all fields in the returned signalfd_siginfo structure
       will be valid for a specific signal; the set of valid fields can be
       determined from the value returned in the ssi_code field.  This field is
       the analog of the siginfo_t si_code field; see sigaction(2) for details.

fork(2) semantics

       After a fork(2), the child inherits a copy of the signalfd file descriptor.
       A read(2) from the file descriptor in the child will return information
       about signals queued to the child.

execve(2) semantics

       Just like any other file descriptor, a signalfd file descriptor remains
       open across an execve(2), unless it has been marked for close-on-exec (see
       fcntl(2)).  Any signals that were available for reading before the
       execve(2) remain available to the newly loaded program.  (This is analogous
       to traditional signal semantics, where a blocked signal that is pending
       remains pending across an execve(2).)

Thread semantics

       The semantics of signalfd file descriptors in a multithreaded program
       mirror the standard semantics for signals.  In other words, when a thread
       reads from a signalfd file descriptor, it will read the signals that are
       directed to the thread itself and the signals that are directed to the
       process (i.e., the entire thread group).  (A thread will not be able to
       read signals that are directed to other threads in the process.)

RETURN VALUE top

       On success, signalfd() returns a signalfd file descriptor; this is either a
       new file descriptor (if fd was -1), or fd if fd was a valid signalfd file
       descriptor.  On error, -1 is returned and errno is set to indicate the
       error.

ERRORS top

       EBADF  The fd file descriptor is not a valid file descriptor.

       EINVAL fd is not a valid signalfd file descriptor.

       EINVAL flags is invalid; or, in Linux 2.6.26 or earlier, flags is nonzero.

       EMFILE The per-process limit of open file descriptors has been reached.

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

       ENODEV Could not mount (internal) anonymous inode device.

       ENOMEM There was insufficient memory to create a new signalfd file
              descriptor.

VERSIONS top

       signalfd() is available on Linux since kernel 2.6.22.  Working support is
       provided in glibc since version 2.8.  The signalfd4() system call (see
       NOTES) is available on Linux since kernel 2.6.27.

CONFORMING TO top

       signalfd() and signalfd4() are Linux-specific.

NOTES top

       The underlying Linux system call requires an additional argument, size_t
       sizemask, which specifies the size of the mask argument.  The glibc
       signalfd() wrapper function does not include this argument, since it
       provides the required value for the underlying system call.

       A process can create multiple signalfd file descriptors.  This makes it
       possible to accept different signals on different file descriptors.  (This
       may be useful if monitoring the file descriptors using select(2), poll(2),
       or epoll(7): the arrival of different signals will make different
       descriptors ready.)  If a signal appears in the mask of more than one of
       the file descriptors, then occurrences of that signal can be read (once)
       from any one of the descriptors.

Underlying Linux system calls

       There are two underlying Linux system calls: signalfd() and the more recent
       signalfd4().  The former system call does not implement a flags argument.
       The latter system call implements the flags values described above.
       Starting with glibc 2.9, the signalfd() wrapper function will use
       signalfd4() where it is available.

BUGS top

       In kernels before 2.6.25, the ssi_ptr and ssi_int fields are not filled in
       with the data accompanying a signal sent by sigqueue(3).

EXAMPLE top

       The program below accepts the signals SIGINT and SIGQUIT via a signalfd
       file descriptor.  The program terminates after accepting a SIGQUIT signal.
       The following shell session demonstrates the use of the program:

           $ ./signalfd_demo
           ^C                   # Control-C generates SIGINT
           Got SIGINT
           ^C
           Got SIGINT
           ^\                    # Control-\ generates SIGQUIT
           Got SIGQUIT
           $

Program source

       #include <sys/signalfd.h>
       #include <signal.h>
       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>

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

       int
       main(int argc, char *argv[])
       {
           sigset_t mask;
           int sfd;
           struct signalfd_siginfo fdsi;
           ssize_t s;

           sigemptyset(&mask);
           sigaddset(&mask, SIGINT);
           sigaddset(&mask, SIGQUIT);

           /* Block signals so that they aren't handled
              according to their default dispositions */

           if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)
               handle_error("sigprocmask");

           sfd = signalfd(-1, &mask, 0);
           if (sfd == -1)
               handle_error("signalfd");

           for (;;) {
               s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));
               if (s != sizeof(struct signalfd_siginfo))
                   handle_error("read");

               if (fdsi.ssi_signo == SIGINT) {
                   printf("Got SIGINT\n");
               } else if (fdsi.ssi_signo == SIGQUIT) {
                   printf("Got SIGQUIT\n");
                   exit(EXIT_SUCCESS);
               } else {
                   printf("Read unexpected signal\n");
               }
           }
       }

SEE ALSO top

       eventfd(2), poll(2), read(2), select(2), sigaction(2), sigprocmask(2),
       sigwaitinfo(2), timerfd_create(2), sigsetops(3), sigwait(3), epoll(7),
       signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-01-13                         SIGNALFD(2)


signbit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SIGNBIT(3)                   Linux Programmer's Manual                  SIGNBIT(3)

NAME top

       signbit - test sign of a real floating-point number

SYNOPSIS top

       #include <math.h>

       int signbit(x);

       Link with -lm.

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

       signbit():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       signbit() is a generic macro which can work on all real floating-point
       types.  It returns a nonzero value if the value of x has its sign bit set.

       This is not the same as x < 0.0, because IEEE 754 floating point allows
       zero to be signed.  The comparison -0.0 < 0.0 is false, but signbit(-0.0)
       will return a nonzero value.

       NaNs and infinities have a sign bit.

RETURN VALUE top

       The signbit() macro returns nonzero if the sign of x is negative; otherwise
       it returns zero.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  This function is defined in IEC 559 (and the appendix
       with recommended functions in IEEE 754/IEEE 854).

SEE ALSO top

       copysign(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                          SIGNBIT(3)


significand(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SIGNIFICAND(3)               Linux Programmer's Manual              SIGNIFICAND(3)

NAME top

       significand,  significandf,  significandl  - get mantissa of floating-point
       number

SYNOPSIS top

       #include <math.h>

       double significand(double x);
       float significandf(float x);
       long double significandl(long double x);

       Link with -lm.

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

       significand(), significandf(), significandl():
           _SVID_SOURCE || _BSD_SOURCE

DESCRIPTION top

       The significand() function returns the mantissa of x scaled to the range
       [1,2).  It is equivalent to

           scalb(x, (double) -ilogb(x))

       This function exists mainly for use in certain standardized tests for IEEE
       754 conformance.

CONFORMING TO top

       These functions are nonstandard; the double version is available on a
       number of other systems.

SEE ALSO top

       ilogb(3), scalb(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-02-04                      SIGNIFICAND(3)


sigpause(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGPAUSE(3)                  Linux Programmer's Manual                 SIGPAUSE(3)

NAME top

       sigpause - atomically release blocked signals and wait for interrupt

SYNOPSIS top

       #include <signal.h>

       int sigpause(int sigmask);  /* BSD */

       int sigpause(int sig);      /* System V / UNIX 95 */

DESCRIPTION top

       Don't use this function.  Use sigsuspend(2) instead.

       The function sigpause() is designed to wait for some signal.  It changes
       the process's signal mask (set of blocked signals), and then waits for a
       signal to arrive.  Upon arrival of a signal, the original signal mask is
       restored.

RETURN VALUE top

       If sigpause() returns, it was interrupted by a signal and the return value
       is -1 with errno set to EINTR.

CONFORMING TO top

       The System V version of sigpause() is standardized in POSIX.1-2001.

NOTES top

History

       The classical BSD version of this function appeared in 4.2BSD.  It sets the
       process's signal mask to sigmask.  UNIX 95 standardized the incompatible
       System V version of this function, which removes only the specified signal
       sig from the process's signal mask.  The unfortunate situation with two
       incompatible functions with the same name was solved by the sigsuspend(2)
       function, that takes a sigset_t * argument (instead of an int).

Linux Notes

       On Linux, this routine is a system call only on the Sparc (sparc64)
       architecture.

       Libc4 and libc5 only know about the BSD version.

       Glibc uses the BSD version if the _BSD_SOURCE feature test macro is defined
       and none of _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _GNU_SOURCE, or
       _SVID_SOURCE is defined.  Otherwise, the System V version is used.

SEE ALSO          top
       kill(2), sigaction(2), sigprocmask(2), sigsuspend(2), sigblock(3),
       sigvec(3), feature_test_macros(7)

COLOPHON          top
       This page is part of release 3.45 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                               2010-09-12                         SIGPAUSE(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


sigqueue(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SIGQUEUE(3)                  Linux Programmer's Manual                 SIGQUEUE(3)

NAME top

       sigqueue - queue a signal and data to a process

SYNOPSIS top

       #include <signal.h>

       int sigqueue(pid_t pid, int sig, const union sigval value);

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

       sigqueue(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       sigqueue() sends the signal specified in sig to the process whose PID is
       given in pid.  The permissions required to send a signal are the same as
       for kill(2).  As with kill(2), the null signal (0) can be used to check if
       a process with a given PID exists.

       The value argument is used to specify an accompanying item of data (either
       an integer or a pointer value) to be sent with the signal, and has the
       following type:

           union sigval {
               int   sival_int;
               void *sival_ptr;
           };

       If the receiving process has installed a handler for this signal using the
       SA_SIGINFO flag to sigaction(2), then it can obtain this data via the
       si_value field of the siginfo_t structure passed as the second argument to
       the handler.  Furthermore, the si_code field of that structure will be set
       to SI_QUEUE.

RETURN VALUE top

       On success, sigqueue() returns 0, indicating that the signal was
       successfully queued to the receiving process.  Otherwise -1 is returned and
       errno is set to indicate the error.

ERRORS top

       EAGAIN The limit of signals which may be queued has been reached.  (See
              signal(7) for further information.)

       EINVAL sig was invalid.

       EPERM  The process does not have permission to send the signal to the
              receiving process.  For the required permissions, see kill(2).

       ESRCH  No process has a PID matching pid.

VERSIONS top

       This system call first appeared in Linux 2.2.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       If this function results in the sending of a signal to the process that
       invoked it, and that signal was not blocked by the calling thread, and no
       other threads were willing to handle this signal (either by having it
       unblocked, or by waiting for it using sigwait(3)), then at least some
       signal must be delivered to this thread before this function returns.

       On Linux, this function is implemented using the rt_sigqueueinfo(2) system
       call.  The system call differs in its third argument, which is the
       siginfo_t structure that will be supplied to the receiving process's signal
       handler or returned by the receiving process's sigtimedwait(2) call.
       Inside the glibc sigqueue() wrapper, this argument, uinfo, is initialized
       as follows:

           uinfo.si_signo = sig;      /* argument supplied to sigqueue() */
           uinfo.si_code = SI_QUEUE;
           uinfo.si_pid = getpid();   /* Process ID of sender */
           uinfo.si_uid = getuid();   /* Real UID of sender */
           uinfo.si_value = val;      /* argument supplied to sigqueue() */

SEE ALSO top

       kill(2), rt_sigqueueinfo(2), sigaction(2), signal(2), pthread_sigqueue(3),
       sigwait(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-03-25                         SIGQUEUE(3)


sigwait(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SIGWAIT(3)                   Linux Programmer's Manual                  SIGWAIT(3)

NAME top

       sigwait - wait for a signal

SYNOPSIS top

       #include <signal.h>

        int sigwait(const sigset_t *set, int *sig);

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

       sigwait(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The sigwait() function suspends execution of the calling thread until one
       of the signals specified in the signal set set becomes pending.  The
       function accepts the signal (removes it from the pending list of signals),
       and returns the signal number in sig.

       The operation of sigwait() is the same as sigwaitinfo(2), except that:

       * sigwait() only returns the signal number, rather than a siginfo_t
         structure describing the signal.

       * The return values of the two functions are different.

RETURN VALUE top

       On success, sigwait() returns 0.  On error, it returns a positive error
       number (listed in ERRORS).

ERRORS top

       EINVAL set contains an invalid signal number.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       sigwait() is implemented using sigtimedwait(2).

EXAMPLE top

       See pthread_sigmask(3).

SEE ALSO top

       sigaction(2), signalfd(2), sigpending(2), sigsuspend(2), sigwaitinfo(2),
       sigsetops(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-21                          SIGWAIT(3)


sin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SIN(3)                       Linux Programmer's Manual                      SIN(3)

NAME top

       sin, sinf, sinl - sine function

SYNOPSIS top

       #include <math.h>

       double sin(double x);
       float sinf(float x);
       long double sinl(long double x);

       Link with -lm.

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

       sinf(), sinl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The sin() function returns the sine of x, where x is given in radians.

RETURN VALUE top

       On success, these functions return the sine of x.

       If x is a NaN, a NaN is returned.

       If x is positive infinity or negative infinity, a domain error occurs, and
       a NaN is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity
              errno is set to EDOM (but see BUGS).  An invalid floating-point
              exception (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

BUGS top

       Before version 2.10, the glibc implementation did not set errno to EDOM
       when a domain error occurred.

SEE ALSO top

       acos(3), asin(3), atan(3), atan2(3), cos(3), csin(3), sincos(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-11                              SIN(3)


sincos(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SINCOS(3)                    Linux Programmer's Manual                   SINCOS(3)

NAME top

       sincos, sincosf, sincosl - calculate sin and cos simultaneously

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <math.h>

       void sincos(double x, double *sin, double *cos);
       void sincosf(float x, float *sin, float *cos);
       void sincosl(long double x, long double *sin, long double *cos);

       Link with -lm.

DESCRIPTION top

       Several applications need sine and cosine of the same angle x.  This
       function computes both at the same time, and stores the results in *sin and
       *cos.

       If x is a NaN, a NaN is returned in *sin and *cos.

       If x is positive infinity or negative infinity, a domain error occurs, and
       a NaN is returned in *sin and *cos.

RETURN VALUE top

       These functions return void.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity
              An invalid floating-point exception (FE_INVALID) is raised.

       These functions do not set errno.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       This function is a GNU extension.

SEE ALSO top

       cos(3), sin(3), tan(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2008-08-11                           SINCOS(3)


sinh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SINH(3)                      Linux Programmer's Manual                     SINH(3)

NAME top

       sinh, sinhf, sinhl - hyperbolic sine function

SYNOPSIS top

       #include <math.h>

       double sinh(double x);
       float sinhf(float x);
       long double sinhl(long double x);

       Link with -lm.

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

       sinhf(), sinhl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The sinh() function returns the hyperbolic sine of x, which is defined
       mathematically as:

           sinh(x) = (exp(x) - exp(-x)) / 2

RETURN VALUE top

       On success, these functions return the hyperbolic sine of x.

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity (negative infinity), positive infinity (negative
       infinity) is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with the same sign as x.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Range error: result overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       acosh(3), asinh(3), atanh(3), cosh(3), csinh(3), tanh(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             SINH(3)


sk98lin(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SK98LIN(4)                   Linux Programmer's Manual                  SK98LIN(4)

NAME top

       sk98lin - Marvell/SysKonnect Gigabit Ethernet driver v6.21

SYNOPSIS top

       insmod  sk98lin.o [Speed_A=i,j,...]  [Speed_B=i,j,...]  [AutoNeg_A=i,j,...]
       [AutoNeg_B=i,j,...]    [DupCap_A=i,j,...]    [DupCap_B=i,j,...]     [FlowC-
       trl_A=i,j,...]   [FlowCtrl_B=i,j,...]   [Role_A=i,j,...]   [Role_B=i,j,...]
       [ConType=i,j,...]    [Moderation=i,j,...]    [IntsPerSec=i,j,...]    [Pref-
       Port=i,j,...]  [RlmtMode=i,j,...]

DESCRIPTION top

       Note: This obsolete driver was removed from the kernel in version 2.6.26.

       sk98lin is the Gigabit Ethernet driver for Marvell and SysKonnect network
       adapter cards.  It supports SysKonnect SK-98xx/SK-95xx compliant Gigabit
       Ethernet Adapter and any Yukon compliant chipset.

       When loading the driver using insmod, parameters for the network adapter
       cards might be stated as a sequence of comma separated commands.  If for
       instance two network adapters are installed and AutoNegotiation on Port A
       of the first adapter should be ON, but on the Port A of the second adapter
       switched OFF, one must enter:

          insmod sk98lin.o AutoNeg_A=On,Off

       After sk98lin is bound to one or more adapter cards and the /proc file
       system is mounted on your system, a dedicated statistics file will be
       created in folder /proc/net/sk98lin for all ports of the installed network
       adapter cards.  Those files are named eth[x] whereas x is the number of the
       interface that has been assigned to a dedicated port by the system.

       If loading is finished, any desired IP address can be assigned to the
       respective eth[x] interface using the ifconfig(8) command.  This causes the
       adapter to connect to the Ethernet and to display a status message on the
       console saying "ethx: network connection up using port y" followed by the
       configured or detected connection parameters.

       The sk98lin also supports large frames (also called jumbo frames).  Using
       jumbo frames can improve throughput tremendously when transferring large
       amounts of data.  To enable large frames, the MTU (maximum transfer unit)
       size for an interface is to be set to a high value.  The default MTU size
       is 1500 and can be changed up to 9000 (bytes).  Setting the MTU size can be
       done when assigning the IP address to the interface or later by using the
       ifconfig(8) command with the mtu parameter.  If for instance eth0 needs an
       IP address and a large frame MTU size, the following two commands might be
       used:

           ifconfig eth0 10.1.1.1
           ifconfig eth0 mtu 9000

       Those two commands might even be combined into one:

           ifconfig eth0 10.1.1.1 mtu 9000

       Note that large frames can only be used if permitted by your network
       infrastructure.  This means, that any switch being used in your Ethernet
       must also support large frames.  Quite some switches support large frames,
       but need to be configured to do so.  Most of the times, their default
       setting is to support only standard frames with an MTU size of 1500
       (bytes).  In addition to the switches inside the network, all network
       adapters that are to be used must also be enabled regarding jumbo frames.
       If an adapter is not set to receive large frames it will simply drop them.

       Switching back to the standard Ethernet frame size can be done by using the
       ifconfig(8) command again:

           ifconfig eth0 mtu 1500

       The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to support
       VLAN and Link Aggregation according to IEEE standards 802.1, 802.1q, and
       802.3ad.  Those features are only available after installation of open
       source modules which can be found on the Internet:

       VLAN: <http://www.candelatech.com/~greear/vlan.html>
       Link Aggregation: <http://www.st.rim.or.jp/~yumo>

       Note that Marvell/SysKonnect does not offer any support for these open
       source modules and does not take the responsibility for any kind of fail-
       ures or problems arising when using these modules.

Parameters

       Speed_A=[22mi,j,...[0m
              This parameter is used to set the speed capabilities of port A of an
              adapter card.  It is only valid for Yukon copper adapters.  Possible
              values are: 10, 100, 1000 or Auto whereas Auto is the default.  Usu-
              ally, the speed is negotiated between the two ports during link
              establishment.  If this fails, a port can be forced to a specific
              setting with this parameter.

       Speed_B=[22mi,j,...[0m
              This parameter is used to set the speed capabilities of port B of an
              adapter card.  It is only valid for Yukon copper adapters.  Possible
              values are: 10, 100, 1000 or Auto whereas Auto is the default.  Usu-
              ally, the speed is negotiated between the two ports during link
              establishment.  If this fails, a port can be forced to a specific
              setting with this parameter.

       AutoNeg_A=[22mi,j,...[0m
              Enables or disables the use of autonegotiation of port A of an
              adapter card.  Possible values are: On, Off or Sense whereas On is
              the default.  The Sense mode automatically detects whether the link
              partner supports auto-negotiation or not.

       AutoNeg_B=[22mi,j,...[0m
              Enables or disables the use of autonegotiation of port B of an
              adapter card.  Possible values are: On, Off or Sense whereas On is
              the default.  The Sense mode automatically detects whether the link
              partner supports auto-negotiation or not.

       DupCap_A=[22mi,j,...[0m
              This parameter indicates the duplex mode to be used for port A of an
              adapter card.  Possible values are: Half, Full or Both whereas Both
              is the default.  This parameter is only relevant if AutoNeg_A of
              port A is not set to Sense.  If AutoNeg_A is set to On, all three
              values of DupCap_A ( Half, Full or Both) might be stated.  If
              AutoNeg_A is set to Off, only DupCap_A values Full and Half are
              allowed.  This DupCap_A parameter is useful if your link partner
              does not support all possible duplex combinations.

       DupCap_B=[22mi,j,...[0m
              This parameter indicates the duplex mode to be used for port B of an
              adapter card.  Possible values are: Half, Full or Both whereas Both
              is the default.  This parameter is only relevant if AutoNeg_B of
              port B is not set to Sense.  If AutoNeg_B is set to On, all three
              values of DupCap_B ( Half, Full or Both) might be stated.  If
              AutoNeg_B is set to Off, only DupCap_B values Full and Half are
              allowed.  This DupCap_B parameter is useful if your link partner
              does not support all possible duplex combinations.

       FlowCtrl_A=[22mi,j,...[0m
              This parameter can be used to set the flow control capabilities the
              port reports during auto-negotiation.  Possible values are: Sym,
              SymOrRem, LocSend or None whereas SymOrRem is the default.  The dif-
              ferent modes have the following meaning:

              Sym = Symmetric
               both link partners are allowed to send PAUSE frames
              SymOrRem = SymmetricOrRemote
               both or only remote partner are allowed to send PAUSE frames
              LocSend = LocalSend
               only local link partner is allowed to send PAUSE frames
              None = None
               no link partner is allowed to send PAUSE frames

              Note that this parameter is ignored if AutoNeg_A is set to Off.

       FlowCtrl_B=[22mi,j,...[0m
              This parameter can be used to set the flow control capabilities the
              port reports during auto-negotiation.  Possible values are: Sym,
              SymOrRem, LocSend or None whereas SymOrRem is the default.  The dif-
              ferent modes have the following meaning:

              Sym = Symmetric
               both link partners are allowed to send PAUSE frames
              SymOrRem = SymmetricOrRemote
               both or only remote partner are allowed to send PAUSE frames
              LocSend = LocalSend
               only local link partner is allowed to send PAUSE frames
              None = None
               no link partner is allowed to send PAUSE frames

              Note that this parameter is ignored if AutoNeg_B is set to Off.

       Role_A=[22mi,j,...[0m
              This parameter is only valid for 1000Base-T adapter cards.  For two
              1000Base-T ports to communicate, one must take the role of the mas-
              ter (providing timing information), while the other must be the
              slave.  Possible values are: Auto, Master or Slave whereas Auto is
              the default.  Usually, the role of a port is negotiated between two
              ports during link establishment, but if that fails the port A of an
              adapter card can be forced to a specific setting with this parame-
              ter.

       Role_B=[22mi,j,...[0m
              This parameter is only valid for 1000Base-T adapter cards.  For two
              1000Base-T ports to communicate, one must take the role of the mas-
              ter (providing timing information), while the other must be the
              slave.  Possible values are: Auto, Master or Slave whereas Auto is
              the default.  Usually, the role of a port is negotiated between two
              ports during link establishment, but if that fails the port B of an
              adapter card can be forced to a specific setting with this parame-
              ter.

       ConType=[22mi,j,...[0m
              This parameter is a combination of all five per-port parameters
              within one single parameter.  This simplifies the configuration of
              both ports of an adapter card.  The different values of this vari-
              able reflect the most meaningful combinations of port parameters.
              Possible values and their corresponding combination of per-port
              parameters:

              ConType | DupCap   AutoNeg   FlowCtrl   Role   Speed
              --------+-------------------------------------------
              Auto    |  Both      On      SymOrRem   Auto   Auto
              100FD   |  Full      Off       None     Auto   100
              100HD   |  Half      Off       None     Auto   100
              10FD    |  Full      Off       None     Auto   10
              10HD    |  Half      Off       None     Auto   10

              Stating any other port parameter together with this ConType parame-
              ter will result in a merged configuration of those settings.  This
              is due to the fact, that the per-port parameters (e.g., Speed_A)
              have a higher priority than the combined variable ConType.

       Moderation=[22mi,j,...[0m
              Interrupt moderation is employed to limit the maximum number of
              interrupts the driver has to serve.  That is, one or more interrupts
              (which indicate any transmit or receive packet to be processed) are
              queued until the driver processes them.  When queued interrupts are
              to be served, is determined by the IntsPerSec parameter, which is
              explained later below.  Possible moderation modes are: None, Static
              or Dynamic whereas None is the default.  The different modes have
              the following meaning:

              None No interrupt moderation is applied on the adapter card.  There-
              fore, each transmit or receive interrupt is served immediately as
              soon as it appears on the interrupt line of the adapter card.

              Static Interrupt moderation is applied on the adapter card.  All
              transmit and receive interrupts are queued until a complete modera-
              tion interval ends.  If such a moderation interval ends, all queued
              interrupts are processed in one big bunch without any delay.  The
              term Static reflects the fact, that interrupt moderation is always
              enabled, regardless how much network load is currently passing via a
              particular interface.  In addition, the duration of the moderation
              interval has a fixed length that never changes while the driver is
              operational.

              Dynamic Interrupt moderation might be applied on the adapter card,
              depending on the load of the system.  If the driver detects that the
              system load is too high, the driver tries to shield the system
              against too much network load by enabling interrupt moderation.
              If--at a later time--the CPU utilization decreases again (or if the
              network load is negligible) the interrupt moderation will automati-
              cally be disabled.

              Interrupt moderation should be used when the driver has to handle
              one or more interfaces with a high network load, which--as a conse-
              quence--leads also to a high CPU utilization.  When moderation is
              applied in such high network load situations, CPU load might be
              reduced by 20-30% on slow computers.

              Note that the drawback of using interrupt moderation is an increase
              of the round-trip-time (RTT), due to the queuing and serving of
              interrupts at dedicated moderation times.

       IntsPerSec=[22mi,j,...[0m
              This parameter determines the length of any interrupt moderation
              interval.  Assuming that static interrupt moderation is to be used,
              an IntsPerSec parameter value of 2000 will lead to an interrupt mod-
              eration interval of 500 microseconds.  Possible values for this
              parameter are in the range of 30...40000 (interrupts per second).
              The default value is 2000.

              This parameter is only used, if either static or dynamic interrupt
              moderation is enabled on a network adapter card.  This parameter is
              ignored if no moderation is applied.

              Note that the duration of the moderation interval is to be chosen
              with care.  At first glance, selecting a very long duration (e.g.,
              only 100 interrupts per second) seems to be meaningful, but the
              increase of packet-processing delay is tremendous.  On the other
              hand, selecting a very short moderation time might compensate the
              use of any moderation being applied.

       PrefPort=[22mi,j,...[0m
              This parameter is used to force the preferred port to A or B (on
              dual-port network adapters).  The preferred port is the one that is
              used if both ports A and B are detected as fully functional.  Possi-
              ble values are: A or B whereas A is the default.

       RlmtMode=[22mi,j,...[0m
              RLMT monitors the status of the port.  If the link of the active
              port fails, RLMT switches immediately to the standby link.  The vir-
              tual link is maintained as long as at least one "physical" link is
              up.  This parameters states how RLMT should monitor both ports.
              Possible values are: CheckLinkState, CheckLocalPort, CheckSeg or
              DualNet whereas CheckLinkState is the default.  The different modes
              have the following meaning:

              CheckLinkState Check link state only: RLMT uses the link state
              reported by the adapter hardware for each individual port to deter-
              mine whether a port can be used for all network traffic or not.

              CheckLocalPort In this mode, RLMT monitors the network path between
              the two ports of an adapter by regularly exchanging packets between
              them.  This mode requires a network configuration in which the two
              ports are able to "see" each other (i.e., there must not be any
              router between the ports).

              CheckSeg Check local port and segmentation: This mode supports the
              same functions as the CheckLocalPort mode and additionally checks
              network segmentation between the ports.  Therefore, this mode is
              only to be used if Gigabit Ethernet switches are installed on the
              network that have been configured to use the Spanning Tree protocol.

              DualNet In this mode, ports A and B are used as separate devices.
              If you have a dual port adapter, port A will be configured as eth[x]
              and port B as eth[x+1].  Both ports can be used independently with
              distinct IP addresses.  The preferred port setting is not used.
              RLMT is turned off.

              Note that RLMT modes CheckLocalPort and CheckLinkState are designed
              to operate in configurations where a network path between the ports
              on one adapter exists.  Moreover, they are not designed to work
              where adapters are connected back-to-back.

FILES top

       /proc/net/sk98lin/eth[x]
              The statistics file of a particular interface of an adapter card.
              It contains generic information about the adapter card plus a
              detailed summary of all transmit and receive counters.

       /usr/src/linux/Documentation/networking/sk98lin.txt
              This is the README file of the sk98lin driver.  It contains a
              detailed installation HOWTO and describes all parameters of the
              driver.  It denotes also common problems and provides the solution
              to them.

BUGS top

       Report any bugs to linux@syskonnect.de

SEE ALSO top

       ifconfig(8), insmod(8), modprobe(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                          SK98LIN(4)


slabinfo(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | VERSIONS | NOTES | COLOPHON The Linux Programming Interface

SLABINFO(5)                  Linux Programmer's Manual                 SLABINFO(5)

NAME top

       /proc/slabinfo - kernel slab allocator statistics

SYNOPSIS top

       cat /proc/slabinfo

DESCRIPTION top

       Frequently used objects in the Linux kernel (buffer heads, inodes,
       dentries, etc.)  have their own cache.  The file /proc/slabinfo gives
       statistics.  For example:

           % cat /proc/slabinfo
           slabinfo - version: 1.1
           kmem_cache            60     78    100    2    2    1
           blkdev_requests     5120   5120     96  128  128    1
           mnt_cache             20     40     96    1    1    1
           inode_cache         7005  14792    480 1598 1849    1
           dentry_cache        5469   5880    128  183  196    1
           filp                 726    760     96   19   19    1
           buffer_head        67131  71240     96 1776 1781    1
           vm_area_struct      1204   1652     64   23   28    1
           ...
           size-8192              1     17   8192    1   17    2
           size-4096             41     73   4096   41   73    1
           ...

       For each slab cache, the cache name, the number of currently active
       objects, the total number of available objects, the size of each object in
       bytes, the number of pages with at least one active object, the total
       number of allocated pages, and the number of pages per slab are given.

       Note that because of object alignment and slab cache overhead, objects are
       not normally packed tightly into pages.  Pages with even one in-use object
       are considered in-use and cannot be freed.

       Kernels compiled with slab cache statistics will also have "(statistics)"
       in the first line of output, and will have 5 additional columns, namely:
       the high water mark of active objects; the number of times objects have
       been allocated; the number of times the cache has grown (new pages added to
       this cache); the number of times the cache has been reaped (unused pages
       removed from this cache); and the number of times there was an error
       allocating new pages to this cache.  If slab cache statistics are not
       enabled for this kernel, these columns will not be shown.

       SMP systems will also have "(SMP)" in the first line of output, and will
       have two additional columns for each slab, reporting the slab allocation
       policy for the CPU-local cache (to reduce the need for inter-CPU
       synchronization when allocating objects from the cache).  The first column
       is the per-CPU limit: the maximum number of objects that will be cached for
       each CPU.  The second column is the batchcount: the maximum number of free
       objects in the global cache that will be transferred to the per-CPU cache
       if it is empty, or the number of objects to be returned to the global cache
       if the per-CPU cache is full.

       If both slab cache statistics and SMP are defined, there will be four
       additional columns, reporting the per-CPU cache statistics.  The first two
       are the per-CPU cache allocation hit and miss counts: the number of times
       an object was or was not available in the per-CPU cache for allocation.
       The next two are the per-CPU cache free hit and miss counts: the number of
       times a freed object could or could not fit within the per-CPU cache limit,
       before flushing objects to the global cache.

       It is possible to tune the SMP per-CPU slab cache limit and batchcount via:

           echo "cache_name limit batchcount" > /proc/slabinfo

FILES top

       <linux/slab.h>

VERSIONS top

       /proc/slabinfo exists since Linux 2.1.23.  SMP per-CPU caches exist since
       Linux 2.4.0-test3.

NOTES top

       Since Linux 2.6.16 the file /proc/slabinfo is only present if the
       CONFIG_SLAB kernel configuration option is enabled.

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-09-30                         SLABINFO(5)


sleep(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SLEEP(3)                     Linux Programmer's Manual                    SLEEP(3)

NAME top

       sleep - sleep for the specified number of seconds

SYNOPSIS top

       #include <unistd.h>

       unsigned int sleep(unsigned int seconds);

DESCRIPTION top

       sleep() makes the calling thread sleep until seconds seconds have elapsed
       or a signal arrives which is not ignored.

RETURN VALUE top

       Zero if the requested time has elapsed, or the number of seconds left to
       sleep, if the call was interrupted by a signal handler.

CONFORMING TO top

       POSIX.1-2001.

BUGS top

       sleep() may be implemented using SIGALRM; mixing calls to alarm(2) and
       sleep() is a bad idea.

       Using longjmp(3) from a signal handler or modifying the handling of SIGALRM
       while sleeping will cause undefined results.

SEE ALSO top

       alarm(2), nanosleep(2), signal(2), signal(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-02-03                            SLEEP(3)


sockatmark(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SOCKATMARK(3)                Linux Programmer's Manual               SOCKATMARK(3)

NAME top

       sockatmark - determine whether socket is at out-of-band mark

SYNOPSIS top

       #include <sys/socket.h>

       int sockatmark(int sockfd);

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

       sockatmark(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600

DESCRIPTION top

       sockatmark() returns a value indicating whether or not the socket referred
       to by the file descriptor sockfd is at the out-of-band mark.  If the socket
       is at the mark, then 1 is returned; if the socket is not at the mark, 0 is
       returned.  This function does not remove the out-of-band mark.

RETURN VALUE top

       A successful call to sockatmark() returns 1 if the socket is at the out-of-
       band mark, or 0 if it is not.  On error, -1 is returned and errno is set to
       indicate the error.

ERRORS top

       EBADF  sockfd is not a valid file descriptor.

       EINVAL sockfd is not a file descriptor to which sockatmark() can be
              applied.

VERSIONS top

       sockatmark() was added to glibc in version 2.2.4.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       If sockatmark() returns 1, then the out-of-band data can be read using the
       MSG_OOB flag of recv(2).

       Out-of-band data is only supported on some stream socket protocols.

       sockatmark() can safely be called from a handler for the SIGURG signal.

       sockatmark() is implemented using the SIOCATMARK ioctl(2) operation.

BUGS top

       Prior to glibc 2.4, sockatmark() did not work.

EXAMPLE top

       The following code can be used after receipt of a SIGURG signal to read
       (and discard) all data up to the mark, and then read the byte of data at
       the mark:

           char buf[BUF_LEN];
           char oobdata;
           int atmark, s;

           for (;;) {
               atmark = sockatmark(sockfd);
               if (atmark == -1) {
                   perror("sockatmark");
                   break;
               }

               if (atmark)
                   break;

               s = read(sockfd, buf, BUF_LEN) <= 0);
               if (s == -1)
                   perror("read");
               if (s <= 0)
                   break;
           }

           if (atmark == 1) {
               if (recv(sockfd, &oobdata, 1, MSG_OOB) == -1) {
                   perror("recv");
                   ...
               }
           }

SEE ALSO top

       fcntl(2), recv(2), send(2), tcp(7)

COLOPHON top

       This page is part of release 3.45 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-03                       SOCKATMARK(3)


socket(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SOCKET(2)                    Linux Programmer's Manual                   SOCKET(2)

NAME top

       socket - create an endpoint for communication

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int socket(int domain, int type, int protocol);

DESCRIPTION top

       socket() creates an endpoint for communication and returns a descriptor.

       The domain argument specifies a communication domain; this selects the
       protocol family which will be used for communication.  These families are
       defined in <sys/socket.h>.  The currently understood formats include:

       Name                Purpose                          Man page
       AF_UNIX, AF_LOCAL   Local communication              unix(7)
       AF_INET             IPv4 Internet protocols          ip(7)
       AF_INET6            IPv6 Internet protocols          ipv6(7)
       AF_IPX              IPX - Novell protocols
       AF_NETLINK          Kernel user interface device     netlink(7)
       AF_X25              ITU-T X.25 / ISO-8208 protocol   x25(7)
       AF_AX25             Amateur radio AX.25 protocol
       AF_ATMPVC           Access to raw ATM PVCs
       AF_APPLETALK        Appletalk                        ddp(7)
       AF_PACKET           Low level packet interface       packet(7)

       The socket has the indicated type, which specifies the communication
       semantics.  Currently defined types are:

       SOCK_STREAM     Provides sequenced, reliable, two-way, connection-based
                       byte streams.  An out-of-band data transmission mechanism
                       may be supported.

       SOCK_DGRAM      Supports datagrams (connectionless, unreliable messages of
                       a fixed maximum length).

       SOCK_SEQPACKET  Provides a sequenced, reliable, two-way connection-based
                       data transmission path for datagrams of fixed maximum
                       length; a consumer is required to read an entire packet
                       with each input system call.

       SOCK_RAW        Provides raw network protocol access.

       SOCK_RDM        Provides a reliable datagram layer that does not guarantee
                       ordering.

       SOCK_PACKET     Obsolete and should not be used in new programs; see
                       packet(7).

       Some socket types may not be implemented by all protocol families; for
       example, SOCK_SEQPACKET is not implemented for AF_INET.

       Since Linux 2.6.27, the type argument serves a second purpose: in addition
       to specifying a socket type, it may include the bitwise OR of any of the
       following values, to modify the behavior of socket():

       SOCK_NONBLOCK   Set the O_NONBLOCK file status flag on the new open file
                       description.  Using this flag saves extra calls to fcntl(2)
                       to achieve the same result.

       SOCK_CLOEXEC    Set the close-on-exec (FD_CLOEXEC) flag on the new file
                       descriptor.  See the description of the O_CLOEXEC flag in
                       open(2) for reasons why this may be useful.

       The protocol specifies a particular protocol to be used with the socket.
       Normally only a single protocol exists to support a particular socket type
       within a given protocol family, in which case protocol can be specified as
       0.  However, it is possible that many protocols may exist, in which case a
       particular protocol must be specified in this manner.  The protocol number
       to use is specific to the "communication domain" in which communication is
       to take place; see protocols(5).  See getprotoent(3) on how to map protocol
       name strings to protocol numbers.

       Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes.
       They do not preserve record boundaries.  A stream socket must be in a
       connected state before any data may be sent or received on it.  A
       connection to another socket is created with a connect(2) call.  Once
       connected, data may be transferred using read(2) and write(2) calls or some
       variant of the send(2) and recv(2) calls.  When a session has been
       completed a close(2) may be performed.  Out-of-band data may also be
       transmitted as described in send(2) and received as described in recv(2).

       The communications protocols which implement a SOCK_STREAM ensure that data
       is not lost or duplicated.  If a piece of data for which the peer protocol
       has buffer space cannot be successfully transmitted within a reasonable
       length of time, then the connection is considered to be dead.  When
       SO_KEEPALIVE is enabled on the socket the protocol checks in a protocol-
       specific manner if the other end is still alive.  A SIGPIPE signal is
       raised if a process sends or receives on a broken stream; this causes naive
       processes, which do not handle the signal, to exit.  SOCK_SEQPACKET sockets
       employ the same system calls as SOCK_STREAM sockets.  The only difference
       is that read(2) calls will return only the amount of data requested, and
       any data remaining in the arriving packet will be discarded.  Also all
       message boundaries in incoming datagrams are preserved.

       SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to
       correspondents named in sendto(2) calls.  Datagrams are generally received
       with recvfrom(2), which returns the next datagram along with the address of
       its sender.

       SOCK_PACKET is an obsolete socket type to receive raw packets directly from
       the device driver.  Use packet(7) instead.

       An fcntl(2) F_SETOWN operation can be used to specify a process or process
       group to receive a SIGURG signal when the out-of-band data arrives or
       SIGPIPE signal when a SOCK_STREAM connection breaks unexpectedly.  This
       operation may also be used to set the process or process group that
       receives the I/O and asynchronous notification of I/O events via SIGIO.
       Using F_SETOWN is equivalent to an ioctl(2) call with the FIOSETOWN or
       SIOCSPGRP argument.

       When the network signals an error condition to the protocol module (e.g.,
       using a ICMP message for IP) the pending error flag is set for the socket.
       The next operation on this socket will return the error code of the pending
       error.  For some protocols it is possible to enable a per-socket error
       queue to retrieve detailed information about the error; see IP_RECVERR in
       ip(7).

       The operation of sockets is controlled by socket level options.  These
       options are defined in <sys/socket.h>.  The functions setsockopt(2) and
       getsockopt(2) are used to set and get options, respectively.

RETURN VALUE top

       On success, a file descriptor for the new socket is returned.  On error, -1
       is returned, and errno is set appropriately.

ERRORS top

       EACCES Permission to create a socket of the specified type and/or protocol
              is denied.

       EAFNOSUPPORT
              The implementation does not support the specified address family.

       EINVAL Unknown protocol, or protocol family not available.

       EINVAL Invalid flags in type.

       EMFILE Process file table overflow.

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

       ENOBUFS or ENOMEM
              Insufficient memory is available.  The socket cannot be created
              until sufficient resources are freed.

       EPROTONOSUPPORT
              The protocol type or the specified protocol is not supported within
              this domain.

       Other errors may be generated by the underlying protocol modules.

CONFORMING TO top

       4.4BSD, POSIX.1-2001.

       The SOCK_NONBLOCK and SOCK_CLOEXEC flags are Linux-specific.

       socket() appeared in 4.2BSD.  It is generally portable to/from non-BSD
       systems supporting clones of the BSD socket layer (including System V
       variants).

NOTES top

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

       The manifest constants used under 4.x BSD for protocol families are
       PF_UNIX, PF_INET, and so on, while AF_UNIX, AF_INET, and so on are used for
       address families.  However, already the BSD man page promises: "The
       protocol family generally is the same as the address family", and
       subsequent standards use AF_* everywhere.

EXAMPLE top

       An example of the use of socket() is shown in getaddrinfo(3).

SEE ALSO top

       accept(2), bind(2), connect(2), fcntl(2), getpeername(2), getsockname(2),
       getsockopt(2), ioctl(2), listen(2), read(2), recv(2), select(2), send(2),
       shutdown(2), socketpair(2), write(2), getprotoent(3), ip(7), socket(7),
       tcp(7), udp(7), unix(7)

       "An Introductory 4.3BSD Interprocess Communication Tutorial" and "BSD
       Interprocess Communication Tutorial", reprinted in UNIX Programmer's
       Supplementary Documents Volume 1.

COLOPHON top

       This page is part of release 3.45 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                               2009-01-19                           SOCKET(2)


socket(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SOCKET(7)                    Linux Programmer's Manual                   SOCKET(7)

NAME top

       socket - Linux socket interface

SYNOPSIS top

       #include <sys/socket.h>

       sockfd = socket(int socket_family, int socket_type, int protocol);

DESCRIPTION top

       This manual page describes the Linux networking socket layer user
       interface.  The BSD compatible sockets are the uniform interface between
       the user process and the network protocol stacks in the kernel.  The
       protocol modules are grouped into protocol families like AF_INET, AF_IPX,
       AF_PACKET and socket types like SOCK_STREAM or SOCK_DGRAM.  See socket(2)
       for more information on families and types.

Socket Layer Functions

       These functions are used by the user process to send or receive packets and
       to do other socket operations.  For more information see their respective
       manual pages.

       socket(2) creates a socket, connect(2) connects a socket to a remote socket
       address, the bind(2) function binds a socket to a local socket address,
       listen(2) tells the socket that new connections shall be accepted, and
       accept(2) is used to get a new socket with a new incoming connection.
       socketpair(2) returns two connected anonymous sockets (only implemented for
       a few local families like AF_UNIX)

       send(2), sendto(2), and sendmsg(2) send data over a socket, and recv(2),
       recvfrom(2), recvmsg(2) receive data from a socket.  poll(2) and select(2)
       wait for arriving data or a readiness to send data.  In addition, the
       standard I/O operations like write(2), writev(2), sendfile(2), read(2), and
       readv(2) can be used to read and write data.

       getsockname(2) returns the local socket address and getpeername(2) returns
       the remote socket address.  getsockopt(2) and setsockopt(2) are used to set
       or get socket layer or protocol options.  ioctl(2) can be used to set or
       read some other options.

       close(2) is used to close a socket.  shutdown(2) closes parts of a full-
       duplex socket connection.

       Seeking, or calling pread(2) or pwrite(2) with a nonzero position is not
       supported on sockets.

       It is possible to do nonblocking I/O on sockets by setting the O_NONBLOCK
       flag on a socket file descriptor using fcntl(2).  Then all operations that
       would block will (usually) return with EAGAIN (operation should be retried
       later); connect(2) will return EINPROGRESS error.  The user can then wait
       for various events via poll(2) or select(2).

       +--------------------------------------------------------------------+
       |                            I/O events                              |
       +-----------+-----------+--------------------------------------------+
       |Event      | Poll flag | Occurrence                                 |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLIN    | New data arrived.                          |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLIN    | A connection setup has been completed (for |
       |           |           | connection-oriented sockets)               |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLHUP   | A disconnection request has been initiated |
       |           |           | by the other end.                          |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLHUP   | A connection is broken (only for           |
       |           |           | connection-oriented protocols).  When the  |
       |           |           | socket is written SIGPIPE is also sent.    |
       +-----------+-----------+--------------------------------------------+
       |Write      | POLLOUT   | Socket has enough send buffer space for    |
       |           |           | writing new data.                          |
       +-----------+-----------+--------------------------------------------+
       |Read/Write | POLLIN|   | An outgoing connect(2) finished.           |
       |           | POLLOUT   |                                            |
       +-----------+-----------+--------------------------------------------+
       |Read/Write | POLLERR   | An asynchronous error occurred.            |
       +-----------+-----------+--------------------------------------------+
       |Read/Write | POLLHUP   | The other end has shut down one direction. |
       +-----------+-----------+--------------------------------------------+
       |Exception  | POLLPRI   | Urgent data arrived.  SIGURG is sent then. |
       +-----------+-----------+--------------------------------------------+

       An alternative to poll(2) and select(2) is to let the kernel inform the
       application about events via a SIGIO signal.  For that the O_ASYNC flag
       must be set on a socket file descriptor via fcntl(2) and a valid signal
       handler for SIGIO must be installed via sigaction(2).  See the Signals
       discussion below.

Socket address structures

       Each socket domain has its own format for socket addresses, with a domain-
       specific address structure.  Each of these structures begins with an
       integer "family" field (typed as sa_family_t) that indicates the type of
       the address structure.  This allows the various system calls (e.g.,
       connect(2), bind(2), accept(2), getsockname(2), getpeername(2)), which are
       generic to all socket domains, to determine the domain of a particular
       socket address.

       To allow any type of socket address to be passed to interfaces in the
       sockets API, the type struct sockaddr is defined.  The purpose of this type
       is purely to allow casting of domain-specific socket address types to a
       "generic" type, so as to avoid compiler warnings about type mismatches in
       calls to the sockets API.

       In addition, the sockets API provides the data type struct
       sockaddr_storage.  This type is suitable to accommodate all supported
       domain-specific socket address structures; it is large enough and is
       aligned properly.  (In particular, it is large enough to hold IPv6 socket
       addresses.)  The structure includes the following field, which can be used
       to identify the type of socket address actually stored in the structure:

               sa_family_t ss_family;

       The sockaddr_storage structure is useful in programs that must handle
       socket addresses in a generic way (e.g., programs that must deal with both
       IPv4 and IPv6 socket addresses).

Socket Options

       These socket options can be set by using setsockopt(2) and read with
       getsockopt(2) with the socket level set to SOL_SOCKET for all sockets:

       SO_ACCEPTCONN
              Returns a value indicating whether or not this socket has been
              marked to accept connections with listen(2).  The value 0 indicates
              that this is not a listening socket, the value 1 indicates that this
              is a listening socket.  This socket option is read-only.

       SO_BINDTODEVICE
              Bind this socket to a particular device like "eth0", as specified in
              the passed interface name.  If the name is an empty string or the
              option length is zero, the socket device binding is removed.  The
              passed option is a variable-length null-terminated interface name
              string with the maximum size of IFNAMSIZ.  If a socket is bound to
              an interface, only packets received from that particular interface
              are processed by the socket.  Note that this only works for some
              socket types, particularly AF_INET sockets.  It is not supported for
              packet sockets (use normal bind(2) there).

       SO_BROADCAST
              Set or get the broadcast flag.  When enabled, datagram sockets are
              allowed to send packets to a broadcast address.  This option has no
              effect on stream-oriented sockets.

       SO_BSDCOMPAT
              Enable BSD bug-to-bug compatibility.  This is used by the UDP
              protocol module in Linux 2.0 and 2.2.  If enabled ICMP errors
              received for a UDP socket will not be passed to the user program.
              In later kernel versions, support for this option has been phased
              out: Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel
              warning (printk()) if a program uses this option.  Linux 2.0 also
              enabled BSD bug-to-bug compatibility options (random header
              changing, skipping of the broadcast flag) for raw sockets with this
              option, but that was removed in Linux 2.2.

       SO_DEBUG
              Enable socket debugging.  Only allowed for processes with the
              CAP_NET_ADMIN capability or an effective user ID of 0.

       SO_DOMAIN (since Linux 2.6.32)
              Retrieves the socket domain as an integer, returning a value such as
              AF_INET6.  See socket(2) for details.  This socket option is read-
              only.

       SO_ERROR
              Get and clear the pending socket error.  This socket option is read-
              only.  Expects an integer.

       SO_DONTROUTE
              Don't send via a gateway, only send to directly connected hosts.
              The same effect can be achieved by setting the MSG_DONTROUTE flag on
              a socket send(2) operation.  Expects an integer boolean flag.

       SO_KEEPALIVE
              Enable sending of keep-alive messages on connection-oriented
              sockets.  Expects an integer boolean flag.

       SO_LINGER
              Sets or gets the SO_LINGER option.  The argument is a linger
              structure.

                  struct linger {
                      int l_onoff;    /* linger active */
                      int l_linger;   /* how many seconds to linger for */
                  };

              When enabled, a close(2) or shutdown(2) will not return until all
              queued messages for the socket have been successfully sent or the
              linger timeout has been reached.  Otherwise, the call returns
              immediately and the closing is done in the background.  When the
              socket is closed as part of exit(2), it always lingers in the
              background.

       SO_MARK (since Linux 2.6.25)
              Set the mark for each packet sent through this socket (similar to
              the netfilter MARK target but socket-based).  Changing the mark can
              be used for mark-based routing without netfilter or for packet
              filtering.  Setting this option requires the CAP_NET_ADMIN
              capability.

       SO_OOBINLINE
              If this option is enabled, out-of-band data is directly placed into
              the receive data stream.  Otherwise out-of-band data is only passed
              when the MSG_OOB flag is set during receiving.

       SO_PASSCRED
              Enable or disable the receiving of the SCM_CREDENTIALS control
              message.  For more information see unix(7).

       SO_PEERCRED
              Return the credentials of the foreign process connected to this
              socket.  This is only possible for connected AF_UNIX stream sockets
              and AF_UNIX stream and datagram socket pairs created using
              socketpair(2); see unix(7).  The returned credentials are those that
              were in effect at the time of the call to connect(2) or
              socketpair(2).  Argument is a ucred structure.  This socket option
              is read-only.

       SO_PRIORITY
              Set the protocol-defined priority for all packets to be sent on this
              socket.  Linux uses this value to order the networking queues:
              packets with a higher priority may be processed first depending on
              the selected device queueing discipline.  For ip(7), this also sets
              the IP type-of-service (TOS) field for outgoing packets.  Setting a
              priority outside the range 0 to 6 requires the CAP_NET_ADMIN
              capability.

       SO_PROTOCOL (since Linux 2.6.32)
              Retrieves the socket protocol as an integer, returning a value such
              as IPPROTO_SCTP.  See socket(2) for details.  This socket option is
              read-only.

       SO_RCVBUF
              Sets or gets the maximum socket receive buffer in bytes.  The kernel
              doubles this value (to allow space for bookkeeping overhead) when it
              is set using setsockopt(2), and this doubled value is returned by
              getsockopt(2).  The default value is set by the
              /proc/sys/net/core/rmem_default file, and the maximum allowed value
              is set by the /proc/sys/net/core/rmem_max file.  The minimum
              (doubled) value for this option is 256.

       SO_RCVBUFFORCE (since Linux 2.6.14)
              Using this socket option, a privileged (CAP_NET_ADMIN) process can
              perform the same task as SO_RCVBUF, but the rmem_max limit can be
              overridden.

       SO_RCVLOWAT and SO_SNDLOWAT
              Specify the minimum number of bytes in the buffer until the socket
              layer will pass the data to the protocol (SO_SNDLOWAT) or the user
              on receiving (SO_RCVLOWAT).  These two values are initialized to 1.
              SO_SNDLOWAT is not changeable on Linux (setsockopt(2) fails with the
              error ENOPROTOOPT).  SO_RCVLOWAT is changeable only since Linux 2.4.
              The select(2) and poll(2) system calls currently do not respect the
              SO_RCVLOWAT setting on Linux, and mark a socket readable when even a
              single byte of data is available.  A subsequent read from the socket
              will block until SO_RCVLOWAT bytes are available.

       SO_RCVTIMEO and SO_SNDTIMEO
              Specify the receiving or sending timeouts until reporting an error.
              The argument is a struct timeval.  If an input or output function
              blocks for this period of time, and data has been sent or received,
              the return value of that function will be the amount of data
              transferred; if no data has been transferred and the timeout has
              been reached then -1 is returned with errno set to EAGAIN or
              EWOULDBLOCK, or EINPROGRESS (for connect(2)) just as if the socket
              was specified to be nonblocking.  If the timeout is set to zero (the
              default) then the operation will never timeout.  Timeouts only have
              effect for system calls that perform socket I/O (e.g., read(2),
              recvmsg(2), send(2), sendmsg(2)); timeouts have no effect for
              select(2), poll(2), epoll_wait(2), and so on.

       SO_REUSEADDR
              Indicates that the rules used in validating addresses supplied in a
              bind(2) call should allow reuse of local addresses.  For AF_INET
              sockets this means that a socket may bind, except when there is an
              active listening socket bound to the address.  When the listening
              socket is bound to INADDR_ANY with a specific port then it is not
              possible to bind to this port for any local address.  Argument is an
              integer boolean flag.

       SO_SNDBUF
              Sets or gets the maximum socket send buffer in bytes.  The kernel
              doubles this value (to allow space for bookkeeping overhead) when it
              is set using setsockopt(2), and this doubled value is returned by
              getsockopt(2).  The default value is set by the
              /proc/sys/net/core/wmem_default file and the maximum allowed value
              is set by the /proc/sys/net/core/wmem_max file.  The minimum
              (doubled) value for this option is 2048.

       SO_SNDBUFFORCE (since Linux 2.6.14)
              Using this socket option, a privileged (CAP_NET_ADMIN) process can
              perform the same task as SO_SNDBUF, but the wmem_max limit can be
              overridden.

       SO_TIMESTAMP
              Enable or disable the receiving of the SO_TIMESTAMP control message.
              The timestamp control message is sent with level SOL_SOCKET and the
              cmsg_data field is a struct timeval indicating the reception time of
              the last packet passed to the user in this call.  See cmsg(3) for
              details on control messages.

       SO_TYPE
              Gets the socket type as an integer (e.g., SOCK_STREAM).  This socket
              option is read-only.

Signals

       When writing onto a connection-oriented socket that has been shut down (by
       the local or the remote end) SIGPIPE is sent to the writing process and
       EPIPE is returned.  The signal is not sent when the write call specified
       the MSG_NOSIGNAL flag.

       When requested with the FIOSETOWN fcntl(2) or SIOCSPGRP ioctl(2), SIGIO is
       sent when an I/O event occurs.  It is possible to use poll(2) or select(2)
       in the signal handler to find out which socket the event occurred on.  An
       alternative (in Linux 2.2) is to set a real-time signal using the F_SETSIG
       fcntl(2); the handler of the real time signal will be called with the file
       descriptor in the si_fd field of its siginfo_t.  See fcntl(2) for more
       information.

       Under some circumstances (e.g., multiple processes accessing a single
       socket), the condition that caused the SIGIO may have already disappeared
       when the process reacts to the signal.  If this happens, the process should
       wait again because Linux will resend the signal later.

/proc interfaces

       The core socket networking parameters can be accessed via files in the
       directory /proc/sys/net/core/.

       rmem_default
              contains the default setting in bytes of the socket receive buffer.

       rmem_max
              contains the maximum socket receive buffer size in bytes which a
              user may set by using the SO_RCVBUF socket option.

       wmem_default
              contains the default setting in bytes of the socket send buffer.

       wmem_max
              contains the maximum socket send buffer size in bytes which a user
              may set by using the SO_SNDBUF socket option.

       message_cost and message_burst
              configure the token bucket filter used to load limit warning
              messages caused by external network events.

       netdev_max_backlog
              Maximum number of packets in the global input queue.

       optmem_max
              Maximum length of ancillary data and user control data like the
              iovecs per socket.

Ioctls

       These operations can be accessed using ioctl(2):

           error = ioctl(ip_socket, ioctl_type, &value_result);

       SIOCGSTAMP
              Return a struct timeval with the receive timestamp of the last
              packet passed to the user.  This is useful for accurate round trip
              time measurements.  See setitimer(2) for a description of struct
              timeval.  This ioctl should only be used if the socket option
              SO_TIMESTAMP is not set on the socket.  Otherwise, it returns the
              timestamp of the last packet that was received while SO_TIMESTAMP
              was not set, or it fails if no such packet has been received, (i.e.,
              ioctl(2) returns -1 with errno set to ENOENT).

       SIOCSPGRP
              Set the process or process group to send SIGIO or SIGURG signals to
              when an asynchronous I/O operation has finished or urgent data is
              available.  The argument is a pointer to a pid_t.  If the argument
              is positive, send the signals to that process.  If the argument is
              negative, send the signals to the process group with the ID of the
              absolute value of the argument.  The process may only choose itself
              or its own process group to receive signals unless it has the
              CAP_KILL capability or an effective UID of 0.

       FIOASYNC
              Change the O_ASYNC flag to enable or disable asynchronous I/O mode
              of the socket.  Asynchronous I/O mode means that the SIGIO signal or
              the signal set with F_SETSIG is raised when a new I/O event occurs.

              Argument is an integer boolean flag.  (This operation is synonymous
              with the use of fcntl(2) to set the O_ASYNC flag.)

       SIOCGPGRP
              Get the current process or process group that receives SIGIO or
              SIGURG signals, or 0 when none is set.

       Valid fcntl(2) operations:

       FIOGETOWN
              The same as the SIOCGPGRP ioctl(2).

       FIOSETOWN
              The same as the SIOCSPGRP ioctl(2).

VERSIONS top

       SO_BINDTODEVICE was introduced in Linux 2.0.30.  SO_PASSCRED is new in
       Linux 2.2.  The /proc interfaces was introduced in Linux 2.2.  SO_RCVTIMEO
       and SO_SNDTIMEO are supported since Linux 2.3.41.  Earlier, timeouts were
       fixed to a protocol-specific setting, and could not be read or written.

NOTES top

       Linux assumes that half of the send/receive buffer is used for internal
       kernel structures; thus the values in the corresponding /proc files are
       twice what can be observed on the wire.

       Linux will only allow port reuse with the SO_REUSEADDR option when this
       option was set both in the previous program that performed a bind(2) to the
       port and in the program that wants to reuse the port.  This differs from
       some implementations (e.g., FreeBSD) where only the later program needs to
       set the SO_REUSEADDR option.  Typically this difference is invisible,
       since, for example, a server program is designed to always set this option.

BUGS top

       The CONFIG_FILTER socket options SO_ATTACH_FILTER and SO_DETACH_FILTER are
       not documented.  The suggested interface to use them is via the libpcap
       library.

SEE ALSO top

       getsockopt(2), connect(2), setsockopt(2), socket(2), capabilities(7),
       ddp(7), ip(7), packet(7), tcp(7), udp(7), unix(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-15                           SOCKET(7)


socketcall(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SOCKETCALL(2)                Linux Programmer's Manual               SOCKETCALL(2)

NAME top

       socketcall - socket system calls

SYNOPSIS top

       int socketcall(int call, unsigned long *args);

DESCRIPTION top

       socketcall() is a common kernel entry point for the socket system calls.
       call determines which socket function to invoke.  args points to a block
       containing the actual arguments, which are passed through to the
       appropriate call.

       User programs should call the appropriate functions by their usual names.
       Only standard library implementors and kernel hackers need to know about
       socketcall().

CONFORMING TO top

       This call is specific to Linux, and should not be used in programs intended
       to be portable.

NOTES top

       On a some architectures--for example, x86-64 and ARM--there is no
       socketcall() system call; instead socket(2), accept(2), bind(2), and so on
       really are implemented as separate system calls.

SEE ALSO top

       accept(2), bind(2), connect(2), getpeername(2), getsockname(2),
       getsockopt(2), listen(2), recv(2), recvfrom(2), recvmsg(2), send(2),
       sendmsg(2), sendto(2), setsockopt(2), shutdown(2), socket(2), socketpair(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-16                       SOCKETCALL(2)


socketpair(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SOCKETPAIR(2)                Linux Programmer's Manual               SOCKETPAIR(2)

NAME top

       socketpair - create a pair of connected sockets

SYNOPSIS top

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int socketpair(int domain, int type, int protocol, int sv[2]);

DESCRIPTION top

       The socketpair() call creates an unnamed pair of connected sockets in the
       specified domain, of the specified type, and using the optionally specified
       protocol.  For further details of these arguments, see socket(2).

       The descriptors used in referencing the new sockets are returned in sv[0]
       and sv[1].  The two sockets are indistinguishable.

RETURN VALUE top

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

ERRORS top

       EAFNOSUPPORT
              The specified address family is not supported on this machine.

       EFAULT The address sv does not specify a valid part of the process address
              space.

       EMFILE Too many descriptors are in use by this process.

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

       EOPNOTSUPP
              The specified protocol does not support creation of socket pairs.

       EPROTONOSUPPORT
              The specified protocol is not supported on this machine.

CONFORMING TO top

       4.4BSD, POSIX.1-2001.  The socketpair() function call appeared in 4.2BSD.
       It is generally portable to/from non-BSD systems supporting clones of the
       BSD socket layer (including System V variants).

NOTES top

       On Linux, the only supported domain for this call is AF_UNIX (or
       synonymously, AF_LOCAL).  (Most implementations have the same restriction.)

       Since Linux 2.6.27, socketpair() supports the SOCK_NONBLOCK and
       SOCK_CLOEXEC flags described in socket(2).

       POSIX.1-2001 does not require the inclusion of <sys/types.h>, and this
       header file is not required on Linux.  However, some historical (BSD)
       implementations required this header file, and portable applications are
       probably wise to include it.

SEE ALSO top

       pipe(2), read(2), socket(2), write(2), socket(7), unix(7)

COLOPHON top

       This page is part of release 3.45 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-10-11                       SOCKETPAIR(2)


splice(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SPLICE(2)                    Linux Programmer's Manual                   SPLICE(2)

NAME top

       splice - splice data to/from a pipe

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <fcntl.h>

       ssize_t splice(int fd_in, loff_t *off_in, int fd_out,
                      loff_t *off_out, size_t len, unsigned int flags);

DESCRIPTION top

       splice() moves data between two file descriptors without copying between
       kernel address space and user address space.  It transfers up to len bytes
       of data from the file descriptor fd_in to the file descriptor fd_out, where
       one of the descriptors must refer to a pipe.

       If fd_in refers to a pipe, then off_in must be NULL.  If fd_in does not
       refer to a pipe and off_in is NULL, then bytes are read from fd_in starting
       from the current file offset, and the current file offset is adjusted
       appropriately.  If fd_in does not refer to a pipe and off_in is not NULL,
       then off_in must point to a buffer which specifies the starting offset from
       which bytes will be read from fd_in; in this case, the current file offset
       of fd_in is not changed.  Analogous statements apply for fd_out and
       off_out.

       The flags argument is a bit mask that is composed by ORing together zero or
       more of the following values:

       SPLICE_F_MOVE      Attempt to move pages instead of copying.  This is only
                          a hint to the kernel: pages may still be copied if the
                          kernel cannot move the pages from the pipe, or if the
                          pipe buffers don't refer to full pages.  The initial
                          implementation of this flag was buggy: therefore
                          starting in Linux 2.6.21 it is a no-op (but is still
                          permitted in a splice() call); in the future, a correct
                          implementation may be restored.

       SPLICE_F_NONBLOCK  Do not block on I/O.  This makes the splice pipe
                          operations nonblocking, but splice() may nevertheless
                          block because the file descriptors that are spliced
                          to/from may block (unless they have the O_NONBLOCK flag
                          set).

       SPLICE_F_MORE      More data will be coming in a subsequent splice.  This
                          is a helpful hint when the fd_out refers to a socket
                          (see also the description of MSG_MORE in send(2), and
                          the description of TCP_CORK in tcp(7))

       SPLICE_F_GIFT      Unused for splice(); see vmsplice(2).

RETURN VALUE top

       Upon successful completion, splice() returns the number of bytes spliced to
       or from the pipe.  A return value of 0 means that there was no data to
       transfer, and it would not make sense to block, because there are no
       writers connected to the write end of the pipe referred to by fd_in.

       On error, splice() returns -1 and errno is set to indicate the error.

ERRORS top

       EBADF  One or both file descriptors are not valid, or do not have proper
              read-write mode.

       EINVAL Target file system doesn't support splicing; target file is opened
              in append mode; neither of the descriptors refers to a pipe; or
              offset given for nonseekable device.

       ENOMEM Out of memory.

       ESPIPE Either off_in or off_out was not NULL, but the corresponding file
              descriptor refers to a pipe.

VERSIONS top

       The splice() system call first appeared in Linux 2.6.17; library support
       was added to glibc in version 2.5.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       The three system calls splice(), vmsplice(2), and tee(2), provide user-
       space programs with full control over an arbitrary kernel buffer,
       implemented within the kernel using the same type of buffer that is used
       for a pipe.  In overview, these system calls perform the following tasks:

       splice()    moves data from the buffer to an arbitrary file descriptor, or
                   vice versa, or from one buffer to another.

       tee(2)      "copies" the data from one buffer to another.

       vmsplice(2) "copies" data from user space into the buffer.

       Though we talk of copying, actual copies are generally avoided.  The kernel
       does this by implementing a pipe buffer as a set of reference-counted
       pointers to pages of kernel memory.  The kernel creates "copies" of pages
       in a buffer by creating new pointers (for the output buffer) referring to
       the pages, and increasing the reference counts for the pages: only pointers
       are copied, not the pages of the buffer.

EXAMPLE top

       See tee(2).

SEE ALSO top

       sendfile(2), tee(2), vmsplice(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                           SPLICE(2)


spufs(7) - Linux manual page

NAME | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SPUFS(7)                     Linux Programmer's Manual                    SPUFS(7)

NAME top

       spufs - SPU file system

DESCRIPTION top

       The SPU file system is used on PowerPC machines that implement the Cell
       Broadband Engine Architecture in order to access Synergistic Processor
       Units (SPUs).

       The file system provides a name space similar to POSIX shared memory or
       message queues.  Users that have write permissions on the file system can
       use spu_create(2) to establish SPU contexts under the spufs root directory.

       Every SPU context is represented by a directory containing a predefined set
       of files.  These files can be used for manipulating the state of the
       logical SPU.  Users can change permissions on the files, but can't add or
       remove files.

Mount Options

       uid=<uid>
              Set the user owning the mount point; the default is 0 (root).

       gid=<gid>
              Set the group owning the mount point; the default is 0 (root).

       mode=<mode>
              Set the mode of the top-level directory in spufs, as an octal mode
              string.  The default is 0775.

Files

       The files in spufs mostly follow the standard behavior for regular system
       calls like read(2) or write(2), but often support only a subset of the
       operations supported on regular file systems.  This list details the
       supported operations and the deviations from the standard behavior
       described in the respective man pages.

       All files that support the read(2) operation also support readv(2) and all
       files that support the write(2) operation also support writev(2).  All
       files support the access(2) and stat(2) family of operations, but for the
       latter call, the only fields of the returned stat structure that contain
       reliable information are st_mode, st_nlink, st_uid, and st_gid.

       All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) operations,
       but will not be able to grant permissions that contradict the possible
       operations (e.g., read access on the wbox file).

       The current set of files is:

       /capabilities
              Contains a comma-delimited string representing the capabilities of
              this SPU context.  Possible capabilities are:

              sched  This context may be scheduled.

              step   This context can be run in single-step mode, for debugging.

              New capabilities flags may be added in the future.

       /mem   the contents of the local storage memory of the SPU.  This can be
              accessed like a regular shared memory file and contains both code
              and data in the address space of the SPU.  The possible operations
              on an open mem file are:

              read(2), pread(2), write(2), pwrite(2), lseek(2)
                     These operate as usual, with the exception that lseek(2),
                     write(2), and pwrite(2) are not supported beyond the end of
                     the file.  The file size is the size of the local storage of
                     the SPU, which is normally 256 kilobytes.

              mmap(2)
                     Mapping mem into the process address space provides access to
                     the SPU local storage within the process address space.  Only
                     MAP_SHARED mappings are allowed.

       /regs  Contains the saved general-purpose registers of the SPU context.
              This file contains the 128-bit values of each register, from
              register 0 to register 127, in order.  This allows the general-
              purpose registers to be inspected for debugging.

              Reading to or writing from this file requires that the context is
              scheduled out, so use of this file is not recommended in normal
              program operation.

              The regs file is not present on contexts that have been created with
              the SPU_CREATE_NOSCHED flag.

       /mbox  The first SPU-to-CPU communication mailbox.  This file is read-only
              and can be read in units of 4 bytes.  The file can only be used in
              nonblocking mode - even poll(2) cannot be used to block on this
              file.  The only possible operation on an open mbox file is:

              read(2)
                     If count is smaller than four, read(2) returns -1 and sets
                     errno to EINVAL.  If there is no data available in the
                     mailbox (i.e., the SPU has not sent a mailbox message), the
                     return value is set to -1 and errno is set to EAGAIN.  When
                     data has been read successfully, four bytes are placed in the
                     data buffer and the value four is returned.

       /ibox  The second SPU-to-CPU communication mailbox.  This file is similar
              to the first mailbox file, but can be read in blocking I/O mode,
              thus calling read(2) on an open ibox file will block until the SPU
              has written data to its interrupt mailbox channel (unless the file
              has been opened with O_NONBLOCK, see below).  Also, poll(2) and
              similar system calls can be used to monitor for the presence of
              mailbox data.

              The possible operations on an open ibox file are:

              read(2)
                     If count is smaller than four, read(2) returns -1 and sets
                     errno to EINVAL.  If there is no data available in the
                     mailbox and the file descriptor has been opened with
                     O_NONBLOCK, the return value is set to -1 and errno is set to
                     EAGAIN.

                     If there is no data available in the mailbox and the file
                     descriptor has been opened without O_NONBLOCK, the call will
                     block until the SPU writes to its interrupt mailbox channel.
                     When data has been read successfully, four bytes are placed
                     in the data buffer and the value four is returned.

              poll(2)
                     Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever
                     data is available for reading.

       /wbox  The CPU-to-SPU communication mailbox.  It is write-only and can be
              written in units of four bytes.  If the mailbox is full, write(2)
              will block, and poll(2) can be used to block until the mailbox is
              available for writing again.  The possible operations on an open
              wbox file are:

              write(2)
                     If count is smaller than four, write(2) returns -1 and sets
                     errno to EINVAL.  If there is no space available in the
                     mailbox and the file descriptor has been opened with
                     O_NONBLOCK, the return value is set to -1 and errno is set to
                     EAGAIN.

                     If there is no space available in the mailbox and the file
                     descriptor has been opened without O_NONBLOCK, the call will
                     block until the SPU reads from its PPE (PowerPC Processing
                     Element) mailbox channel.  When data has been written
                     successfully, the system call returns four as its function
                     result.

              poll(2)
                     A poll on the wbox file returns (POLLOUT | POLLWRNORM)
                     whenever space is available for writing.

       /mbox_stat, /ibox_stat, /wbox_stat
              These are read-only files that contain the length of the current
              queue of each mailbox, i.e., how many words can be read from mbox or
              ibox or how many words can be written to wbox without blocking.  The
              files can be read only in four-byte units and return a big-endian
              binary integer number.  The only possible operation on an open
              *box_stat file is:

              read(2)
                     If count is smaller than four, read(2) returns -1 and sets
                     errno to EINVAL.  Otherwise, a four-byte value is placed in
                     the data buffer.  This value is the number of elements that
                     can be read from (for mbox_stat and ibox_stat) or written to
                     (for wbox_stat) the respective mailbox without blocking or
                     returning an EAGAIN error.

       /npc, /decr, /decr_status, /spu_tag_mask, /event_mask, /event_status,
       /srr0, /lslr
              Internal registers of the SPU.  These files contain an ASCII string
              representing the hex value of the specified register.  Reads and
              writes on these files (except for npc, see below) require that the
              SPU context be scheduled out, so frequent access to these files is
              not recommended for normal program operation.

              The contents of these files are:

              npc             Next Program Counter - only valid when the SPU is in
                              a stopped state.

              decr            SPU Decrementer

              decr_status     Decrementer Status

              spu_tag_mask    MFC tag mask for SPU DMA

              event_mask      Event mask for SPU interrupts

              event_status    Number of SPU events pending (read-only)

              srr0            Interrupt Return address register

              lslr            Local Store Limit Register

              The possible operations on these files are:

              read(2)
                     Reads the current register value.  If the register value is
                     larger than the buffer passed to the read(2) system call,
                     subsequent reads will continue reading from the same buffer,
                     until the end of the buffer is reached.

                     When a complete string has been read, all subsequent read
                     operations will return zero bytes and a new file descriptor
                     needs to be opened to read a new value.

              write(2)
                     A write(2) operation on the file sets the register to the
                     value given in the string.  The string is parsed from the
                     beginning until the first nonnumeric character or the end of
                     the buffer.  Subsequent writes to the same file descriptor
                     overwrite the previous setting.

                     Except for the npc file, these files are not present on
                     contexts that have been created with the SPU_CREATE_NOSCHED
                     flag.

       /fpcr  This file provides access to the Floating Point Status and Control
              Register (fcpr) as a binary, four-byte file.  The operations on the
              fpcr file are:

              read(2)
                     If count is smaller than four, read(2) returns -1 and sets
                     errno to EINVAL.  Otherwise, a four-byte value is placed in
                     the data buffer; this is the current value of the fpcr
                     register.

              write(2)
                     If count is smaller than four, write(2) returns -1 and sets
                     errno to EINVAL.  Otherwise, a four-byte value is copied from
                     the data buffer, updating the value of the fpcr register.

       /signal1, /signal2
              The files provide access to the two signal notification channels of
              an SPU.  These are read-write files that operate on four-byte words.
              Writing to one of these files triggers an interrupt on the SPU.  The
              value written to the signal files can be read from the SPU through a
              channel read or from host user space through the file.  After the
              value has been read by the SPU, it is reset to zero.  The possible
              operations on an open signal1 or signal2 file are:

              read(2)
                     If count is smaller than four, read(2) returns -1 and sets
                     errno to EINVAL.  Otherwise, a four-byte value is placed in
                     the data buffer; this is the current value of the specified
                     signal notification register.

              write(2)
                     If count is smaller than four, write(2) returns -1 and sets
                     errno to EINVAL.  Otherwise, a four-byte value is copied from
                     the data buffer, updating the value of the specified signal
                     notification register.  The signal notification register will
                     either be replaced with the input data or will be updated to
                     the bitwise OR operation of the old value and the input data,
                     depending on the contents of the signal1_type or signal2_type
                     files respectively.

       /signal1_type, /signal2_type
              These two files change the behavior of the signal1 and signal2
              notification files.  They contain a numeric ASCII string which is
              read as either "1" or "0".  In mode 0 (overwrite), the hardware
              replaces the contents of the signal channel with the data that is
              written to it.  In mode 1 (logical OR), the hardware accumulates the
              bits that are subsequently written to it.  The possible operations
              on an open signal1_type or signal2_type file are:

              read(2)
                     When the count supplied to the read(2) call is shorter than
                     the required length for the digit (plus a newline character),
                     subsequent reads from the same file descriptor will complete
                     the string.  When a complete string has been read, all
                     subsequent read operations will return zero bytes and a new
                     file descriptor needs to be opened to read the value again.

              write(2)
                     A write(2) operation on the file sets the register to the
                     value given in the string.  The string is parsed from the
                     beginning until the first nonnumeric character or the end of
                     the buffer.  Subsequent writes to the same file descriptor
                     overwrite the previous setting.

       /mbox_info, /ibox_info, /wbox_info, /dma_into, /proxydma_info
              Read-only files that contain the saved state of the SPU mailboxes
              and DMA queues.  This allows the SPU status to be inspected, mainly
              for debugging.  The mbox_info and ibox_info files each contain the
              four-byte mailbox message that has been written by the SPU.  If no
              message has been written to these mailboxes, then contents of these
              files is undefined.  The mbox_stat, ibox_stat and wbox_stat files
              contain the available message count.

              The wbox_info file contains an array of four-byte mailbox messages,
              which have been sent to the SPU.  With current CBEA machines, the
              array is four items in length, so up to 4 * 4 = 16 bytes can be read
              from this file.  If any mailbox queue entry is empty, then the bytes
              read at the corresponding location are undefined.

              The dma_info file contains the contents of the SPU MFC DMA queue,
              represented as the following structure:

                  struct spu_dma_info {
                      uint64_t         dma_info_type;
                      uint64_t         dma_info_mask;
                      uint64_t         dma_info_status;
                      uint64_t         dma_info_stall_and_notify;
                      uint64_t         dma_info_atomic_command_status;
                      struct mfc_cq_sr dma_info_command_data[16];
                  };

              The last member of this data structure is the actual DMA queue,
              containing 16 entries.  The mfc_cq_sr structure is defined as:

                  struct mfc_cq_sr {
                      uint64_t mfc_cq_data0_RW;
                      uint64_t mfc_cq_data1_RW;
                      uint64_t mfc_cq_data2_RW;
                      uint64_t mfc_cq_data3_RW;
                  };

              The proxydma_info file contains similar information, but describes
              the proxy DMA queue (i.e., DMAs initiated by entities outside the
              SPU) instead.  The file is in the following format:

                  struct spu_proxydma_info {
                      uint64_t         proxydma_info_type;
                      uint64_t         proxydma_info_mask;
                      uint64_t         proxydma_info_status;
                      struct mfc_cq_sr proxydma_info_command_data[8];
                  };

              Accessing these files requires that the SPU context is scheduled out
              - frequent use can be inefficient.  These files should not be used
              for normal program operation.

              These files are not present on contexts that have been created with
              the SPU_CREATE_NOSCHED flag.

       /cntl  This file provides access to the SPU Run Control and SPU status
              registers, as an ASCII string.  The following operations are
              supported:

              read(2)
                     Reads from the cntl file will return an ASCII string with the
                     hex value of the SPU Status register.

              write(2)
                     Writes to the cntl file will set the context's SPU Run
                     Control register.

       /mfc   Provides access to the Memory Flow Controller of the SPU.  Reading
              from the file returns the contents of the SPU's MFC Tag Status
              register, and writing to the file initiates a DMA from the MFC.  The
              following operations are supported:

              write(2)
                     Writes to this file need to be in the format of a MFC DMA
                     command, defined as follows:

                         struct mfc_dma_command {
                             int32_t  pad;    /* reserved */
                             uint32_t lsa;    /* local storage address */
                             uint64_t ea;     /* effective address */
                             uint16_t size;   /* transfer size */
                             uint16_t tag;    /* command tag */
                             uint16_t class;  /* class ID */
                             uint16_t cmd;    /* command opcode */
                         };

                     Writes are required to be exactly sizeof(struct
                     mfc_dma_command) bytes in size.  The command will be sent to
                     the SPU's MFC proxy queue, and the tag stored in the kernel
                     (see below).

              read(2)
                     Reads the contents of the tag status register.  If the file
                     is opened in blocking mode (i.e., without O_NONBLOCK), then
                     the read will block until a DMA tag (as performed by a
                     previous write) is complete.  In nonblocking mode, the MFC
                     tag status register will be returned without waiting.

              poll(2)
                     Calling poll(2) on the mfc file will block until a new DMA
                     can be started (by checking for POLLOUT) or until a
                     previously started DMA (by checking for POLLIN) has been
                     completed.

                     /mss Provides access to the MFC MultiSource Synchronization
                     (MSS) facility.  By mmap(2)-ing this file, processes can
                     access the MSS area of the SPU.

                     The following operations are supported:

              mmap(2)
                     Mapping mss into the process address space gives access to
                     the SPU MSS area within the process address space.  Only
                     MAP_SHARED mappings are allowed.

       /psmap Provides access to the whole problem-state mapping of the SPU.
              Applications can use this area to interface to the SPU, rather than
              writing to individual register files in spufs.

              The following operations are supported:

              mmap(2)
                     Mapping psmap gives a process a direct map of the SPU problem
                     state area.  Only MAP_SHARED mappings are supported.

       /phys-id
              Read-only file containing the physical SPU number that the SPU
              context is running on.  When the context is not running, this file
              contains the string "-1".

              The physical SPU number is given by an ASCII hex string.

       /object-id
              Allows applications to store (or retrieve) a single 64-bit ID into
              the context.  This ID is later used by profiling tools to uniquely
              identify the context.

              write(2)
                     By writing an ASCII hex value into this file, applications
                     can set the object ID of the SPU context.  Any previous value
                     of the object ID is overwritten.

              read(2)
                     Reading this file gives an ASCII hex string representing the
                     object ID for this SPU context.

EXAMPLE top

       /etc/fstab  entry
              none      /spu      spufs     gid=spu   0    0

SEE ALSO top

       close(2), spu_create(2), spu_run(2), capabilities(7)

       The Cell Broadband Engine Architecture (CBEA) specification

COLOPHON top

       This page is part of release 3.45 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-12-20                            SPUFS(7)


spu_create(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | FILES | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SPU_CREATE(2)                Linux Programmer's Manual               SPU_CREATE(2)

NAME top

       spu_create - create a new spu context

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/spu.h>

       int spu_create(const char *pathname, int flags, mode_t mode);
       int spu_create(const char *pathname, int flags, mode_t mode,
                      int neighbor_fd);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The spu_create() system call is used on PowerPC machines that implement the
       Cell Broadband Engine Architecture in order to access Synergistic Processor
       Units (SPUs).  It creates a new logical context for an SPU in pathname and
       returns a file descriptor associated with it.  pathname must refer to a
       nonexistent directory in the mount point of the SPU file system (spufs).
       If spu_create() is successful, a directory is created at pathname and it is
       populated with the files described in spufs(7).

       When a context is created, the returned file descriptor can only be passed
       to spu_run(2), used as the dirfd argument to the *at family of system calls
       (e.g., openat(2)), or closed; other operations are not defined.  A logical
       SPU context is destroyed (along with all files created within the context's
       pathname directory) once the last reference to the context has gone; this
       usually occurs when the file descriptor returned by spu_create() is closed.

       The flags argument can be zero or any bitwise OR-ed combination of the
       following constants:

       SPU_CREATE_EVENTS_ENABLED
              Rather than using signals for reporting DMA errors, use the event
              argument to spu_run(2).

       SPU_CREATE_GANG
              Create an SPU gang instead of a context.  (A gang is a group of SPU
              contexts that are functionally related to each other and which share
              common scheduling parameters--priority and policy.  In the future,
              gang scheduling may be implemented causing the group to be switched
              in and out as a single unit.)

              A new directory will be created at the location specified by the
              pathname argument.  This gang may be used to hold other SPU
              contexts, by providing a pathname that is within the gang directory
              to further calls to spu_create().

       SPU_CREATE_NOSCHED
              Create a context that is not affected by the SPU scheduler.  Once
              the context is run, it will not be scheduled out until it is
              destroyed by the creating process.

              Because the context cannot be removed from the SPU, some
              functionality is disabled for SPU_CREATE_NOSCHED contexts.  Only a
              subset of the files will be available in this context directory in
              spufs.  Additionally, SPU_CREATE_NOSCHED contexts cannot dump a core
              file when crashing.

              Creating SPU_CREATE_NOSCHED contexts requires the CAP_SYS_NICE
              capability.

       SPU_CREATE_ISOLATE
              Create an isolated SPU context.  Isolated contexts are protected
              from some PPE (PowerPC Processing Element) operations, such as
              access to the SPU local store and the NPC register.

              Creating SPU_CREATE_ISOLATE contexts also requires the
              SPU_CREATE_NOSCHED flag.

       SPU_CREATE_AFFINITY_SPU
              Create a context with affinity to another SPU context.  This
              affinity information is used within the SPU scheduling algorithm.
              Using this flag requires that a file descriptor referring to the
              other SPU context be passed in the neighbor_fd argument.

       SPU_CREATE_AFFINITY_MEM
              Create a context with affinity to system memory.  This affinity
              information is used within the SPU scheduling algorithm.

       The mode argument (minus any bits set in the process's umask(2)) specifies
       the permissions used for creating the new directory in spufs.  See stat(2)
       for a full list of the possible mode values.

RETURN VALUE top

       On success, spu_create() returns a new file descriptor.  On error, -1 is
       returned, and errno is set to one of the error codes listed below.

ERRORS top

       EACCES The current user does not have write access to the spufs(7) mount
              point.

       EEXIST An SPU context already exists at the given path name.

       EFAULT pathname is not a valid string pointer in the calling process's
              address space.

       EINVAL pathname is not a directory in the spufs(7) mount point, or invalid
              flags have been provided.

       ELOOP  Too many symbolic links were found while resolving pathname.

       EMFILE The process has reached its maximum open files limit.

       ENAMETOOLONG
              pathname is too long.

       ENFILE The system has reached the global open files limit.

       ENODEV An isolated context was requested, but the hardware does not support
              SPU isolation.

       ENOENT Part of pathname could not be resolved.

       ENOMEM The kernel could not allocate all resources required.

       ENOSPC There are not enough SPU resources available to create a new context
              or the user-specific limit for the number of SPU contexts has been
              reached.

       ENOSYS The functionality is not provided by the current system, because
              either the hardware does not provide SPUs or the spufs module is not
              loaded.

       ENOTDIR
              A part of pathname is not a directory.

       EPERM  The SPU_CREATE_NOSCHED flag has been given, but the user does not
              have the CAP_SYS_NICE capability.

FILES top

       pathname must point to a location beneath the mount point of spufs.  By
       convention, it gets mounted in /spu.

VERSIONS top

       The spu_create() system call was added to Linux in kernel 2.6.16.

CONFORMING TO top

       This call is Linux-specific and only implemented on the PowerPC
       architecture.  Programs using this system call are not portable.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).  Note however, that spu_create() is meant to be used from
       libraries that implement a more abstract interface to SPUs, not to be used
       from regular applications.  See <http://www.bsc.es/projects/deepcomputing
       /linuxoncell/> for the recommended libraries.

EXAMPLE top

       See spu_run(2) for an example of the use of spu_create()

SEE ALSO top

       close(2), spu_run(2), capabilities(7), spufs(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                       SPU_CREATE(2)


spu_run(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SPU_RUN(2)                   Linux Programmer's Manual                  SPU_RUN(2)

NAME top

       spu_run - execute an SPU context

SYNOPSIS top

       #include <sys/spu.h>

       int spu_run(int fd, unsigned int *npc, unsigned int *event);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The spu_run() system call is used on PowerPC machines that implement the
       Cell Broadband Engine Architecture in order to access Synergistic Processor
       Units (SPUs).  The fd argument is a file descriptor returned by
       spu_create(2) that refers to a specific SPU context.  When the context gets
       scheduled to a physical SPU, it starts execution at the instruction pointer
       passed in npc.

       Execution of SPU code happens synchronously, meaning that spu_run() blocks
       while the SPU is still running.  If there is a need to execute SPU code in
       parallel with other code on either the main CPU or other SPUs, a new thread
       of execution must be created first (e.g., using pthread_create(3)).

       When spu_run() returns, the current value of the SPU program counter is
       written to npc, so successive calls to spu_run() can use the same npc
       pointer.

       The event argument provides a buffer for an extended status code.  If the
       SPU context was created with the SPU_CREATE_EVENTS_ENABLED flag, then this
       buffer is populated by the Linux kernel before spu_run() returns.

       The status code may be one (or more) of the following constants:

       SPE_EVENT_DMA_ALIGNMENT
              A DMA alignment error occurred.

       SPE_EVENT_INVALID_DMA
              An invalid MFC DMA command was attempted.

       SPE_EVENT_SPE_DATA_STORAGE
              A DMA storage error occurred.

       SPE_EVENT_SPE_ERROR
              An illegal instruction was executed.

       NULL is a valid value for the event argument.  In this case, the events
       will not be reported to the calling process.

RETURN VALUE top

       On success, spu_run() returns the value of the spu_status register.  On
       error it returns -1 and sets errno to one of the error codes listed below.

       The spu_status register value is a bit mask of status codes and optionally
       a 14-bit code returned from the stop-and-signal instruction on the SPU.
       The bit masks for the status codes are:

       0x02   SPU was stopped by a stop-and-signal instruction.

       0x04   SPU was stopped by a halt instruction.

       0x08   SPU is waiting for a channel.

       0x10   SPU is in single-step mode.

       0x20   SPU has tried to execute an invalid instruction.

       0x40   SPU has tried to access an invalid channel.

       0x3fff0000
              The bits masked with this value contain the code returned from a
              stop-and-signal instruction.  These bits are only valid if the 0x02
              bit is set.

       If spu_run() has not returned an error, one or more bits among the lower
       eight ones are always set.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       EFAULT npc is not a valid pointer, or event is non-NULL and an invalid
              pointer.

       EINTR  A signal occurred while spu_run() was in progress; see signal(7).
              The npc value has been updated to the new program counter value if
              necessary.

       EINVAL fd is not a valid file descriptor returned from spu_create(2).

       ENOMEM There was not enough memory available to handle a page fault
              resulting from a Memory Flow Controller (MFC) direct memory access.

       ENOSYS The functionality is not provided by the current system, because
              either the hardware does not provide SPUs or the spufs module is not
              loaded.

VERSIONS top

       The spu_run() system call was added to Linux in kernel 2.6.16.

CONFORMING TO top

       This call is Linux-specific and only implemented by the PowerPC
       architecture.  Programs using this system call are not portable.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).  Note however, that spu_run() is meant to be used from
       libraries that implement a more abstract interface to SPUs, not to be used
       from regular applications.  See <http://www.bsc.es/projects/deepcomputing
       /linuxoncell/> for the recommended libraries.

EXAMPLE top

       The following is an example of running a simple, one-instruction SPU pro-
       gram with the spu_run() system call.

       #include <stdlib.h>
       #include <stdint.h>
       #include <unistd.h>
       #include <stdio.h>
       #include <sys/types.h>
       #include <fcntl.h>

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

       int main(void)
       {
           int context, fd, spu_status;
           uint32_t instruction, npc;

           context = spu_create("/spu/example-context", 0, 0755);
           if (context == -1)
               handle_error("spu_create");

           /* write a 'stop 0x1234' instruction to the SPU's
            * local store memory
            */
           instruction = 0x00001234;

           fd = open("/spu/example-context/mem", O_RDWR);
           if (fd == -1)
               handle_error("open");
           write(fd, &instruction, sizeof(instruction));

           /* set npc to the starting instruction address of the
            * SPU program. Since we wrote the instruction at the
            * start of the mem file, the entry point will be 0x0
            */
           npc = 0;

           spu_status = spu_run(context, &npc, NULL);
           if (spu_status == -1)
               handle_error("open");

           /* we should see a status code of 0x1234002:
            *   0x00000002 (spu was stopped due to stop-and-signal)
            * | 0x12340000 (the stop-and-signal code)
            */
           printf("SPU Status: 0x%08x\n", spu_status);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       close(2), spu_create(2), capabilities(7), spufs(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                          SPU_RUN(2)


sqrt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SQRT(3)                      Linux Programmer's Manual                     SQRT(3)

NAME top

       sqrt, sqrtf, sqrtl - square root function

SYNOPSIS top

       #include <math.h>

       double sqrt(double x);
       float sqrtf(float x);
       long double sqrtl(long double x);

       Link with -lm.

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

       sqrtf(), sqrtl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The sqrt() function returns the nonnegative square root of x.

RETURN VALUE top

       On success, these functions return the square root of x.

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity, positive infinity is returned.

       If x is less than -0, a domain error occurs, and a NaN is returned.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x less than -0
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       cbrt(3), csqrt(3), hypot(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             SQRT(3)


st(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ST(4)                        Linux Programmer's Manual                       ST(4)

NAME top

       st - SCSI tape device

SYNOPSIS top

       #include <sys/mtio.h>

       int ioctl(int fd, int request [, (void *)arg3]);
       int ioctl(int fd, MTIOCTOP, (struct mtop *)mt_cmd);
       int ioctl(int fd, MTIOCGET, (struct mtget *)mt_status);
       int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt_pos);

DESCRIPTION top

       The st driver provides the interface to a variety of SCSI tape devices.
       Currently, the driver takes control of all detected devices of type
       "sequential-access".  The st driver uses major device number 9.

       Each device uses eight minor device numbers.  The lowermost five bits in
       the minor numbers are assigned sequentially in the order of detection.  In
       the 2.6 kernel, the bits above the eight lowermost bits are concatenated to
       the five lowermost bits to form the tape number.  The minor numbers can be
       grouped into two sets of four numbers: the principal (auto-rewind) minor
       device numbers, n, and the "no-rewind" device numbers, (n + 128).  Devices
       opened using the principal device number will be sent a REWIND command when
       they are closed.  Devices opened using the "no-rewind" device number will
       not.  (Note that using an auto-rewind device for positioning the tape with,
       for instance, mt does not lead to the desired result: the tape is rewound
       after the mt command and the next command starts from the beginning of the
       tape).

       Within each group, four minor numbers are available to define devices with
       different characteristics (block size, compression, density, etc.)  When
       the system starts up, only the first device is available.  The other three
       are activated when the default characteristics are defined (see below).
       (By changing compile-time constants, it is possible to change the balance
       between the maximum number of tape drives and the number of minor numbers
       for each drive.  The default allocation allows control of 32 tape drives.
       For instance, it is possible to control up to 64 tape drives with two minor
       numbers for different options.)

       Devices are typically created by:

           mknod -m 666 /dev/st0 c 9 0
           mknod -m 666 /dev/st0l c 9 32
           mknod -m 666 /dev/st0m c 9 64
           mknod -m 666 /dev/st0a c 9 96
           mknod -m 666 /dev/nst0 c 9 128
           mknod -m 666 /dev/nst0l c 9 160
           mknod -m 666 /dev/nst0m c 9 192
           mknod -m 666 /dev/nst0a c 9 224

       There is no corresponding block device.

       The driver uses an internal buffer that has to be large enough to hold at
       least one tape block.  In kernels before 2.1.121, the buffer is allocated
       as one contiguous block.  This limits the block size to the largest
       contiguous block of memory the kernel allocator can provide.  The limit is
       currently 128 kB for 32-bit architectures and 256 kB for 64-bit
       architectures.  In newer kernels the driver allocates the buffer in several
       parts if necessary.  By default, the maximum number of parts is 16.  This
       means that the maximum block size is very large (2 MB if allocation of 16
       blocks of 128 kB succeeds).

       The driver's internal buffer size is determined by a compile-time constant
       which can be overridden with a kernel startup option.  In addition to this,
       the driver tries to allocate a larger temporary buffer at run time if
       necessary.  However, run-time allocation of large contiguous blocks of
       memory may fail and it is advisable not to rely too much on dynamic buffer
       allocation with kernels older than 2.1.121 (this applies also to demand-
       loading the driver with kerneld or kmod).

       The driver does not specifically support any tape drive brand or model.
       After system start-up the tape device options are defined by the drive
       firmware.  For example, if the drive firmware selects fixed-block mode, the
       tape device uses fixed-block mode.  The options can be changed with
       explicit ioctl(2) calls and remain in effect when the device is closed and
       reopened.  Setting the options affects both the auto-rewind and the
       nonrewind device.

       Different options can be specified for the different devices within the
       subgroup of four.  The options take effect when the device is opened.  For
       example, the system administrator can define one device that writes in
       fixed-block mode with a certain block size, and one which writes in
       variable-block mode (if the drive supports both modes).

       The driver supports tape partitions if they are supported by the drive.
       (Note that the tape partitions have nothing to do with disk partitions.  A
       partitioned tape can be seen as several logical tapes within one medium.)
       Partition support has to be enabled with an ioctl(2).  The tape location is
       preserved within each partition across partition changes.  The partition
       used for subsequent tape operations is selected with an ioctl(2).  The
       partition switch is executed together with the next tape operation in order
       to avoid unnecessary tape movement.  The maximum number of partitions on a
       tape is defined by a compile-time constant (originally four).  The driver
       contains an ioctl(2) that can format a tape with either one or two
       partitions.

       Device /dev/tape is usually created as a hard or soft link to the default
       tape device on the system.

       Starting from kernel 2.6.2, the driver exports in the sysfs directory
       /sys/class/scsi_tape the attached devices and some parameters assigned to
       the devices.

Data Transfer

       The driver supports operation in both fixed-block mode and variable-block
       mode (if supported by the drive).  In fixed-block mode the drive writes
       blocks of the specified size and the block size is not dependent on the
       byte counts of the write system calls.  In variable-block mode one tape
       block is written for each write call and the byte count determines the size
       of the corresponding tape block.  Note that the blocks on the tape don't
       contain any information about the writing mode: when reading, the only
       important thing is to use commands that accept the block sizes on the tape.

       In variable-block mode the read byte count does not have to match the tape
       block size exactly.  If the byte count is larger than the next block on
       tape, the driver returns the data and the function returns the actual block
       size.  If the block size is larger than the byte count, the requested
       amount of data from the start of the block is returned and the rest of the
       block is discarded.

       In fixed-block mode the read byte counts can be arbitrary if buffering is
       enabled, or a multiple of the tape block size if buffering is disabled.
       Kernels before 2.1.121 allow writes with arbitrary byte count if buffering
       is enabled.  In all other cases (kernel before 2.1.121 with buffering
       disabled or newer kernel) the write byte count must be a multiple of the
       tape block size.

       In the 2.6 kernel, the driver tries to use direct transfers between the
       user buffer and the device.  If this is not possible, the driver's internal
       buffer is used.  The reasons for not using direct transfers include
       improper alignment of the user buffer (default is 512 bytes but this can be
       changed by the HBA driver), one of more pages of the user buffer not
       reachable by the SCSI adapter, etc.

       A filemark is automatically written to tape if the last tape operation
       before close was a write.

       When a filemark is encountered while reading, the following happens.  If
       there are data remaining in the buffer when the filemark is found, the
       buffered data is returned.  The next read returns zero bytes.  The
       following read returns data from the next file.  The end of recorded data
       is signaled by returning zero bytes for two consecutive read calls.  The
       third read returns an error.

Ioctls

       The driver supports three ioctl(2) requests.  Requests not recognized by
       the st driver are passed to the SCSI driver.  The definitions below are
       from /usr/include/linux/mtio.h:

MTIOCTOP -- Perform a tape operation

       This request takes an argument of type (struct mtop *).  Not all drives
       support all operations.  The driver returns an EIO error if the drive
       rejects an operation.

           /* Structure for MTIOCTOP - mag tape op command: */
           struct mtop {
               short   mt_op;       /* operations defined below */
               int     mt_count;    /* how many of them */
           };

       Magnetic Tape operations for normal tape use:

       MTBSF         Backward space over mt_count filemarks.

       MTBSFM        Backward space over mt_count filemarks.  Reposition the tape
                     to the EOT side of the last filemark.

       MTBSR         Backward space over mt_count records (tape blocks).

       MTBSS         Backward space over mt_count setmarks.

       MTCOMPRESSION Enable compression of tape data within the drive if mt_count
                     is nonzero and disable compression if mt_count is zero.  This
                     command uses the MODE page 15 supported by most DATs.

       MTEOM         Go to the end of the recorded media (for appending files).

       MTERASE       Erase tape.  With 2.6 kernel, short erase (mark tape empty)
                     is performed if the argument is zero.  Otherwise long erase
                     (erase all) is done.

       MTFSF         Forward space over mt_count filemarks.

       MTFSFM        Forward space over mt_count filemarks.  Reposition the tape
                     to the BOT side of the last filemark.

       MTFSR         Forward space over mt_count records (tape blocks).

       MTFSS         Forward space over mt_count setmarks.

       MTLOAD        Execute the SCSI load command.  A special case is available
                     for some HP autoloaders.  If mt_count is the constant
                     MT_ST_HPLOADER_OFFSET plus a number, the number is sent to
                     the drive to control the autoloader.

       MTLOCK        Lock the tape drive door.

       MTMKPART      Format the tape into one or two partitions.  If mt_count is
                     nonzero, it gives the size of the first partition and the
                     second partition contains the rest of the tape.  If mt_count
                     is zero, the tape is formatted into one partition.  This
                     command is not allowed for a drive unless the partition
                     support is enabled for the drive (see MT_ST_CAN_PARTITIONS
                     below).

       MTNOP         No op--flushes the driver's buffer as a side effect.  Should
                     be used before reading status with MTIOCGET.

       MTOFFL        Rewind and put the drive off line.

       MTRESET       Reset drive.

       MTRETEN       Re-tension tape.

       MTREW         Rewind.

       MTSEEK        Seek to the tape block number specified in mt_count.  This
                     operation requires either a SCSI-2 drive that supports the
                     LOCATE command (device-specific address) or a Tandberg-
                     compatible SCSI-1 drive (Tandberg, Archive Viper, Wangtek,
                     ...).  The block number should be one that was previously
                     returned by MTIOCPOS if device-specific addresses are used.

       MTSETBLK      Set the drive's block length to the value specified in
                     mt_count.  A block length of zero sets the drive to variable
                     block size mode.

       MTSETDENSITY  Set the tape density to the code in mt_count.  The density
                     codes supported by a drive can be found from the drive
                     documentation.

       MTSETPART     The active partition is switched to mt_count.  The partitions
                     are numbered from zero.  This command is not allowed for a
                     drive unless the partition support is enabled for the drive
                     (see MT_ST_CAN_PARTITIONS below).

       MTUNLOAD      Execute the SCSI unload command (does not eject the tape).

       MTUNLOCK      Unlock the tape drive door.

       MTWEOF        Write mt_count filemarks.

       MTWSM         Write mt_count setmarks.

       Magnetic Tape operations for setting of device options (by the superuser):

       MTSETDRVBUFFER
               Set various drive and driver options according to bits encoded in
               mt_count.  These consist of the drive's buffering mode, a set of
               Boolean driver options, the buffer write threshold, defaults for
               the block size and density, and timeouts (only in kernels 2.1 and
               later).  A single operation can affect only one item in the list
               above (the Booleans counted as one item.)

               A value having zeros in the high-order 4 bits will be used to set
               the drive's buffering mode.  The buffering modes are:

                   0   The drive will not report GOOD status on write commands
                       until the data blocks are actually written to the medium.

                   1   The drive may report GOOD status on write commands as soon
                       as all the data has been transferred to the drive's
                       internal buffer.

                   2   The drive may report GOOD status on write commands as soon
                       as (a) all the data has been transferred to the drive's
                       internal buffer, and (b) all buffered data from different
                       initiators has been successfully written to the medium.

               To control the write threshold the value in mt_count must include
               the constant MT_ST_WRITE_THRESHOLD bitwise ORed with a block count
               in the low 28 bits.  The block count refers to 1024-byte blocks,
               not the physical block size on the tape.  The threshold cannot
               exceed the driver's internal buffer size (see DESCRIPTION, above).

               To set and clear the Boolean options the value in mt_count must
               include one of the constants MT_ST_BOOLEANS, MT_ST_SETBOOLEANS,
               MT_ST_CLEARBOOLEANS, or MT_ST_DEFBOOLEANS bitwise ORed with
               whatever combination of the following options is desired.  Using
               MT_ST_BOOLEANS the options can be set to the values defined in the
               corresponding bits.  With MT_ST_SETBOOLEANS the options can be
               selectively set and with MT_ST_DEFBOOLEANS selectively cleared.

               The default options for a tape device are set with
               MT_ST_DEFBOOLEANS.  A nonactive tape device (e.g., device with
               minor 32 or 160) is activated when the default options for it are
               defined the first time.  An activated device inherits from the
               device activated at start-up the options not set explicitly.

               The Boolean options are:

               MT_ST_BUFFER_WRITES (Default: true)
                      Buffer all write operations in fixed-block mode.  If this
                      option is false and the drive uses a fixed block size, then
                      all write operations must be for a multiple of the block
                      size.  This option must be set false to write reliable
                      multivolume archives.

               MT_ST_ASYNC_WRITES (Default: true)
                      When this option is true, write operations
                      return immediately without waiting for the
                      data to be transferred to the drive if the
                      data fits into the driver's buffer.  The
                      write threshold determines how full the
                      buffer must be before a new SCSI write
                      command is issued.  Any errors reported by
                      the drive will be held until the next
                      operation.  This option must be set false to
                      write reliable multivolume archives.

               MT_ST_READ_AHEAD (Default: true)
                      This option causes the driver to provide read
                      buffering and read-ahead in fixed-block mode.
                      If this option is false and the drive uses a
                      fixed block size, then all read operations
                      must be for a multiple of the block size.

               MT_ST_TWO_FM (Default: false)
                      This option modifies the driver behavior when
                      a file is closed.  The normal action is to
                      write a single filemark.  If the option is
                      true the driver will write two filemarks and
                      backspace over the second one.

                      Note: This option should not be set true for
                      QIC tape drives since they are unable to
                      overwrite a filemark.  These drives detect
                      the end of recorded data by testing for blank
                      tape rather than two consecutive filemarks.
                      Most other current drives also detect the end
                      of recorded data and using two filemarks is
                      usually necessary only when interchanging
                      tapes with some other systems.

               MT_ST_DEBUGGING (Default: false)
                      This option turns on various debugging
                      messages from the driver (effective only if
                      the driver was compiled with DEBUG defined
                      nonzero).

               MT_ST_FAST_EOM (Default: false)
                      This option causes the MTEOM operation to be
                      sent directly to the drive, potentially
                      speeding up the operation but causing the
                      driver to lose track of the current file
                      number normally returned by the MTIOCGET
                      request.  If MT_ST_FAST_EOM is false the
                      driver will respond to an MTEOM request by
                      forward spacing over files.

               MT_ST_AUTO_LOCK (Default: false)
                      When this option is true, the drive door is
                      locked when the device is opened and unlocked
                      when it is closed.

               MT_ST_DEF_WRITES (Default: false)
                      The tape options (block size, mode,
                      compression, etc.) may change when changing
                      from one device linked to a drive to another
                      device linked to the same drive depending on
                      how the devices are defined.  This option
                      defines when the changes are enforced by the
                      driver using SCSI-commands and when the
                      drives auto-detection capabilities are relied
                      upon.  If this option is false, the driver
                      sends the SCSI-commands immediately when the
                      device is changed.  If the option is true,
                      the SCSI-commands are not sent until a write
                      is requested.  In this case the drive
                      firmware is allowed to detect the tape
                      structure when reading and the SCSI-commands
                      are used only to make sure that a tape is
                      written according to the correct
                      specification.

               MT_ST_CAN_BSR (Default: false)
                      When read-ahead is used, the tape must
                      sometimes be spaced backward to the correct
                      position when the device is closed and the
                      SCSI command to space backward over records
                      is used for this purpose.  Some older drives
                      can't process this command reliably and this
                      option can be used to instruct the driver not
                      to use the command.  The end result is that,
                      with read-ahead and fixed-block mode, the
                      tape may not be correctly positioned within a
                      file when the device is closed.  With 2.6
                      kernel, the default is true for drives
                      supporting SCSI-3.

               MT_ST_NO_BLKLIMS (Default: false)
                      Some drives don't accept the READ BLOCK
                      LIMITS SCSI command.  If this is used, the
                      driver does not use the command.  The
                      drawback is that the driver can't check
                      before sending commands if the selected block
                      size is acceptable to the drive.

               MT_ST_CAN_PARTITIONS (Default: false)
                      This option enables support for several
                      partitions within a tape.  The option applies
                      to all devices linked to a drive.

               MT_ST_SCSI2LOGICAL (Default: false)
                      This option instructs the driver to use the
                      logical block addresses defined in the SCSI-2
                      standard when performing the seek and tell
                      operations (both with MTSEEK and MTIOCPOS
                      commands and when changing tape partition).
                      Otherwise the device-specific addresses are
                      used.  It is highly advisable to set this
                      option if the drive supports the logical
                      addresses because they count also filemarks.
                      There are some drives that only support the
                      logical block addresses.

               MT_ST_SYSV (Default: false)
                      When this option is enabled, the tape devices
                      use the SystemV semantics.  Otherwise the BSD
                      semantics are used.  The most important
                      difference between the semantics is what
                      happens when a device used for reading is
                      closed: in System V semantics the tape is
                      spaced forward past the next filemark if this
                      has not happened while using the device.  In
                      BSD semantics the tape position is not
                      changed.

               MT_NO_WAIT (Default: false)
                      Enables immediate mode (i.e., don't wait for
                      the command to finish) for some commands
                      (e.g., rewind).

               An example:

                   struct mtop mt_cmd;
                   mt_cmd.mt_op = MTSETDRVBUFFER;
                   mt_cmd.mt_count = MT_ST_BOOLEANS |
                           MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES;
                   ioctl(fd, MTIOCTOP, mt_cmd);

               The default block size for a device can be set with
               MT_ST_DEF_BLKSIZE and the default density code can
               be set with MT_ST_DEFDENSITY.  The values for the
               parameters are or'ed with the operation code.

               With kernels 2.1.x and later, the timeout values can
               be set with the subcommand MT_ST_SET_TIMEOUT ORed
               with the timeout in seconds.  The long timeout (used
               for rewinds and other commands that may take a long
               time) can be set with MT_ST_SET_LONG_TIMEOUT.  The
               kernel defaults are very long to make sure that a
               successful command is not timed out with any drive.
               Because of this the driver may seem stuck even if it
               is only waiting for the timeout.  These commands can
               be used to set more practical values for a specific
               drive.  The timeouts set for one device apply for
               all devices linked to the same drive.

               Starting from kernels 2.4.19 and 2.5.43, the driver
               supports a status bit which indicates whether the
               drive requests cleaning.  The method used by the
               drive to return cleaning information is set using
               the MT_ST_SEL_CLN subcommand.  If the value is zero,
               the cleaning bit is always zero.  If the value is
               one, the TapeAlert data defined in the SCSI-3
               standard is used (not yet implemented).  Values 2-17
               are reserved.  If the lowest eight bits are >= 18,
               bits from the extended sense data are used.  The
               bits 9-16 specify a mask to select the bits to look
               at and the bits 17-23 specify the bit pattern to
               look for.  If the bit pattern is zero, one or more
               bits under the mask indicate the cleaning request.
               If the pattern is nonzero, the pattern must match
               the masked sense data byte.

MTIOCGET -- Get status

       This request takes an argument of type (struct mtget *).

           /* structure for MTIOCGET - mag tape get status command */
           struct mtget {
               long     mt_type;
               long     mt_resid;
               /* the following registers are device dependent */
               long     mt_dsreg;
               long     mt_gstat;
               long     mt_erreg;
               /* The next two fields are not always used */
               daddr_t  mt_fileno;
               daddr_t  mt_blkno;
           };

       mt_type    The header file defines many values for mt_type,
                  but the current driver reports only the generic
                  types MT_ISSCSI1 (Generic SCSI-1 tape) and
                  MT_ISSCSI2 (Generic SCSI-2 tape).

       mt_resid   contains the current tape partition number.

       mt_dsreg   reports the drive's current settings for block
                  size (in the low 24 bits) and density (in the
                  high 8 bits).  These fields are defined by
                  MT_ST_BLKSIZE_SHIFT, MT_ST_BLKSIZE_MASK,
                  MT_ST_DENSITY_SHIFT, and MT_ST_DENSITY_MASK.

       mt_gstat   reports generic (device independent) status
                  information.  The header file defines macros for
                  testing these status bits:

                  GMT_EOF(x): The tape is positioned just after a
                      filemark (always false after an MTSEEK
                      operation).

                  GMT_BOT(x): The tape is positioned at the
                      beginning of the first file (always false
                      after an MTSEEK operation).

                  GMT_EOT(x): A tape operation has reached the
                      physical End Of Tape.

                  GMT_SM(x): The tape is currently positioned at a
                      setmark (always false after an MTSEEK
                      operation).

                  GMT_EOD(x): The tape is positioned at the end of
                      recorded data.

                  GMT_WR_PROT(x): The drive is write-protected.
                      For some drives this can also mean that the
                      drive does not support writing on the current
                      medium type.

                  GMT_ONLINE(x): The last open(2) found the drive
                      with a tape in place and ready for operation.

                  GMT_D_6250(x), GMT_D_1600(x), GMT_D_800(x): This
                      "generic" status information reports the
                      current density setting for 9-track 1/2" tape
                      drives only.

                  GMT_DR_OPEN(x): The drive does not have a tape in
                      place.

                  GMT_IM_REP_EN(x): Immediate report mode.  This
                      bit is set if there are no guarantees that
                      the data has been physically written to the
                      tape when the write call returns.  It is set
                      zero only when the driver does not buffer
                      data and the drive is set not to buffer data.

                  GMT_CLN(x): The drive has requested cleaning.
                      Implemented in kernels since 2.4.19 and
                      2.5.43.

       mt_erreg   The only field defined in mt_erreg is the
                  recovered error count in the low 16 bits (as
                  defined by MT_ST_SOFTERR_SHIFT and
                  MT_ST_SOFTERR_MASK.  Due to inconsistencies in
                  the way drives report recovered errors, this
                  count is often not maintained (most drives do not
                  by default report soft errors but this can be
                  changed with a SCSI MODE SELECT command).

       mt_fileno  reports the current file number (zero-based).
                  This value is set to -1 when the file number is
                  unknown (e.g., after MTBSS or MTSEEK).

       mt_blkno   reports the block number (zero-based) within the
                  current file.  This value is set to -1 when the
                  block number is unknown (e.g., after MTBSF,
                  MTBSS, or MTSEEK).

MTIOCPOS -- Get tape position

       This request takes an argument of type (struct mtpos *) and
       reports the drive's notion of the current tape block number,
       which is not the same as mt_blkno returned by MTIOCGET.
       This drive must be a SCSI-2 drive that supports the READ
       POSITION command (device-specific address) or a Tandberg-
       compatible SCSI-1 drive (Tandberg, Archive Viper, Wangtek,
       ... ).

           /* structure for MTIOCPOS - mag tape get position command */
           struct mtpos {
               long mt_blkno;    /* current block number */
           };

RETURN VALUE top

       EACCES        An attempt was made to write or erase a
                     write-protected tape.  (This error is
                     not detected during open(2).)

       EBUSY         The device is already in use or the
                     driver was unable to allocate a buffer.

       EFAULT        The command parameters point to memory
                     not belonging to the calling process.

       EINVAL        An ioctl(2) had an invalid argument, or
                     a requested block size was invalid.

       EIO           The requested operation could not be
                     completed.

       ENOMEM        The byte count in read(2) is smaller
                     than the next physical block on the
                     tape.  (Before 2.2.18 and 2.4.0-test6
                     the extra bytes have been silently
                     ignored.)

       ENOSPC        A write operation could not be
                     completed because the tape reached end-
                     of-medium.

       ENOSYS        Unknown ioctl(2).

       ENXIO         During opening, the tape device does
                     not exist.

       EOVERFLOW     An attempt was made to read or write a
                     variable-length block that is larger
                     than the driver's internal buffer.

       EROFS         Open is attempted with O_WRONLY or
                     O_RDWR when the tape in the drive is
                     write-protected.

FILES top

       /dev/st*    the auto-rewind SCSI tape devices

       /dev/nst*   the nonrewind SCSI tape devices

NOTES top

       1.  When exchanging data between systems, both
           systems have to agree on the physical tape block
           size.  The parameters of a drive after startup
           are often not the ones most operating systems use
           with these devices.  Most systems use drives in
           variable-block mode if the drive supports that
           mode.  This applies to most modern drives,
           including DATs, 8mm helical scan drives, DLTs,
           etc.  It may be advisable to use these drives in
           variable-block mode also in Linux (i.e., use
           MTSETBLK or MTSETDEFBLK at system startup to set
           the mode), at least when exchanging data with a
           foreign system.  The drawback of this is that a
           fairly large tape block size has to be used to
           get acceptable data transfer rates on the SCSI
           bus.

       2.  Many programs (e.g., tar(1)) allow the user to
           specify the blocking factor on the command line.
           Note that this determines the physical block size
           on tape only in variable-block mode.

       3.  In order to use SCSI tape drives, the basic SCSI
           driver, a SCSI-adapter driver and the SCSI tape
           driver must be either configured into the kernel
           or loaded as modules.  If the SCSI-tape driver is
           not present, the drive is recognized but the tape
           support described in this page is not available.

       4.  The driver writes error messages to the
           console/log.  The SENSE codes written into some
           messages are automatically translated to text if
           verbose SCSI messages are enabled in kernel
           configuration.

       5.  The driver's internal buffering allows good
           throughput in fixed-block mode also with small
           read(2) and write(2) byte counts.  With direct
           transfers this is not possible and may cause a
           surprise when moving to the 2.6 kernel.  The
           solution is to tell the software to use larger
           transfers (often telling it to use larger
           blocks).  If this is not possible, direct
           transfers can be disabled.

SEE ALSO top

       mt(1)

       The file drivers/scsi/README.st or
       Documentation/scsi/st.txt (kernel >= 2.6) in the
       Linux kernel source tree contains the most recent
       information about the driver and its configuration
       possibilities

COLOPHON top

       This page is part of release 3.45 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                               2010-09-04                               ST(4)


standards(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

STANDARDS(7)                 Linux Programmer's Manual                STANDARDS(7)

NAME top

       standards - C and UNIX Standards

DESCRIPTION top

       The CONFORMING TO section that appears in many manual pages identifies
       various standards to which the documented interface conforms.  The
       following list briefly describes these standards.

       V7     Version 7, the ancestral UNIX from Bell Labs.

       4.2BSD This is an implementation standard defined by the 4.2 release of the
              Berkeley Software Distribution, released by the University of
              California at Berkeley.  This was the first Berkeley release that
              contained a TCP/IP stack and the sockets API.  4.2BSD was released
              in 1983.

              Earlier major BSD releases included 3BSD (1980), 4BSD (1980), and
              4.1BSD (1981).

       4.3BSD The successor to 4.2BSD, released in 1986.

       4.4BSD The successor to 4.3BSD, released in 1993.  This was the last major
              Berkeley release.

       System V
              This is an implementation standard defined by AT&T's milestone 1983
              release of its commercial System V (five) release.  The previous
              major AT&T release was System III, released in 1981.

       System V release 2 (SVr2)
              This was the next System V release, made in 1985.  The SVr2 was
              formally described in the System V Interface Definition version 1
              (SVID 1) published in 1985.

       System V release 3 (SVr3)
              This was the successor to SVr2, released in 1986.  This release was
              formally described in the System V Interface Definition version 2
              (SVID 2).

       System V release 4 (SVr4)
              This was the successor to SVr3, released in 1989.  This version of
              System V is described in the "Programmer's Reference Manual:
              Operating System API (Intel processors)" (Prentice-Hall 1992, ISBN
              0-13-951294-2) This release was formally described in the System V
              Interface Definition version 3 (SVID 3), and is considered the
              definitive System V release.

       SVID 4 System V Interface Definition version 4, issued in 1995.  Available
              online at <http://www.sco.com/developers/devspecs/>.

       C89    This was the first C language standard, ratified by ANSI (American
              National Standards Institute) in 1989 (X3.159-1989).  Sometimes this
              is known as ANSI C, but since C99 is also an ANSI standard, this
              term is ambiguous.  This standard was also ratified by ISO (Interna-
              tional Standards Organization) in 1990 (ISO/IEC 9899:1990), and is
              thus occasionally referred to as ISO C90.

       C99    This revision of the C language standard was ratified by ISO in 1999
              (ISO/IEC 9899:1999).  Available online at <http://www.open-std.org
              /jtc1/sc22/wg14/www/standards>.

       POSIX.1-1990
              "Portable Operating System Interface for Computing Environments".
              IEEE 1003.1-1990 part 1, ratified by ISO in 1990 (ISO/IEC
              9945-1:1990).  The term "POSIX" was coined by Richard Stallman.

       POSIX.2
              IEEE Std 1003.2-1992, describing commands and utilities, ratified by
              ISO in 1993 (ISO/IEC 9945-2:1993).

       POSIX.1b (formerly known as POSIX.4)
              IEEE Std 1003.1b-1993 describing real-time facilities for portable
              operating systems, ratified by ISO in 1996 (ISO/IEC 9945-1:1996).

       POSIX.1c
              IEEE Std 1003.1c-1995 describing the POSIX threads interfaces.

       POSIX.1d
              IEEE Std 1003.1c-1999 describing additional real-time extensions.

       POSIX.1g
              IEEE Std 1003.1g-2000 describing networking APIs (including sock-
              ets).

       POSIX.1j
              IEEE Std 1003.1j-2000 describing advanced real-time extensions.

       POSIX.1-1996
              A 1996 revision of POSIX.1 which incorporated POSIX.1b and POSIX.1c.

       XPG3   Released in 1989, this was the first significant release of the
              X/Open Portability Guide, produced by the X/Open Company, a multi-
              vendor consortium.  This multivolume guide was based on the POSIX
              standards.

       XPG4   A revision of the X/Open Portability Guide, released in 1992.

       XPG4v2 A 1994 revision of XPG4.  This is also referred to as Spec 1170,
              where 1170 referred to the number of interfaces defined by this
              standard.

       SUS (SUSv1)
              Single UNIX Specification.  This was a repackaging of XPG4v2 and
              other X/Open standards (X/Open Curses Issue 4 version 2, X/Open Net-
              working Service (XNS) Issue 4).  Systems conforming to this standard
              can be branded UNIX 95.

       SUSv2  Single UNIX Specification version 2.  Sometimes also referred to as
              XPG5.  This standard appeared in 1997.  Systems conforming to this
              standard can be branded UNIX 98.  See also <http://www.UNIX-
              systems.org/version2/>.)

       POSIX.1-2001, SUSv3
              This was a 2001 revision and consolidation of the POSIX.1, POSIX.2,
              and SUS standards into a single document, conducted under the aus-
              pices of the Austin group <http://www.opengroup.org/austin/>.  The
              standard is available online at <http://www.unix-systems.org
              /version3/>, and the interfaces that it describes are also available
              in the Linux manual pages package under sections 1p and 3p (e.g.,
              "man 3p open").

              The standard defines two levels of conformance: POSIX conformance,
              which is a baseline set of interfaces required of a conforming sys-
              tem; and XSI Conformance, which additionally mandates a set of
              interfaces (the "XSI extension") which are only optional for POSIX
              conformance.  XSI-conformant systems can be branded UNIX 03.  (XSI
              conformance constitutes the Single UNIX Specification version 3
              (SUSv3).)

              The POSIX.1-2001 document is broken into four parts:

              XBD: Definitions, terms and concepts, header file specifications.

              XSH: Specifications of functions (i.e., system calls and library
              functions in actual implementations).

              XCU: Specifications of commands and utilities (i.e., the area for-
              merly described by POSIX.2).

              XRAT: Informative text on the other parts of the standard.

              POSIX.1-2001 is aligned with C99, so that all of the library func-
              tions standardized in C99 are also standardized in POSIX.1-2001.

              Two Technical Corrigenda (minor fixes and improvements) of the orig-
              inal 2001 standard have occurred: TC1 in 2003 (referred to as
              POSIX.1-2003), and TC2 in 2004 (referred to as POSIX.1-2004).

       POSIX.1-2008, SUSv4
              Work on the next revision of POSIX.1/SUS was completed and ratified
              in 2008.

              The changes in this revision are not as large as those that occurred
              for POSIX.1-2001/SUSv3, but a number of new interfaces are added and
              various details of existing specifications are modified.  Many of
              the interfaces that were optional in POSIX.1-2001 become mandatory
              in the 2008 revision of the standard.  A few interfaces that are
              present in POSIX.1-2001 are marked as obsolete in POSIX.1-2008, or
              removed from the standard altogether.

              The revised standard is broken into the same four parts as
              POSIX.1-2001, and again there are two levels of conformance: the
              baseline POSIX Conformance, and XSI Conformance, which mandates an
              additional set of interfaces beyond those in the base specification.

              In general, where the CONFORMING TO section of a manual page lists
              POSIX.1-2001, it can be assumed that the interface also conforms to
              POSIX.1-2008, unless otherwise noted.

              Further information can be found on the Austin group web site,
              <http://www.opengroup.org/austin/>.

SEE ALSO top

       feature_test_macros(7), libc(7), posixoptions(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                        STANDARDS(7)


stdarg(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | EXAMPLE | COLOPHON The Linux Programming Interface

STDARG(3)                    Linux Programmer's Manual                   STDARG(3)

NAME top

       stdarg, va_start, va_arg, va_end, va_copy - variable argument lists

SYNOPSIS top

       #include <stdarg.h>

       void va_start(va_list ap, last);
       type va_arg(va_list ap, type);
       void va_end(va_list ap);
       void va_copy(va_list dest, va_list src);

DESCRIPTION top

       A function may be called with a varying number of arguments of varying
       types.  The include file <stdarg.h> declares a type va_list and defines
       three macros for stepping through a list of arguments whose number and
       types are not known to the called function.

       The called function must declare an object of type va_list which is used by
       the macros va_start(), va_arg(), and va_end().

va_start()

       The va_start() macro initializes ap for subsequent use by va_arg() and
       va_end(), and must be called first.

       The argument last is the name of the last argument before the variable
       argument list, that is, the last argument of which the calling function
       knows the type.

       Because the address of this argument may be used in the va_start() macro,
       it should not be declared as a register variable, or as a function or an
       array type.

va_arg()

       The va_arg() macro expands to an expression that has the type and value of
       the next argument in the call.  The argument ap is the va_list ap
       initialized by va_start().  Each call to va_arg() modifies ap so that the
       next call returns the next argument.  The argument type is a type name
       specified so that the type of a pointer to an object that has the specified
       type can be obtained simply by adding a * to type.

       The first use of the va_arg() macro after that of the va_start() macro
       returns the argument after last.  Successive invocations return the values
       of the remaining arguments.

       If there is no next argument, or if type is not compatible with the type of
       the actual next argument (as promoted according to the default argument
       promotions), random errors will occur.

       If ap is passed to a function that uses va_arg(ap,type) then the value of
       ap is undefined after the return of that function.

va_end()

       Each invocation of va_start() must be matched by a corresponding invocation
       of va_end() in the same function.  After the call va_end(ap) the variable
       ap is undefined.  Multiple traversals of the list, each bracketed by
       va_start() and va_end() are possible.  va_end() may be a macro or a
       function.

va_copy()

       An obvious implementation would have a va_list be a pointer to the stack
       frame of the variadic function.  In such a setup (by far the most common)
       there seems nothing against an assignment

           va_list aq = ap;

       Unfortunately, there are also systems that make it an array of pointers (of
       length 1), and there one needs

           va_list aq;
           *aq = *ap;

       Finally, on systems where arguments are passed in registers, it may be
       necessary for va_start() to allocate memory, store the arguments there, and
       also an indication of which argument is next, so that va_arg() can step
       through the list.  Now va_end() can free the allocated memory again.  To
       accommodate this situation, C99 adds a macro va_copy(), so that the above
       assignment can be replaced by

           va_list aq;
           va_copy(aq, ap);
           ...
           va_end(aq);

       Each invocation of va_copy() must be matched by a corresponding invocation
       of va_end() in the same function.  Some systems that do not supply
       va_copy() have __va_copy instead, since that was the name used in the draft
       proposal.

CONFORMING TO top

       The va_start(), va_arg(), and va_end() macros conform to C89.  C99 defines
       the va_copy() macro.

NOTES top

       These macros are not compatible with the historic macros they replace.  A
       backward-compatible version can be found in the include file <varargs.h>.

       The historic setup is:

           #include <varargs.h>

           void
           foo(va_alist)
               va_dcl
           {
               va_list ap;

               va_start(ap);
               while (...) {
                   ...
                   x = va_arg(ap, type);
                   ...
               }
               va_end(ap);
           }

       On some systems, va_end contains a closing '}' matching a '{' in va_start,
       so that both macros must occur in the same function, and in a way that
       allows this.

BUGS top

       Unlike the varargs macros, the stdarg macros do not permit programmers to
       code a function with no fixed arguments.  This problem generates work
       mainly when converting varargs code to stdarg code, but it also creates
       difficulties for variadic functions that wish to pass all of their
       arguments on to a function that takes a va_list argument, such as
       vfprintf(3).

EXAMPLE top

       The function foo takes a string of format characters and prints out the
       argument associated with each format character based on the type.

       #include <stdio.h>
       #include <stdarg.h>

       void
       foo(char *fmt, ...)
       {
           va_list ap;
           int d;
           char c, *s;

           va_start(ap, fmt);
           while (*fmt)
               switch (*fmt++) {
               case 's':              /* string */
                   s = va_arg(ap, char *);
                   printf("string %s\n", s);
                   break;
               case 'd':              /* int */
                   d = va_arg(ap, int);
                   printf("int %d\n", d);
                   break;
               case 'c':              /* char */
                   /* need a cast here since va_arg only
                      takes fully promoted types */
                   c = (char) va_arg(ap, int);
                   printf("char %c\n", c);
                   break;
               }
           va_end(ap);
       }

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-10-14                           STDARG(3)


stdin(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

STDIN(3)                     Linux Programmer's Manual                    STDIN(3)

NAME top

       stdin, stdout, stderr - standard I/O streams

SYNOPSIS top

       #include <stdio.h>

       extern FILE *stdin;
       extern FILE *stdout;
       extern FILE *stderr;

DESCRIPTION top

       Under normal circumstances every UNIX program has three streams opened for
       it when it starts up, one for input, one for output, and one for printing
       diagnostic or error messages.  These are typically attached to the user's
       terminal (see tty(4) but might instead refer to files or other devices,
       depending on what the parent process chose to set up.  (See also the
       "Redirection" section of sh(1).)

       The input stream is referred to as "standard input"; the output stream is
       referred to as "standard output"; and the error stream is referred to as
       "standard error".  These terms are abbreviated to form the symbols used to
       refer to these files, namely stdin, stdout, and stderr.

       Each of these symbols is a stdio(3) macro of type pointer to FILE, and can
       be used with functions like fprintf(3) or fread(3).

       Since FILEs are a buffering wrapper around UNIX file descriptors, the same
       underlying files may also be accessed using the raw UNIX file interface,
       that is, the functions like read(2) and lseek(2).

       On program startup, the integer file descriptors associated with the
       streams stdin, stdout, and stderr are 0, 1, and 2, respectively.  The
       preprocessor symbols STDIN_FILENO, STDOUT_FILENO, and STDERR_FILENO are
       defined with these values in <unistd.h>.  (Applying freopen(3) to one of
       these streams can change the file descriptor number associated with the
       stream.)

       Note that mixing use of FILEs and raw file descriptors can produce
       unexpected results and should generally be avoided.  (For the masochistic
       among you: POSIX.1, section 8.2.3, describes in detail how this interaction
       is supposed to work.)  A general rule is that file descriptors are handled
       in the kernel, while stdio is just a library.  This means for example, that
       after an exec(3), the child inherits all open file descriptors, but all old
       streams have become inaccessible.

       Since the symbols stdin, stdout, and stderr are specified to be macros,
       assigning to them is nonportable.  The standard streams can be made to
       refer to different files with help of the library function freopen(3),
       specially introduced to make it possible to reassign stdin, stdout, and
       stderr.  The standard streams are closed by a call to exit(3) and by normal
       program termination.

CONFORMING TO top

       The stdin, stdout, and stderr macros conform to C89 and this standard also
       stipulates that these three streams shall be open at program startup.

NOTES top

       The stream stderr is unbuffered.  The stream stdout is line-buffered when
       it points to a terminal.  Partial lines will not appear until fflush(3) or
       exit(3) is called, or a newline is printed.  This can produce unexpected
       results, especially with debugging output.  The buffering mode of the
       standard streams (or any other stream) can be changed using the setbuf(3)
       or setvbuf(3) call.  Note that in case stdin is associated with a terminal,
       there may also be input buffering in the terminal driver, entirely
       unrelated to stdio buffering.  (Indeed, normally terminal input is line
       buffered in the kernel.)  This kernel input handling can be modified using
       calls like tcsetattr(3); see also stty(1), and termios(3).

SEE ALSO top

       csh(1), sh(1), open(2), fopen(3), stdio(3)

COLOPHON top

       This page is part of release 3.45 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-07-14                            STDIN(3)


stdio(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STDIO(3)                     Linux Programmer's Manual                    STDIO(3)

NAME top

       stdio - standard input/output library functions

SYNOPSIS top

       #include <stdio.h>

       FILE *stdin;
       FILE *stdout;
       FILE *stderr;

DESCRIPTION top

       The standard I/O library provides a simple and efficient buffered stream
       I/O interface.  Input and output is mapped into logical data streams and
       the physical I/O characteristics are concealed.  The functions and macros
       are listed below; more information is available from the individual man
       pages.

       A stream is associated with an external file (which may be a physical
       device) by opening a file, which may involve creating a new file.  Creating
       an existing file causes its former contents to be discarded.  If a file can
       support positioning requests (such as a disk file, as opposed to a
       terminal) then a file position indicator associated with the stream is
       positioned at the start of the file (byte zero), unless the file is opened
       with append mode.  If append mode is used, it is unspecified whether the
       position indicator will be placed at the start or the end of the file.  The
       position indicator is maintained by subsequent reads, writes and
       positioning requests.  All input occurs as if the characters were read by
       successive calls to the fgetc(3) function; all output takes place as if all
       characters were written by successive calls to the fputc(3) function.

       A file is disassociated from a stream by closing the file.  Output streams
       are flushed (any unwritten buffer contents are transferred to the host
       environment) before the stream is disassociated from the file.  The value
       of a pointer to a FILE object is indeterminate after a file is closed
       (garbage).

       A file may be subsequently reopened, by the same or another program
       execution, and its contents reclaimed or modified (if it can be
       repositioned at the start).  If the main function returns to its original
       caller, or the exit(3) function is called, all open files are closed (hence
       all output streams are flushed) before program termination.  Other methods
       of program termination, such as abort(3) do not bother about closing files
       properly.

       At program startup, three text streams are predefined and need not be
       opened explicitly: standard input (for reading conventional input),
       standard output (for writing conventional input), and standard error (for
       writing diagnostic output).  These streams are abbreviated stdin,stdout and
       stderr.  When opened, the standard error stream is not fully buffered; the
       standard input and output streams are fully buffered if and only if the
       streams do not to refer to an interactive device.

       Output streams that refer to terminal devices are always line buffered by
       default; pending output to such streams is written automatically whenever
       an input stream that refers to a terminal device is read.  In cases where a
       large amount of computation is done after printing part of a line on an
       output terminal, it is necessary to fflush(3) the standard output before
       going off and computing so that the output will appear.

       The stdio library is a part of the library libc and routines are
       automatically loaded as needed by the compilers cc(1) and pc(1).  The
       SYNOPSIS sections of the following manual pages indicate which include
       files are to be used, what the compiler declaration for the function looks
       like and which external variables are of interest.

       The following are defined as macros; these names may not be reused without
       first removing their current definitions with #undef: BUFSIZ, EOF,
       FILENAME_MAX, FOPEN_MAX, L_cuserid, L_ctermid, L_tmpnam, NULL, SEEK_END,
       SEEK_SET, SEEK_CUR, TMP_MAX, clearerr, feof, ferror, fileno, getc, getchar,
       putc, putchar, stderr, stdin, stdout.  Function versions of the macro
       functions feof, ferror, clearerr, fileno, getc, getchar, putc, and putchar
       exist and will be used if the macros definitions are explicitly removed.

List of Functions

       Function      Description
       -------------------------------------------------------------------
       clearerr      check and reset stream status
       fclose        close a stream
       fdopen        stream open functions
       feof          check and reset stream status
       ferror        check and reset stream status
       fflush        flush a stream
       fgetc         get next character or word from input stream
       fgetpos       reposition a stream
       fgets         get a line from a stream
       fileno        return the integer descriptor of the argument stream
       fopen         stream open functions
       fprintf       formatted output conversion
       fpurge        flush a stream
       fputc         output a character or word to a stream
       fputs         output a line to a stream
       fread         binary stream input/output
       freopen       stream open functions
       fscanf        input format conversion
       fseek         reposition a stream
       fsetpos       reposition a stream
       ftell         reposition a stream
       fwrite        binary stream input/output
       getc          get next character or word from input stream
       getchar       get next character or word from input stream
       gets          get a line from a stream
       getw          get next character or word from input stream
       mktemp        make temporary filename (unique)
       perror        system error messages
       printf        formatted output conversion
       putc          output a character or word to a stream
       putchar       output a character or word to a stream
       puts          output a line to a stream
       putw          output a character or word to a stream
       remove        remove directory entry
       rewind        reposition a stream
       scanf         input format conversion
       setbuf        stream buffering operations
       setbuffer     stream buffering operations
       setlinebuf    stream buffering operations
       setvbuf       stream buffering operations
       sprintf       formatted output conversion
       sscanf        input format conversion
       strerror      system error messages
       sys_errlist   system error messages
       sys_nerr      system error messages
       tempnam       temporary file routines
       tmpfile       temporary file routines
       tmpnam        temporary file routines
       ungetc        un-get character from input stream
       vfprintf      formatted output conversion
       vfscanf       input format conversion

       vprintf       formatted output conversion
       vscanf        input format conversion
       vsprintf      formatted output conversion
       vsscanf       input format conversion

CONFORMING TO top

       The stdio library conforms to C89.

SEE ALSO top

       close(2), open(2), read(2), write(2), stdout(3), unlocked_stdio(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-12-26                            STDIO(3)


stdio_ext(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

STDIO_EXT(3)                 Linux Programmer's Manual                STDIO_EXT(3)

NAME top

       __fbufsize,  __flbf, __fpending, __fpurge, __freadable, __freading, __fset-
       locking, __fwritable, __fwriting, _flushlbf  -  interfaces  to  stdio  FILE
       structure

SYNOPSIS top

       #include <stdio.h>
       #include <stdio_ext.h>

       size_t __fbufsize(FILE *stream);
       size_t __fpending(FILE *stream);
       int __flbf(FILE *stream);
       int __freadable(FILE *stream);
       int __fwritable(FILE *stream);
       int __freading(FILE *stream);
       int __fwriting(FILE *stream);
       int __fsetlocking(FILE *stream, int type);
       void _flushlbf(void);
       void __fpurge(FILE *stream);

DESCRIPTION top

       Solaris introduced routines to allow portable access to the internals of
       the FILE structure, and glibc also implemented these.

       The __fbufsize() function returns the size of the buffer currently used by
       the given stream.

       The __fpending() function returns the number of bytes in the output buffer.
       For wide-oriented streams the unit is wide characters.  This function is
       undefined on buffers in reading mode, or opened read-only.

       The __flbf() function returns a nonzero value if the stream is line-
       buffered, and zero otherwise.

       The __freadable() function returns a nonzero value if the stream allows
       reading, and zero otherwise.

       The __fwritable() function returns a nonzero value if the stream allows
       writing, and zero otherwise.

       The __freading() function returns a nonzero value if the stream is read-
       only, or if the last operation on the stream was a read operation, and zero
       otherwise.

       The __fwriting() function returns a nonzero value if the stream is write-
       only (or append-only), or if the last operation on the stream was a write
       operation, and zero otherwise.

       The __fsetlocking() function can be used to select the desired type of
       locking on the stream.  It returns the current type.  The type argument can
       take the following three values:

       FSETLOCKING_INTERNAL
              Perform implicit locking around every operation on the given stream
              (except for the *_unlocked ones).  This is the default.

       FSETLOCKING_BYCALLER
              The caller will take care of the locking (possibly using
              flockfile(3) in case there is more than one thread), and the stdio
              routines will not do locking until the state is reset to
              FSETLOCKING_INTERNAL.

       FSETLOCKING_QUERY
              Don't change the type of locking.  (Only return it.)

       The _flushlbf() function flushes all line-buffered streams.  (Presumably so
       that output to a terminal is forced out, say before reading keyboard
       input.)

       The __fpurge() function discards the contents of the stream's buffer.

SEE ALSO top

       flockfile(3), fpurge(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-12-16                        STDIO_EXT(3)


stime(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STIME(2)                     Linux Programmer's Manual                    STIME(2)

NAME top

       stime - set time

SYNOPSIS top

       #include <time.h>

       int stime(time_t *t);

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

       stime(): _SVID_SOURCE

DESCRIPTION top

       stime() sets the system's idea of the time and date.  The time, pointed to
       by t, is measured in seconds since the Epoch, 1970-01-01 00:00:00 +0000
       (UTC).  stime() may only be executed by the superuser.

RETURN VALUE top

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

ERRORS top

       EFAULT Error in getting information from user space.

       EPERM  The calling process has insufficient privilege.  Under Linux the
              CAP_SYS_TIME privilege is required.

CONFORMING TO top

       SVr4.

SEE ALSO top

       date(1), settimeofday(2), capabilities(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-25                            STIME(2)


stpcpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STPCPY(3)                    Linux Programmer's Manual                   STPCPY(3)

NAME top

       stpcpy - copy a string returning a pointer to its end

SYNOPSIS top

       #include <string.h>

       char *stpcpy(char *dest, const char *src);

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

       stpcpy():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The stpcpy() function copies the string pointed to by src (including the
       terminating null byte ('\0')) to the array pointed to by dest.  The strings
       may not overlap, and the destination string dest must be large enough to
       receive the copy.

RETURN VALUE top

       stpcpy() returns a pointer to the end of the string dest (that is, the
       address of the terminating null byte) rather than the beginning.

CONFORMING TO top

       This function was added to POSIX.1-2008. Before that, it was not part of
       the C or POSIX.1 standards, nor customary on UNIX systems, but was not a
       GNU invention either.  Perhaps it came from MS-DOS.  It is also present on
       the BSDs.

BUGS top

       This function may overrun the buffer dest.

EXAMPLE top

       For example, this program uses stpcpy() to concatenate foo and bar to
       produce foobar, which it then prints.

           #define _GNU_SOURCE
           #include <string.h>
           #include <stdio.h>

           int
           main(void)
           {
               char buffer[20];
               char *to = buffer;

               to = stpcpy(to, "foo");
               to = stpcpy(to, "bar");
               printf("%s\n", buffer);
           }

SEE ALSO top

       bcopy(3), memccpy(3), memcpy(3), memmove(3), stpncpy(3), strcpy(3),
       string(3), wcpcpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-03-15                           STPCPY(3)


stpncpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STPNCPY(3)                   Linux Programmer's Manual                  STPNCPY(3)

NAME top

       stpncpy - copy a fixed-size string, returning a pointer to its end

SYNOPSIS top

       #include <string.h>

       char *stpncpy(char *dest, const char *src, size_t n);

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

       stpncpy():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The stpncpy() function copies at most n characters from the string pointed
       to by src, including the terminating null byte ('\0'), to the array pointed
       to by dest.  Exactly n characters are written at dest.  If the length
       strlen(src) is smaller than n, the remaining characters in the array
       pointed to by dest are filled with null bytes ('\0'), If the length
       strlen(src) is greater or equal to n, the string pointed to by dest will
       not be null-terminated.

       The strings may not overlap.

       The programmer must ensure that there is room for at least n characters at
       dest.

RETURN VALUE top

       stpncpy() returns a pointer to the terminating null byte in dest, or, if
       dest is not null-terminated, dest + n.

CONFORMING TO top

       This function was added to POSIX.1-2008. Before that, it was a GNU
       extension.

SEE ALSO top

       strncpy(3), wcpncpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          STPNCPY(3)


strcasecmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRCASECMP(3)                Linux Programmer's Manual               STRCASECMP(3)

NAME top

       strcasecmp, strncasecmp - compare two strings ignoring case

SYNOPSIS top

       #include <strings.h>

       int strcasecmp(const char *s1, const char *s2);

       int strncasecmp(const char *s1, const char *s2, size_t n);

DESCRIPTION top

       The strcasecmp() function compares the two strings s1 and s2, ignoring the
       case of the characters.  It returns an integer less than, equal to, or
       greater than zero if s1 is found, respectively, to be less than, to match,
       or be greater than s2.

       The strncasecmp() function is similar, except it only compares the first n
       bytes of s1.

RETURN VALUE top

       The strcasecmp() and strncasecmp() functions return an integer less than,
       equal to, or greater than zero if s1 (or the first n bytes thereof) is
       found, respectively, to be less than, to match, or be greater than s2.

CONFORMING TO top

       4.4BSD, POSIX.1-2001.

SEE ALSO top

       bcmp(3), memcmp(3), strcmp(3), strcoll(3), string(3), strncmp(3),
       wcscasecmp(3), wcsncasecmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-10                       STRCASECMP(3)


strstr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

STRSTR(3)                    Linux Programmer's Manual                   STRSTR(3)

NAME top

       strstr, strcasestr - locate a substring

SYNOPSIS top

       #include <string.h>

       char *strstr(const char *haystack, const char *needle);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */

       #include <string.h>

       char *strcasestr(const char *haystack, const char *needle);

DESCRIPTION top

       The strstr() function finds the first occurrence of the substring needle in
       the string haystack.  The terminating null bytes ('\0') are not compared.

       The strcasestr() function is like strstr(), but ignores the case of both
       arguments.

RETURN VALUE top

       These functions return a pointer to the beginning of the substring, or NULL
       if the substring is not found.

CONFORMING TO top

       The strstr() function conforms to C89 and C99.  The strcasestr() function
       is a nonstandard extension.

BUGS top

       Early versions of Linux libc (like 4.5.26) would not allow an empty needle
       argument for strstr().  Later versions (like 4.6.27) work correctly, and
       return haystack when needle is empty.

SEE ALSO top

       index(3), memchr(3), rindex(3), strcasecmp(3), strchr(3), string(3),
       strpbrk(3), strsep(3), strspn(3), strtok(3), wcsstr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           STRSTR(3)


strcat(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

STRCAT(3)                    Linux Programmer's Manual                   STRCAT(3)

NAME top

       strcat, strncat - concatenate two strings

SYNOPSIS top

       #include <string.h>

       char *strcat(char *dest, const char *src);

       char *strncat(char *dest, const char *src, size_t n);

DESCRIPTION top

       The strcat() function appends the src string to the dest string,
       overwriting the terminating null byte ('\0') at the end of dest, and then
       adds a terminating null byte.  The strings may not overlap, and the dest
       string must have enough space for the result.  If dest is not large enough,
       program behavior is unpredictable; buffer overruns are a favorite avenue
       for attacking secure programs.

       The strncat() function is similar, except that

       *  it will use at most n bytes from src; and

       *  src does not need to be null-terminated if it contains n or more bytes.

       As with strcat(), the resulting string in dest is always null-terminated.

       If src contains n or more bytes, strncat() writes n+1 bytes to dest (n from
       src plus the terminating null byte).  Therefore, the size of dest must be
       at least strlen(dest)+n+1.

       A simple implementation of strncat() might be:

           char*
           strncat(char *dest, const char *src, size_t n)
           {
               size_t dest_len = strlen(dest);
               size_t i;

               for (i = 0 ; i < n && src[i] != '\0' ; i++)
                   dest[dest_len + i] = src[i];
               dest[dest_len + i] = '\0';

               return dest;
           }

RETURN VALUE top

       The strcat() and strncat() functions return a pointer to the resulting
       string dest.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

NOTES top

       Some systems (the BSDs, Solaris, and others) provide the following
       function:

           size_t strlcat(char *dest, const char *src, size_t size);

       This function appends the null-terminated string src to the string dest,
       copying at most size-strlen(dest)-1 from src, and adds a null terminator to
       the result, unless size is less than strlen(dest).  This function fixes the
       buffer overrun problem of strcat(), but the caller must still handle the
       possibility of data loss if size is too small.  The function returns the
       length of the string strlcat() tried to create; if the return value is
       greater than or equal to size, data loss occurred.  If data loss matters,
       the caller must either check the arguments before the call, or test the
       function return value.  strlcat() is not present in glibc and is not
       standardized by POSIX, but is available on Linux via the libbsd library.

SEE ALSO top

       bcopy(3), memccpy(3), memcpy(3), strcpy(3), string(3), strncpy(3),
       wcscat(3), wcsncat(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-07-19                           STRCAT(3)


strchr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRCHR(3)                    Linux Programmer's Manual                   STRCHR(3)

NAME top

       strchr, strrchr, strchrnul - locate character in string

SYNOPSIS top

       #include <string.h>

       char *strchr(const char *s, int c);

       char *strrchr(const char *s, int c);

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <string.h>

       char *strchrnul(const char *s, int c);

DESCRIPTION top

       The strchr() function returns a pointer to the first occurrence of the
       character c in the string s.

       The strrchr() function returns a pointer to the last occurrence of the
       character c in the string s.

       The strchrnul() function is like strchr() except that if c is not found in
       s, then it returns a pointer to the null byte at the end of s, rather than
       NULL.

       Here "character" means "byte"; these functions do not work with wide or
       multibyte characters.

RETURN VALUE top

       The strchr() and strrchr() functions return a pointer to the matched
       character or NULL if the character is not found.  The terminating null byte
       is considered part of the string, so that if c is specified as '\0', these
       functions return a pointer to the terminator.

       The strchrnul() function returns a pointer to the matched character, or a
       pointer to the null byte at the end of s (i.e., s+strlen(s)) if the
       character is not found.

VERSIONS top

       strchrnul() first appeared in glibc in version 2.1.1.

CONFORMING TO top

       strchr() and strrchr() are in SVr4, 4.3BSD, C89, C99.  strchrnul() is a GNU
       extension.

SEE ALSO top

       index(3), memchr(3), rindex(3), string(3), strlen(3), strpbrk(3),
       strsep(3), strspn(3), strstr(3), strtok(3), wcschr(3), wcsrchr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-24                           STRCHR(3)


strcmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRCMP(3)                    Linux Programmer's Manual                   STRCMP(3)

NAME top

       strcmp, strncmp - compare two strings

SYNOPSIS top

       #include <string.h>

       int strcmp(const char *s1, const char *s2);

       int strncmp(const char *s1, const char *s2, size_t n);

DESCRIPTION top

       The strcmp() function compares the two strings s1 and s2.  It returns an
       integer less than, equal to, or greater than zero if s1 is found,
       respectively, to be less than, to match, or be greater than s2.

       The strncmp() function is similar, except it only compares the first (at
       most) n bytes of s1 and s2.

RETURN VALUE top

       The strcmp() and strncmp() functions return an integer less than, equal to,
       or greater than zero if s1 (or the first n bytes thereof) is found,
       respectively, to be less than, to match, or be greater than s2.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

SEE ALSO top

       bcmp(3), memcmp(3), strcasecmp(3), strcoll(3), string(3), strncasecmp(3),
       strverscmp(3), wcscmp(3), wcsncmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-11-25                           STRCMP(3)


strcoll(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

STRCOLL(3)                   Linux Programmer's Manual                  STRCOLL(3)

NAME top

       strcoll - compare two strings using the current locale

SYNOPSIS top

       #include <string.h>

       int strcoll(const char *s1, const char *s2);

DESCRIPTION top

       The strcoll() function compares the two strings s1 and s2.  It returns an
       integer less than, equal to, or greater than zero if s1 is found,
       respectively, to be less than, to match, or be greater than s2.  The
       comparison is based on strings interpreted as appropriate for the program's
       current locale for category LC_COLLATE.  (See setlocale(3).)

RETURN VALUE top

       The strcoll() function returns an integer less than, equal to, or greater
       than zero if s1 is found, respectively, to be less than, to match, or be
       greater than s2, when both are interpreted as appropriate for the current
       locale.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

NOTES top

       In the "POSIX" or "C" locales strcoll() is equivalent to strcmp(3).

SEE ALSO top

       bcmp(3), memcmp(3), setlocale(3), strcasecmp(3), strcmp(3), string(3),
       strxfrm(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                          STRCOLL(3)


strcpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

STRCPY(3)                    Linux Programmer's Manual                   STRCPY(3)

NAME top

       strcpy, strncpy - copy a string

SYNOPSIS top

       #include <string.h>

       char *strcpy(char *dest, const char *src);

       char *strncpy(char *dest, const char *src, size_t n);

DESCRIPTION top

       The strcpy() function copies the string pointed to by src, including the
       terminating null byte ('\0'), to the buffer pointed to by dest.  The
       strings may not overlap, and the destination string dest must be large
       enough to receive the copy.  Beware of buffer overruns!  (See BUGS.)

       The strncpy() function is similar, except that at most n bytes of src are
       copied.  Warning: If there is no null byte among the first n bytes of src,
       the string placed in dest will not be null-terminated.

       If the length of src is less than n, strncpy() writes additional null bytes
       to dest to ensure that a total of n bytes are written.

       A simple implementation of strncpy() might be:

           char *
           strncpy(char *dest, const char *src, size_t n)
           {
               size_t i;

               for (i = 0; i < n && src[i] != '\0'; i++)
                   dest[i] = src[i];
               for ( ; i < n; i++)
                   dest[i] = '\0';

               return dest;
           }

RETURN VALUE top

       The strcpy() and strncpy() functions return a pointer to the destination
       string dest.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

NOTES top

       Some programmers consider strncpy() to be inefficient and error prone.  If
       the programmer knows (i.e., includes code to test!)  that the size of dest
       is greater than the length of src, then strcpy() can be used.

       One valid (and intended) use of strncpy() is to copy a C string to a fixed-
       length buffer while ensuring both that the buffer is not overflowed and
       that unused bytes in the target buffer are zeroed out (perhaps to prevent
       information leaks if the buffer is to be written to media or transmitted to
       another process via an interprocess communication technique).

       If there is no terminating null byte in the first n bytes of src, strncpy()
       produces an unterminated string in dest.  You can force termination using
       something like the following:

           strncpy(buf, str, n);
           if (n > 0)
               buf[n - 1]= '\0';

       (Of course, the above technique ignores the fact that information contained
       in src is lost in the copying to dest.)

       Some systems (the BSDs, Solaris, and others) provide the following
       function:

           size_t strlcpy(char *dest, const char *src, size_t size);

       This function is similar to strncpy(), but it copies at most size-1 bytes
       to dest, always adds a terminating null byte, and does not pad the target
       with (further) null bytes.  This function fixes some of the problems of
       strcpy() and strncpy(), but the caller must still handle the possibility of
       data loss if size is too small.  The return value of the function is the
       length of src, which allows truncation to be easily detected: if the return
       value is greater than or equal to size, truncation occurred.  If loss of
       data matters, the caller must either check the arguments before the call,
       or test the function return value.  strlcpy() is not present in glibc and
       is not standardized by POSIX, but is available on Linux via the libbsd
       library.

BUGS top

       If the destination string of a strcpy() is not large enough, then anything
       might happen.  Overflowing fixed-length string buffers is a favorite
       cracker technique for taking complete control of the machine.  Any time a
       program reads or copies data into a buffer, the program first needs to
       check that there's enough space.  This may be unnecessary if you can show
       that overflow is impossible, but be careful: programs can get changed over
       time, in ways that may make the impossible possible.

SEE ALSO top

       bcopy(3), memccpy(3), memcpy(3), memmove(3), stpcpy(3), stpncpy(3),
       strdup(3), string(3), wcscpy(3), wcsncpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-07-19                           STRCPY(3)


strspn(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRSPN(3)                    Linux Programmer's Manual                   STRSPN(3)

NAME top

       strspn, strcspn - search a string for a set of bytes

SYNOPSIS top

       #include <string.h>

       size_t strspn(const char *s, const char *accept);

       size_t strcspn(const char *s, const char *reject);

DESCRIPTION top

       The strspn() function calculates the length (in bytes) of the initial
       segment of s which consists entirely of bytes in accept.

       The strcspn() function calculates the length of the initial segment of s
       which consists entirely of bytes not in reject.

RETURN VALUE top

       The strspn() function returns the number of bytes in the initial segment of
       s which consist only of bytes from accept.

       The strcspn() function returns the number of bytes in the initial segment
       of s which are not in the string reject.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

SEE ALSO top

       index(3), memchr(3), rindex(3), strchr(3), string(3), strpbrk(3),
       strsep(3), strstr(3), strtok(3), wcscspn(3), wcsspn(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-10                           STRSPN(3)


strdup(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRDUP(3)                    Linux Programmer's Manual                   STRDUP(3)

NAME top

       strdup, strndup, strdupa, strndupa - duplicate a string

SYNOPSIS top

       #include <string.h>

       char *strdup(const char *s);

       char *strndup(const char *s, size_t n);
       char *strdupa(const char *s);
       char *strndupa(const char *s, size_t n);

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

       strdup():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
       strndup():
           Since glibc 2.10:
               POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700
           Before glibc 2.10:
               _GNU_SOURCE
       strdupa(), strndupa(): _GNU_SOURCE

DESCRIPTION top

       The strdup() function returns a pointer to a new string which is a
       duplicate of the string s.  Memory for the new string is obtained with
       malloc(3), and can be freed with free(3).

       The strndup() function is similar, but only copies at most n bytes.  If s
       is longer than n, only n bytes are copied, and a terminating null byte
       ('\0') is added.

       strdupa() and strndupa() are similar, but use alloca(3) to allocate the
       buffer.  They are only available when using the GNU GCC suite, and suffer
       from the same limitations described in alloca(3).

RETURN VALUE top

       The strdup() function returns a pointer to the duplicated string, or NULL
       if insufficient memory was available.

ERRORS top

       ENOMEM Insufficient memory available to allocate duplicate string.

CONFORMING TO top

       strdup() conforms to SVr4, 4.3BSD, POSIX.1-2001.  strndup() conforms to
       POSIX.1-2008.  strdupa() and strndupa() are GNU extensions.

SEE ALSO top

       alloca(3), calloc(3), free(3), malloc(3), realloc(3), string(3), wcsdup(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                           STRDUP(3)


strerror(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRERROR(3)                  Linux Programmer's Manual                 STRERROR(3)

NAME top

       strerror, strerror_r - return string describing error number

SYNOPSIS top

       #include <string.h>

       char *strerror(int errnum);

       int strerror_r(int errnum, char *buf, size_t buflen);
                   /* XSI-compliant */

       char *strerror_r(int errnum, char *buf, size_t buflen);
                   /* GNU-specific */

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

       The XSI-compliant version of strerror_r() is provided if:
       (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) && ! _GNU_SOURCE
       Otherwise, the GNU-specific version is provided.

DESCRIPTION top

       The strerror() function returns a pointer to a string that describes the
       error code passed in the argument errnum, possibly using the LC_MESSAGES
       part of the current locale to select the appropriate language.  (For
       example, if errnum is EINVAL, the returned description will "Invalid
       argument".)  This string must not be modified by the application, but may
       be modified by a subsequent call to strerror().  No library function,
       including perror(3), will modify this string.

       The strerror_r() function is similar to strerror(), but is thread safe.
       This function is available in two versions: an XSI-compliant version
       specified in POSIX.1-2001 (available since glibc 2.3.4, but not POSIX-
       compliant until glibc 2.13), and a GNU-specific version (available since
       glibc 2.0).  The XSI-compliant version is provided with the feature test
       macros settings shown in the SYNOPSIS; otherwise the GNU-specific version
       is provided.  If no feature test macros are explicitly defined, then (since
       glibc 2.4) _POSIX_SOURCE is defined by default with the value 200112L, so
       that the XSI-compliant version of strerror_r() is provided by default.

       The XSI-compliant strerror_r() is preferred for portable applications.  It
       returns the error string in the user-supplied buffer buf of length buflen.

       The GNU-specific strerror_r() returns a pointer to a string containing the
       error message.  This may be either a pointer to a string that the function
       stores in buf, or a pointer to some (immutable) static string (in which
       case buf is unused).  If the function stores a string in buf, then at most
       buflen bytes are stored (the string may be truncated if buflen is too small
       and errnum is unknown).  The string always includes a terminating null
       byte.

RETURN VALUE top

       The strerror() and the GNU-specific strerror_r() functions return the
       appropriate error description string, or an "Unknown error nnn" message if
       the error number is unknown.

       POSIX.1-2001 and POSIX.1-2008 require that a successful call to strerror(3)
       shall leave errno unchanged, and note that, since no function return value
       is reserved to indicate an error, an application that wishes to check for
       errors should initialize errno to zero before the call, and then check
       errno after the call.

       The XSI-compliant strerror_r() function returns 0 on success.  On error, a
       (positive) error number is returned (since glibc 2.13), or -1 is returned
       and errno is set to indicate the error (glibc versions before 2.13).

ERRORS top

       EINVAL The value of errnum is not a valid error number.

       ERANGE Insufficient storage was supplied to contain the error description
              string.

CONFORMING TO top

       strerror() is specified by POSIX.1-2001, C89, C99.  strerror_r() is
       specified by POSIX.1-2001.

       The GNU-specific strerror_r() function is a nonstandard extension.

       POSIX.1-2001 permits strerror() to set errno if the call encounters an
       error, but does not specify what value should be returned as the function
       result in the event of an error.  On some systems, strerror() returns NULL
       if the error number is unknown.  On other systems, strerror() returns a
       string something like "Error nnn occurred" and sets errno to EINVAL if the
       error number is unknown.  C99 and POSIX.1-2008 require the return value to
       be non-NULL.

SEE ALSO top

       err(3), errno(3), error(3), perror(3), strsignal(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-04-22                         STRERROR(3)


strfmon(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRFMON(3)                   Linux Programmer's Manual                  STRFMON(3)

NAME top

       strfmon - convert monetary value to a string

SYNOPSIS top

       #include <monetary.h>

       ssize_t strfmon(char *s, size_t max, const char *format, ...);

DESCRIPTION top

       The strfmon() function formats the specified amounts according to the
       format specification format and places the result in the character array s
       of size max.

       Ordinary characters in format are copied to s without conversion.
       Conversion specifiers are introduced by a '%' character.  Immediately
       following it there can be zero or more of the following flags:

       =f     The single-byte character f is used as the numeric fill character
              (to be used with a left precision, see below).  When not specified,
              the space character is used.

       ^      Do not use any grouping characters that might be defined for the
              current locale.  By default, grouping is enabled.

       ( or + The ( flag indicates that negative amounts should be enclosed
              between parentheses.  The + flag indicates that signs should be
              handled in the default way, that is, amounts are preceded by the
              locale's sign indication, for example, nothing for positive, "-" for
              negative.

       !      Omit the currency symbol.

       -      Left justify all fields.  The default is right justification.

       Next, there may be a field width: a decimal digit string specifying a
       minimum field width in bytes.  The default is 0.  A result smaller than
       this width is padded with spaces (on the left, unless the left-justify flag
       was given).

       Next, there may be a left precision of the form "#" followed by a decimal
       digit string.  If the number of digits left of the radix character is
       smaller than this, the representation is padded on the left with the
       numeric fill character.  Grouping characters are not counted in this field
       width.

       Next, there may be a right precision of the form "." followed by a decimal
       digit string.  The amount being formatted is rounded to the specified
       number of digits prior to formatting.  The default is specified in the
       frac_digits and int_frac_digits items of the current locale.  If the right
       precision is 0, no radix character is printed.  (The radix character here
       is determined by LC_MONETARY, and may differ from that specified by
       LC_NUMERIC.)

       Finally, the conversion specification must be ended with a conversion
       character.  The three conversion characters are

       %      (In this case the entire specification must be exactly "%%".)  Put a
              '%' character in the result string.

       i      One argument of type double is converted using the locale's
              international currency format.

       n      One argument of type double is converted using the locale's national
              currency format.

RETURN VALUE top

       The strfmon() function returns the number of characters placed in the array
       s, not including the terminating null byte, provided the string, including
       the terminating null byte, fits.  Otherwise, it sets errno to E2BIG,
       returns -1, and the contents of the array is undefined.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on several other systems.

EXAMPLE top

       The call

           strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]",
                   1234.567, 1234.567);

       outputs

           [ fl **1234,57] [ NLG  **1 234,57]

       in the Dutch locale (with fl for "florijnen" and NLG for Netherlands
       Guilders).  The grouping character is very ugly because it takes as much
       space as a digit, while it should not take more than half that, and will no
       doubt cause confusion.  Surprisingly, the "fl" is preceded and followed by
       a space, and "NLG" is preceded by one and followed by two spaces.  This may
       be a bug in the locale files.  The Italian, Australian, Swiss and
       Portuguese locales yield

           [ L. **1235] [ ITL  **1.235]
           [ $**1234.57] [ AUD **1,234.57]
           [Fr. **1234,57] [CHF  **1.234,57]
           [ **1234$57Esc] [ **1.234$57PTE ]

SEE ALSO top

       setlocale(3), sprintf(3), locale(7)

COLOPHON top

       This page is part of release 3.45 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-12-05                          STRFMON(3)


strfry(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRFRY(3)                    Linux Programmer's Manual                   STRFRY(3)

NAME top

       strfry - randomize a string

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <string.h>

       char *strfry(char *string);

DESCRIPTION top

       The strfry() function randomizes the contents of string by using rand(3) to
       randomly swap characters in the string.  The result is an anagram of
       string.

RETURN VALUE top

       The strfry() functions returns a pointer to the randomized string.

CONFORMING TO top

       The strfry() function is unique to the GNU C Library.

SEE ALSO top

       memfrob(3), string(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           STRFRY(3)


strftime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ENVIRONMENT | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRFTIME(3)                  Linux Programmer's Manual                 STRFTIME(3)

NAME top

       strftime - format date and time

SYNOPSIS top

       #include <time.h>

       size_t strftime(char *s, size_t max, const char *format,
                       const struct tm *tm);

DESCRIPTION top

       The strftime() function formats the broken-down time tm according to the
       format specification format and places the result in the character array s
       of size max.

       The format specification is a null-terminated string and may contain
       special character sequences called conversion specifications, each of which
       is introduced by a '%' character and terminated by some other character
       known as a conversion specifier character.  All other character sequences
       are ordinary character sequences.

       The characters of ordinary character sequences (including the null byte)
       are copied verbatim from format to s.  However, the characters of
       conversion specifications are replaced as follows:

       %a     The abbreviated weekday name according to the current locale.

       %A     The full weekday name according to the current locale.

       %b     The abbreviated month name according to the current locale.

       %B     The full month name according to the current locale.

       %c     The preferred date and time representation for the current locale.

       %C     The century number (year/100) as a 2-digit integer. (SU)

       %d     The day of the month as a decimal number (range 01 to 31).

       %D     Equivalent to %m/%d/%y.  (Yecch--for Americans only.  Americans
              should note that in other countries %d/%m/%y is rather common.  This
              means that in international context this format is ambiguous and
              should not be used.) (SU)

       %e     Like %d, the day of the month as a decimal number, but a leading
              zero is replaced by a space. (SU)

       %E     Modifier: use alternative format, see below. (SU)

       %F     Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)

       %G     The ISO 8601 week-based year (see NOTES) with century as a decimal
              number.  The 4-digit year corresponding to the ISO week number (see
              %V).  This has the same format and value as %Y, except that if the
              ISO week number belongs to the previous or next year, that year is
              used instead. (TZ)

       %g     Like %G, but without century, that is, with a 2-digit year (00-99).
              (TZ)

       %h     Equivalent to %b.  (SU)

       %H     The hour as a decimal number using a 24-hour clock (range 00 to 23).

       %I     The hour as a decimal number using a 12-hour clock (range 01 to 12).

       %j     The day of the year as a decimal number (range 001 to 366).

       %k     The hour (24-hour clock) as a decimal number (range 0 to 23); single
              digits are preceded by a blank.  (See also %H.)  (TZ)

       %l     The hour (12-hour clock) as a decimal number (range 1 to 12); single
              digits are preceded by a blank.  (See also %I.)  (TZ)

       %m     The month as a decimal number (range 01 to 12).

       %M     The minute as a decimal number (range 00 to 59).

       %n     A newline character. (SU)

       %O     Modifier: use alternative format, see below. (SU)

       %p     Either "AM" or "PM" according to the given time value, or the
              corresponding strings for the current locale.  Noon is treated as
              "PM" and midnight as "AM".

       %P     Like %p but in lowercase: "am" or "pm" or a corresponding string for
              the current locale. (GNU)

       %r     The time in a.m. or p.m. notation.  In the POSIX locale this is
              equivalent to %I:%M:%S %p.  (SU)

       %R     The time in 24-hour notation (%H:%M). (SU) For a version including
              the seconds, see %T below.

       %s     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
              (UTC). (TZ)

       %S     The second as a decimal number (range 00 to 60).  (The range is up
              to 60 to allow for occasional leap seconds.)

       %t     A tab character. (SU)

       %T     The time in 24-hour notation (%H:%M:%S). (SU)

       %u     The day of the week as a decimal, range 1 to 7, Monday being 1.  See
              also %w.  (SU)

       %U     The week number of the current year as a decimal number, range 00 to
              53, starting with the first Sunday as the first day of week 01.  See
              also %V and %W.

       %V     The ISO 8601 week number (see NOTES) of the current year as a
              decimal number, range 01 to 53, where week 1 is the first week that
              has at least 4 days in the new year.  See also %U and %W.  (SU)

       %w     The day of the week as a decimal, range 0 to 6, Sunday being 0.  See
              also %u.

       %W     The week number of the current year as a decimal number, range 00 to
              53, starting with the first Monday as the first day of week 01.

       %x     The preferred date representation for the current locale without the
              time.

       %X     The preferred time representation for the current locale without the
              date.

       %y     The year as a decimal number without a century (range 00 to 99).

       %Y     The year as a decimal number including the century.

       %z     The +hhmm or -hhmm numeric timezone (that is, the hour and minute
              offset from UTC). (SU)

       %Z     The timezone or name or abbreviation.

       %+     The date and time in date(1) format. (TZ) (Not supported in glibc2.)

       %%     A literal '%' character.

       Some conversion specifications can be modified by preceding the conversion
       specifier character by the E or O modifier to indicate that an alternative
       format should be used.  If the alternative format or specification does not
       exist for the current locale, the behavior will be as if the unmodified
       conversion specification were used. (SU) The Single UNIX Specification
       mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS,
       %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use
       alternative numeric symbols (say, roman numerals), and that of the E
       modifier is to use a locale-dependent alternative representation.

       The broken-down time structure tm is defined in <time.h>.  See also
       ctime(3).

RETURN VALUE top

       The strftime() function returns the number of bytes placed in the array s,
       not including the terminating null byte, provided the string, including the
       terminating null byte, fits.  Otherwise, it returns 0, and the contents of
       the array is undefined.  (This behavior applies since at least libc 4.4.4;
       very old versions of libc, such as libc 4.4.1, would return max if the
       array was too small.)

       Note that the return value 0 does not necessarily indicate an error; for
       example, in many locales %p yields an empty string.

ENVIRONMENT top

       The environment variables TZ and LC_TIME are used.

CONFORMING TO top

       SVr4, C89, C99.  There are strict inclusions between the set of conversions
       given in ANSI C (unmarked), those given in the Single UNIX Specification
       (marked SU), those given in Olson's timezone package (marked TZ), and those
       given in glibc (marked GNU), except that %+ is not supported in glibc2.  On
       the other hand glibc2 has several more extensions.  POSIX.1 only refers to
       ANSI C; POSIX.2 describes under date(1) several extensions that could apply
       to strftime() as well.  The %F conversion is in C99 and POSIX.1-2001.

       In SUSv2, the %S specifier allowed a range of 00 to 61, to allow for the
       theoretical possibility of a minute that included a double leap second
       (there never has been such a minute).

NOTES top

ISO 8601 Week Dates

       %G, %g, and %V yield values calculated from the week-based year defined by
       the ISO 8601 standard.  In this system, weeks start on a Monday, and are
       numbered from 01, for the first week, up to 52 or 53, for the last week.
       Week 1 is the first week where four or more days fall within the new year
       (or, synonymously, week 01 is: the first week of the year that contains a
       Thursday; or, the week that has 4 January in it).  When three of fewer days
       of the first calendar week of the new year fall within that year, then the
       ISO 8601 week-based system counts those days as part of week 53 of the
       preceding year.  For example, 1 January 2010 is a Friday, meaning that just
       three days of that calendar week fall in 2010.  Thus, the ISO 8601 week-
       based system considers these days to be part of week 53 (%V) of the year
       2009 (%G) ; week 01 of ISO 8601 year 2010 starts on Monday, 4 January 2010.

Glibc Notes

       Glibc provides some extensions for conversion specifications.  (These
       extensions are not specified in POSIX.1-2001, but a few other systems
       provide similar features.)  Between the '%' character and the conversion
       specifier character, an optional flag and field width may be specified.
       (These precede the E or O modifiers, if present.)

       The following flag characters are permitted:

       _      (underscore) Pad a numeric result string with spaces.

       -      (dash) Do not pad a numeric result string.

       0      Pad a numeric result string with zeros even if the conversion
              specifier character uses space-padding by default.

       ^      Convert alphabetic characters in result string to upper case.

       #      Swap the case of the result string.  (This flag only works with
              certain conversion specifier characters, and of these, it is only
              really useful with %Z.)

       An optional decimal width specifier may follow the (possibly absent) flag.
       If the natural size of the field is smaller than this width, then the
       result string is padded (on the left) to the specified width.

BUGS          top
       Some buggy versions of gcc(1) complain about the use of %c: warning: `%c'
       yields only last 2 digits of year in some locales.  Of course programmers
       are encouraged to use %c, it gives the preferred date and time
       representation.  One meets all kinds of strange obfuscations to circumvent
       this gcc(1) problem.  A relatively clean one is to add an intermediate
       function

           size_t
           my_strftime(char *s, size_t max, const char *fmt,
                       const struct tm *tm)
           {
               return strftime(s, max, fmt, tm);
           }

       Nowadays, gcc(1) provides the -Wno-format-y2k option to prevent the
       warning, so that the above workaround is no longer required.

EXAMPLE          top
       RFC 2822-compliant date format (with an English locale for %a and %b)

         "%a, %d %b %Y %T %z"

       RFC 822-compliant date format (with an English locale for %a and %b)

         "%a, %d %b %y %T %z"

Example Program

       The program below can be used to experiment with strftime().

       Some examples of the result string produced by the glibc implementation of
       strftime() are as follows:

           $ ./a.out '%m'
           Result string is "11"
           $ ./a.out '%5m'
           Result string is "00011"
           $ ./a.out '%_5m'
           Result string is "   11"

       Here's the program source:

       #include <time.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           char outstr[200];
           time_t t;
           struct tm *tmp;

           t = time(NULL);
           tmp = localtime(&t);
           if (tmp == NULL) {
               perror("localtime");
               exit(EXIT_FAILURE);
           }

           if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
               fprintf(stderr, "strftime returned 0");
               exit(EXIT_FAILURE);
           }

           printf("Result string is \"%s\"\n", outstr);
           exit(EXIT_SUCCESS);
       }

SEE ALSO          top
       date(1), time(2), ctime(3), setlocale(3), sprintf(3), strptime(3)

COLOPHON          top
       This page is part of release 3.45 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/.

GNU                                 2012-05-10                         STRFTIME(3)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


string(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

STRING(3)                    Linux Programmer's Manual                   STRING(3)

NAME top

       stpcpy,  strcasecmp,  strcat,  strchr,  strcmp,  strcoll,  strcpy, strcspn,
       strdup, strfry, strlen, strncat, strncmp,  strncpy,  strncasecmp,  strpbrk,
       strrchr,  strsep,  strspn,  strstr, strtok, strxfrm, index, rindex - string
       operations

SYNOPSIS top

       #include <strings.h>

       int strcasecmp(const char *s1, const char *s2);

       int strncasecmp(const char *s1, const char *s2, size_t n);

       char *index(const char *s, int c);

       char *rindex(const char *s, int c);

       #include <string.h>

       char *stpcpy(char *dest, const char *src);

       char *strcat(char *dest, const char *src);

       char *strchr(const char *s, int c);

       int strcmp(const char *s1, const char *s2);

       int strcoll(const char *s1, const char *s2);

       char *strcpy(char *dest, const char *src);

       size_t strcspn(const char *s, const char *reject);

       char *strdup(const char *s);

       char *strfry(char *string);

       size_t strlen(const char *s);

       char *strncat(char *dest, const char *src, size_t n);

       int strncmp(const char *s1, const char *s2, size_t n);

       char *strncpy(char *dest, const char *src, size_t n);

       char *strpbrk(const char *s, const char *accept);

       char *strrchr(const char *s, int c);

       char *strsep(char **stringp, const char *delim);

       size_t strspn(const char *s, const char *accept);

       char *strstr(const char *haystack, const char *needle);

       char *strtok(char *s, const char *delim);

       size_t strxfrm(char *dest, const char *src, size_t n);

DESCRIPTION top

       The string functions perform string operations on null-terminated strings.
       See the individual man pages for descriptions of each function.

SEE ALSO top

       index(3), rindex(3), stpcpy(3), strcasecmp(3), strcat(3), strchr(3),
       strcmp(3), strcoll(3), strcpy(3), strcspn(3), strdup(3), strfry(3),
       strlen(3), strncasecmp(3), strncat(3), strncmp(3), strncpy(3), strpbrk(3),
       strrchr(3), strsep(3), strspn(3), strstr(3), strtok(3), strxfrm(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-02-25                           STRING(3)


strlen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRLEN(3)                    Linux Programmer's Manual                   STRLEN(3)

NAME top

       strlen - calculate the length of a string

SYNOPSIS top

       #include <string.h>

       size_t strlen(const char *s);

DESCRIPTION top

       The strlen() function calculates the length of the string s, excluding the
       terminating null byte ('\0').

RETURN VALUE top

       The strlen() function returns the number of bytes in the string s.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

SEE ALSO top

       string(3), strnlen(3), wcslen(3), wcsnlen(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-04                           STRLEN(3)


strnlen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRNLEN(3)                   Linux Programmer's Manual                  STRNLEN(3)

NAME top

       strnlen - determine the length of a fixed-size string

SYNOPSIS top

       #include <string.h>

       size_t strnlen(const char *s, size_t maxlen);

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

       strnlen():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The strnlen() function returns the number of bytes in the string pointed to
       by s, excluding the terminating null bye ('\0'), but at most maxlen.  In
       doing this, strnlen() looks only at the first maxlen bytes at s and never
       beyond s+maxlen.

RETURN VALUE top

       The strnlen() function returns strlen(s), if that is less than maxlen, or
       maxlen if there is no null byte ('\0') among the first maxlen bytes pointed
       to by s.

CONFORMING TO top

       POSIX.1-2008.

SEE ALSO top

       strlen(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                          STRNLEN(3)


strpbrk(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRPBRK(3)                   Linux Programmer's Manual                  STRPBRK(3)

NAME top

       strpbrk - search a string for any of a set of bytes

SYNOPSIS top

       #include <string.h>

       char *strpbrk(const char *s, const char *accept);

DESCRIPTION top

       The strpbrk() function locates the first occurrence in the string s of any
       of the bytes in the string accept.

RETURN VALUE top

       The strpbrk() function returns a pointer to the byte in s that matches one
       of the bytes in accept, or NULL if no such byte is found.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

SEE ALSO top

       index(3), memchr(3), rindex(3), strchr(3), string(3), strsep(3), strspn(3),
       strstr(3), strtok(3), wcspbrk(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-10                          STRPBRK(3)


strptime(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRPTIME(3)                  Linux Programmer's Manual                 STRPTIME(3)

NAME top

       strptime - convert a string representation of time to a time tm structure

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <time.h>

       char *strptime(const char *s, const char *format, struct tm *tm);

DESCRIPTION top

       The strptime() function is the converse function to strftime(3) and
       converts the character string pointed to by s to values which are stored in
       the tm structure pointed to by tm, using the format specified by format.
       Here format is a character string that consists of field descriptors and
       text characters, reminiscent of scanf(3).  Each field descriptor consists
       of a % character followed by another character that specifies the
       replacement for the field descriptor.  All other characters in the format
       string must have a matching character in the input string, except for
       whitespace, which matches zero or more whitespace characters in the input
       string.  There should be whitespace or other alphanumeric characters
       between any two field descriptors.

       The strptime() function processes the input string from left to right.
       Each of the three possible input elements (whitespace, literal, or format)
       are handled one after the other.  If the input cannot be matched to the
       format string the function stops.  The remainder of the format and input
       strings are not processed.

       The supported input field descriptors are listed below.  In case a text
       string (such as a weekday or month name) is to be matched, the comparison
       is case insensitive.  In case a number is to be matched, leading zeros are
       permitted but not required.

       %%     The % character.

       %a or %A
              The weekday name according to the current locale, in abbreviated
              form or the full name.

       %b or %B or %h
              The month name according to the current locale, in abbreviated form
              or the full name.

       %c     The date and time representation for the current locale.

       %C     The century number (0-99).

       %d or %e
              The day of month (1-31).

       %D     Equivalent to %m/%d/%y.  (This is the American style date, very
              confusing to non-Americans, especially since %d/%m/%y is widely used
              in Europe.  The ISO 8601 standard format is %Y-%m-%d.)

       %H     The hour (0-23).

       %I     The hour on a 12-hour clock (1-12).

       %j     The day number in the year (1-366).

       %m     The month number (1-12).

       %M     The minute (0-59).

       %n     Arbitrary whitespace.

       %p     The locale's equivalent of AM or PM.  (Note: there may be none.)

       %r     The 12-hour clock time (using the locale's AM or PM).  In the POSIX
              locale equivalent to %I:%M:%S %p.  If t_fmt_ampm is empty in the
              LC_TIME part of the current locale then the behavior is undefined.

       %R     Equivalent to %H:%M.

       %S     The second (0-60; 60 may occur for leap seconds; earlier also 61 was
              allowed).

       %t     Arbitrary whitespace.

       %T     Equivalent to %H:%M:%S.

       %U     The week number with Sunday the first day of the week (0-53).  The
              first Sunday of January is the first day of week 1.

       %w     The weekday number (0-6) with Sunday = 0.

       %W     The week number with Monday the first day of the week (0-53).  The
              first Monday of January is the first day of week 1.

       %x     The date, using the locale's date format.

       %X     The time, using the locale's time format.

       %y     The year within century (0-99).  When a century is not otherwise
              specified, values in the range 69-99 refer to years in the twentieth
              century (1969-1999); values in the range 00-68 refer to years in the
              twenty-first century (2000-2068).

       %Y     The year, including century (for example, 1991).

       Some field descriptors can be modified by the E or O modifier characters to
       indicate that an alternative format or specification should be used.  If
       the alternative format or specification does not exist in the current
       locale, the unmodified field descriptor is used.

       The E modifier specifies that the input string may contain alternative
       locale-dependent versions of the date and time representation:

       %Ec    The locale's alternative date and time representation.

       %EC    The name of the base year (period) in the locale's alternative
              representation.

       %Ex    The locale's alternative date representation.

       %EX    The locale's alternative time representation.

       %Ey    The offset from %EC (year only) in the locale's alternative
              representation.

       %EY    The full alternative year representation.

       The O modifier specifies that the numerical input may be in an alternative
       locale-dependent format:

       %Od or %Oe
              The day of the month using the locale's alternative numeric symbols;
              leading zeros are permitted but not required.

       %OH    The hour (24-hour clock) using the locale's alternative numeric
              symbols.

       %OI    The hour (12-hour clock) using the locale's alternative numeric
              symbols.

       %Om    The month using the locale's alternative numeric symbols.

       %OM    The minutes using the locale's alternative numeric symbols.

       %OS    The seconds using the locale's alternative numeric symbols.

       %OU    The week number of the year (Sunday as the first day of the week)
              using the locale's alternative numeric symbols.

       %Ow    The number of the weekday (Sunday=0) using the locale's alternative
              numeric symbols.

       %OW    The week number of the year (Monday as the first day of the week)
              using the locale's alternative numeric symbols.

       %Oy    The year (offset from %C) using the locale's alternative numeric
              symbols.

       The broken-down time structure tm is defined in <time.h> as follows:

           struct tm {
               int tm_sec;        /* seconds */
               int tm_min;        /* minutes */
               int tm_hour;       /* hours */
               int tm_mday;       /* day of the month */
               int tm_mon;        /* month */
               int tm_year;       /* year */
               int tm_wday;       /* day of the week */
               int tm_yday;       /* day in the year */
               int tm_isdst;      /* daylight saving time */
           };

RETURN VALUE top

       The return value of the function is a pointer to the first character not
       processed in this function call.  In case the input string contains more
       characters than required by the format string the return value points right
       after the last consumed input character.  In case the whole input string is
       consumed the return value points to the null byte at the end of the string.
       If strptime() fails to match all of the format string and therefore an
       error occurred the function returns NULL.

CONFORMING TO top

       SUSv2, POSIX.1-2001.

NOTES top

       In principle, this function does not initialize tm but only stores the
       values specified.  This means that tm should be initialized before the
       call.  Details differ a bit between different UNIX systems.  The glibc
       implementation does not touch those fields which are not explicitly
       specified, except that it recomputes the tm_wday and tm_yday field if any
       of the year, month, or day elements changed.

       This function is available since libc 4.6.8.  Linux libc4 and libc5
       includes define the prototype unconditionally; glibc2 includes provide a
       prototype only when _XOPEN_SOURCE or _GNU_SOURCE are defined.

       Before libc 5.4.13 whitespace (and the 'n' and 't' specifications) was not
       handled, no 'E' and 'O' locale modifier characters were accepted, and the
       'C' specification was a synonym for the 'c' specification.

       The 'y' (year in century) specification is taken to specify a year in the
       20th century by libc4 and libc5.  It is taken to be a year in the range
       1950-2049 by glibc 2.0.  It is taken to be a year in 1969-2068 since glibc
       2.1.

Glibc Notes

       For reasons of symmetry, glibc tries to support for strptime() the same
       format characters as for strftime(3).  (In most cases the corresponding
       fields are parsed, but no field in tm is changed.)  This leads to

       %F     Equivalent to %Y-%m-%d, the ISO 8601 date format.

       %g     The year corresponding to the ISO week number, but without the
              century (0-99).

       %G     The year corresponding to the ISO week number.  (For example, 1991.)

       %u     The day of the week as a decimal number (1-7, where Monday = 1).

       %V     The ISO 8601:1988 week number as a decimal number (1-53).  If the
              week (starting on Monday) containing 1 January has four or more days
              in the new year, then it is considered week 1.  Otherwise, it is the
              last week of the previous year, and the next week is week 1.

       %z     An RFC-822/ISO 8601 standard timezone specification.

       %Z     The timezone name.

       Similarly, because of GNU extensions to strftime(3), %k is accepted as a
       synonym for %H, and %l should be accepted as a synonym for %I, and %P is
       accepted as a synonym for %p.  Finally

       %s     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
              (UTC).  Leap seconds are not counted unless leap second support is
              available.

       The glibc implementation does not require whitespace between two field
       descriptors.

EXAMPLE top

       The following example demonstrates the use of strptime() and strftime(3).

       #define _XOPEN_SOURCE
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #include <time.h>

       int
       main(void)
       {
           struct tm tm;
           char buf[255];

           memset(&tm, 0, sizeof(struct tm));
           strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);
           strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
           puts(buf);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       time(2), getdate(3), scanf(3), setlocale(3), strftime(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-12-05                         STRPTIME(3)


strsep(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

STRSEP(3)                    Linux Programmer's Manual                   STRSEP(3)

NAME top

       strsep - extract token from string

SYNOPSIS top

       #include <string.h>

       char *strsep(char **stringp, const char *delim);

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

       strsep(): _BSD_SOURCE

DESCRIPTION top

       If *stringp is NULL, the strsep() function returns NULL and does nothing
       else.  Otherwise, this function finds the first token in the string
       *stringp, where tokens are delimited by symbols in the string delim.  This
       token is terminated by overwriting the delimiter with a null byte ('\0')
       and *stringp is updated to point past the token.  In case no delimiter was
       found, the token is taken to be the entire string *stringp, and *stringp is
       made NULL.

RETURN VALUE top

       The strsep() function returns a pointer to the token, that is, it returns
       the original value of *stringp.

CONFORMING TO top

       4.4BSD.

NOTES top

       The strsep() function was introduced as a replacement for strtok(3), since
       the latter cannot handle empty fields.  However, strtok(3) conforms to
       C89/C99 and hence is more portable.

BUGS top

       Be cautious when using this function.  If you do use it, note that:

       * This function modifies its first argument.

       * This function cannot be used on constant strings.

       * The identity of the delimiting character is lost.

SEE ALSO top

       index(3), memchr(3), rindex(3), strchr(3), string(3), strpbrk(3),
       strspn(3), strstr(3), strtok(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           STRSEP(3)


strsignal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRSIGNAL(3)                 Linux Programmer's Manual                STRSIGNAL(3)

NAME top

       strsignal - return string describing signal

SYNOPSIS top

       #include <string.h>

       char *strsignal(int sig);

       extern const char * const sys_siglist[];

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

       strsignal():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The strsignal() function returns a string describing the signal number
       passed in the argument sig.  The string can only be used until the next
       call to strsignal().

       The array sys_siglist holds the signal description strings indexed by
       signal number.  The strsignal() function should be used if possible instead
       of this array.

RETURN VALUE top

       The strsignal() function returns the appropriate description string, or an
       unknown signal message if the signal number is invalid.  On some systems
       (but not on Linux), a NULL pointer may be returned instead for an invalid
       signal number.

CONFORMING TO top

       POSIX.1-2008.  Present on Solaris and the BSDs.

SEE ALSO top

       psignal(3), strerror(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-15                        STRSIGNAL(3)


strtod(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRTOD(3)                    Linux Programmer's Manual                   STRTOD(3)

NAME top

       strtod, strtof, strtold - convert ASCII string to floating-point number

SYNOPSIS top

       #include <stdlib.h>

       double strtod(const char *nptr, char **endptr);
       float strtof(const char *nptr, char **endptr);
       long double strtold(const char *nptr, char **endptr);

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

       strtof(), strtold():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The strtod(), strtof(), and strtold() functions convert the initial portion
       of the string pointed to by nptr to double, float, and long double
       representation, respectively.

       The expected form of the (initial portion of the) string is optional
       leading white space as recognized by isspace(3), an optional plus ('+') or
       minus sign ('-') and then either (i) a decimal number, or (ii) a
       hexadecimal number, or (iii) an infinity, or (iv) a NAN (not-a-number).

       A decimal number consists of a nonempty sequence of decimal digits possibly
       containing a radix character (decimal point, locale-dependent, usually
       '.'), optionally followed by a decimal exponent.  A decimal exponent
       consists of an 'E' or 'e', followed by an optional plus or minus sign,
       followed by a nonempty sequence of decimal digits, and indicates
       multiplication by a power of 10.

       A hexadecimal number consists of a "0x" or "0X" followed by a nonempty
       sequence of hexadecimal digits possibly containing a radix character,
       optionally followed by a binary exponent.  A binary exponent consists of a
       'P' or 'p', followed by an optional plus or minus sign, followed by a
       nonempty sequence of decimal digits, and indicates multiplication by a
       power of 2.  At least one of radix character and binary exponent must be
       present.

       An infinity is either "INF" or "INFINITY", disregarding case.

       A NAN is "NAN" (disregarding case) optionally followed by '(', a sequence
       of characters, followed by ')'.  The character string specifies in an
       implementation-dependent way the type of NAN.

RETURN VALUE top

       These functions return the converted value, if any.

       If endptr is not NULL, a pointer to the character after the last character
       used in the conversion is stored in the location referenced by endptr.

       If no conversion is performed, zero is returned and the value of nptr is
       stored in the location referenced by endptr.

       If the correct value would cause overflow, plus or minus HUGE_VAL
       (HUGE_VALF, HUGE_VALL) is returned (according to the sign of the value),
       and ERANGE is stored in errno.  If the correct value would cause underflow,
       zero is returned and ERANGE is stored in errno.

ERRORS top

       ERANGE Overflow or underflow occurred.

CONFORMING TO top

       C89 describes strtod(), C99 describes the other two functions.

NOTES top

       Since 0 can legitimately be returned on both success and failure, the
       calling program should set errno to 0 before the call, and then determine
       if an error occurred by checking whether errno has a nonzero value after
       the call.

EXAMPLE top

       See the example on the strtol(3) manual page; the use of the functions
       described in this manual page is similar.

SEE ALSO top

       atof(3), atoi(3), atol(3), strtol(3), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                           STRTOD(3)


strtoimax(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRTOIMAX(3)                 Linux Programmer's Manual                STRTOIMAX(3)

NAME top

       strtoimax, strtoumax - convert string to integer

SYNOPSIS top

       #include <inttypes.h>

       intmax_t strtoimax(const char *nptr, char **endptr, int base);
       uintmax_t strtoumax(const char *nptr, char **endptr, int base);

DESCRIPTION top

       These functions are just like strtol(3) and strtoul(3), except that they
       return a value of type intmax_t and uintmax_t, respectively.

RETURN VALUE top

       On success, the converted value is returned.  If nothing was found to
       convert, zero is returned.  On overflow or underflow INTMAX_MAX or
       INTMAX_MIN or UINTMAX_MAX is returned, and errno is set to ERANGE.

CONFORMING TO top

       C99, POSIX.1-2001.

SEE ALSO top

       imaxabs(3), imaxdiv(3), strtol(3), strtoul(3), wcstoimax(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2003-11-28                        STRTOIMAX(3)


strtok(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRTOK(3)                    Linux Programmer's Manual                   STRTOK(3)

NAME top

       strtok, strtok_r - extract tokens from strings

SYNOPSIS top

       #include <string.h>

       char *strtok(char *str, const char *delim);

       char *strtok_r(char *str, const char *delim, char **saveptr);

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

       strtok_r(): _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE >= 1 ||
       _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION top

       The strtok() function parses a string into a sequence of tokens.  On the
       first call to strtok() the string to be parsed should be specified in str.
       In each subsequent call that should parse the same string, str should be
       NULL.

       The delim argument specifies a set of bytes that delimit the tokens in the
       parsed string.  The caller may specify different strings in delim in
       successive calls that parse the same string.

       Each call to strtok() returns a pointer to a null-terminated string
       containing the next token.  This string does not include the delimiting
       byte.  If no more tokens are found, strtok() returns NULL.

       A sequence of two or more contiguous delimiter bytes in the parsed string
       is considered to be a single delimiter.  Delimiter bytes at the start or
       end of the string are ignored.  Put another way: the tokens returned by
       strtok() are always nonempty strings.

       The strtok_r() function is a reentrant version strtok().  The saveptr
       argument is a pointer to a char * variable that is used internally by
       strtok_r() in order to maintain context between successive calls that parse
       the same string.

       On the first call to strtok_r(), str should point to the string to be
       parsed, and the value of saveptr is ignored.  In subsequent calls, str
       should be NULL, and saveptr should be unchanged since the previous call.

       Different strings may be parsed concurrently using sequences of calls to
       strtok_r() that specify different saveptr arguments.

RETURN VALUE top

       The strtok() and strtok_r() functions return a pointer to the next token,
       or NULL if there are no more tokens.

CONFORMING TO top

       strtok()
              SVr4, POSIX.1-2001, 4.3BSD, C89, C99.

       strtok_r()
              POSIX.1-2001.

BUGS top

       Be cautious when using these functions.  If you do use them, note that:

       * These functions modify their first argument.

       * These functions cannot be used on constant strings.

       * The identity of the delimiting byte is lost.

       * The strtok() function uses a static buffer while parsing, so it's not
         thread safe.  Use strtok_r() if this matters to you.

EXAMPLE top

       The program below uses nested loops that employ strtok_r() to break a
       string into a two-level hierarchy of tokens.  The first command-line
       argument specifies the string to be parsed.  The second argument specifies
       the delimiter byte(s) to be used to separate that string into "major"
       tokens.  The third argument specifies the delimiter byte(s) to be used to
       separate the "major" tokens into subtokens.

       An example of the output produced by this program is the following:

           $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
           1: a/bbb///cc
                    --> a
                    --> bbb
                    --> cc
           2: xxx
                    --> xxx
           3: yyy
                    --> yyy

Program source

       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           char *str1, *str2, *token, *subtoken;
           char *saveptr1, *saveptr2;
           int j;

           if (argc != 4) {
               fprintf(stderr, "Usage: %s string delim subdelim\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
               token = strtok_r(str1, argv[2], &saveptr1);
               if (token == NULL)
                   break;
               printf("%d: %s\n", j, token);

               for (str2 = token; ; str2 = NULL) {
                   subtoken = strtok_r(str2, argv[3], &saveptr2);
                   if (subtoken == NULL)
                       break;
                   printf(" --> %s\n", subtoken);
               }
           }

           exit(EXIT_SUCCESS);
       }

       Another example program using strtok() can be found in getaddrinfo_a(3).

SEE ALSO top

       index(3), memchr(3), rindex(3), strchr(3), string(3), strpbrk(3),
       strsep(3), strspn(3), strstr(3), wcstok(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                           STRTOK(3)


strtol(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRTOL(3)                    Linux Programmer's Manual                   STRTOL(3)

NAME top

       strtol, strtoll, strtoq - convert a string to a long integer

SYNOPSIS top

       #include <stdlib.h>

       long int strtol(const char *nptr, char **endptr, int base);

       long long int strtoll(const char *nptr, char **endptr, int base);

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

       strtoll():
           XOPEN_SOURCE >= 600 || _BSD_SOURCE || _SVID_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The strtol() function converts the initial part of the string in nptr to a
       long integer value according to the given base, which must be between 2 and
       36 inclusive, or be the special value 0.

       The string may begin with an arbitrary amount of white space (as determined
       by isspace(3)) followed by a single optional '+' or '-' sign.  If base is
       zero or 16, the string may then include a "0x" prefix, and the number will
       be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless
       the next character is '0', in which case it is taken as 8 (octal).

       The remainder of the string is converted to a long int value in the obvious
       manner, stopping at the first character which is not a valid digit in the
       given base.  (In bases above 10, the letter 'A' in either upper or lower
       case represents 10, 'B' represents 11, and so forth, with 'Z' representing
       35.)

       If endptr is not NULL, strtol() stores the address of the first invalid
       character in *endptr.  If there were no digits at all, strtol() stores the
       original value of nptr in *endptr (and returns 0).  In particular, if *nptr
       is not '\0' but **endptr is '\0' on return, the entire string is valid.

       The strtoll() function works just like the strtol() function but returns a
       long long integer value.

RETURN VALUE top

       The strtol() function returns the result of the conversion, unless the
       value would underflow or overflow.  If an underflow occurs, strtol()
       returns LONG_MIN.  If an overflow occurs, strtol() returns LONG_MAX.  In
       both cases, errno is set to ERANGE.  Precisely the same holds for strtoll()
       (with LLONG_MIN and LLONG_MAX instead of LONG_MIN and LONG_MAX).

ERRORS top

       EINVAL (not in C99) The given base contains an unsupported value.

       ERANGE The resulting value was out of range.

       The implementation may also set errno to EINVAL in case no conversion was
       performed (no digits seen, and 0 returned).

CONFORMING TO top

       strtol() conforms to SVr4, 4.3BSD, C89, C99 and POSIX.1-2001, and strtoll()
       to C99 and POSIX.1-2001.

NOTES top

       Since strtol() can legitimately return 0, LONG_MAX, or LONG_MIN (LLONG_MAX
       or LLONG_MIN for strtoll()) on both success and failure, the calling
       program should set errno to 0 before the call, and then determine if an
       error occurred by checking whether errno has a nonzero value after the
       call.

       In locales other than the "C" locale, other strings may also be accepted.
       (For example, the thousands separator of the current locale may be
       supported.)

       BSD also has

           quad_t strtoq(const char *nptr, char **endptr, int base);

       with completely analogous definition.  Depending on the wordsize of the
       current architecture, this may be equivalent to strtoll() or to strtol().

EXAMPLE top

       The program shown below demonstrates the use of strtol().  The first
       command-line argument specifies a string from which strtol() should parse a
       number.  The second (optional) argument specifies the base to be used for
       the conversion.  (This argument is converted to numeric form using atoi(3),
       a function that performs no error checking and has a simpler interface than
       strtol().)  Some examples of the results produced by this program are the
       following:

           $ ./a.out 123
           strtol() returned 123
           $ ./a.out '    123'
           strtol() returned 123
           $ ./a.out 123abc
           strtol() returned 123
           Further characters after number: abc
           $ ./a.out 123abc 55
           strtol: Invalid argument
           $ ./a.out ''
           No digits were found
           $ ./a.out 4000000000
           strtol: Numerical result out of range

Program source

       #include <stdlib.h>
       #include <limits.h>
       #include <stdio.h>
       #include <errno.h>

       int
       main(int argc, char *argv[])
       {
           int base;
           char *endptr, *str;
           long val;

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

           str = argv[1];
           base = (argc > 2) ? atoi(argv[2]) : 10;

           errno = 0;    /* To distinguish success/failure after call */
           val = strtol(str, &endptr, base);

           /* Check for various possible errors */

           if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN))
                   || (errno != 0 && val == 0)) {
               perror("strtol");
               exit(EXIT_FAILURE);
           }

           if (endptr == str) {
               fprintf(stderr, "No digits were found\n");
               exit(EXIT_FAILURE);
           }

           /* If we got here, strtol() successfully parsed a number */

           printf("strtol() returned %ld\n", val);

           if (*endptr != '\0')        /* Not necessarily an error... */
               printf("Further characters after number: %s\n", endptr);

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       atof(3), atoi(3), atol(3), strtod(3), strtoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           STRTOL(3)


strtoul(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

STRTOUL(3)                   Linux Programmer's Manual                  STRTOUL(3)

NAME top

       strtoul, strtoull, strtouq - convert a string to an unsigned long integer

SYNOPSIS top

       #include <stdlib.h>

       unsigned long int strtoul(const char *nptr, char **endptr, int base);

       unsigned long long int strtoull(const char *nptr, char **endptr,
                                       int base);

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

       strtoull():
           XOPEN_SOURCE >= 600 || _BSD_SOURCE || _SVID_SOURCE || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The strtoul() function converts the initial part of the string in nptr to
       an unsigned long int value according to the given base, which must be
       between 2 and 36 inclusive, or be the special value 0.

       The string may begin with an arbitrary amount of white space (as determined
       by isspace(3)) followed by a single optional '+' or '-' sign.  If base is
       zero or 16, the string may then include a "0x" prefix, and the number will
       be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless
       the next character is '0', in which case it is taken as 8 (octal).

       The remainder of the string is converted to an unsigned long int value in
       the obvious manner, stopping at the first character which is not a valid
       digit in the given base.  (In bases above 10, the letter 'A' in either
       upper or lower case represents 10, 'B' represents 11, and so forth, with
       'Z' representing 35.)

       If endptr is not NULL, strtoul() stores the address of the first invalid
       character in *endptr.  If there were no digits at all, strtoul() stores the
       original value of nptr in *endptr (and returns 0).  In particular, if *nptr
       is not '\0' but **endptr is '\0' on return, the entire string is valid.

       The strtoull() function works just like the strtoul() function but returns
       an unsigned long long int value.

RETURN VALUE top

       The strtoul() function returns either the result of the conversion or, if
       there was a leading minus sign, the negation of the result of the
       conversion represented as an unsigned value, unless the original
       (nonnegated) value would overflow; in the latter case, strtoul() returns
       ULONG_MAX and sets errno to ERANGE.  Precisely the same holds for
       strtoull() (with ULLONG_MAX instead of ULONG_MAX).

ERRORS top

       EINVAL (not in C99) The given base contains an unsupported value.

       ERANGE The resulting value was out of range.

       The implementation may also set errno to EINVAL in case no conversion was
       performed (no digits seen, and 0 returned).

CONFORMING TO top

       strtoul() conforms to SVr4, C89, C99 and POSIX-2001, and strtoull() to C99
       and POSIX.1-2001.

NOTES top

       Since strtoul() can legitimately return 0 or ULONG_MAX (ULLONG_MAX for
       strtoull()) on both success and failure, the calling program should set
       errno to 0 before the call, and then determine if an error occurred by
       checking whether errno has a nonzero value after the call.

       In locales other than the "C" locale, other strings may be accepted.  (For
       example, the thousands separator of the current locale may be supported.)

       BSD also has

           u_quad_t strtouq(const char *nptr, char **endptr, int base);

       with completely analogous definition.  Depending on the wordsize of the
       current architecture, this may be equivalent to strtoull() or to strtoul().

       Negative values are considered valid input and are silently converted to
       the equivalent unsigned long int value.

EXAMPLE top

       See the example on the strtol(3) manual page; the use of the functions
       described in this manual page is similar.

SEE ALSO top

       atof(3), atoi(3), atol(3), strtod(3), strtol(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-15                          STRTOUL(3)


strverscmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

STRVERSCMP(3)                Linux Programmer's Manual               STRVERSCMP(3)

NAME top

       strverscmp - compare two version strings

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <string.h>

       int strverscmp(const char *s1, const char *s2);

DESCRIPTION top

       Often one has files jan1, jan2, ..., jan9, jan10, ...  and it feels wrong
       when ls(1) orders them jan1, jan10, ..., jan2, ..., jan9.  In order to
       rectify this, GNU introduced the -v option to ls(1), which is implemented
       using versionsort(3), which again uses strverscmp().

       Thus, the task of strverscmp() is to compare two strings and find the
       "right" order, while strcmp(3) only finds the lexicographic order.  This
       function does not use the locale category LC_COLLATE, so is meant mostly
       for situations where the strings are expected to be in ASCII.

       What this function does is the following.  If both strings are equal,
       return 0.  Otherwise find the position between two bytes with the property
       that before it both strings are equal, while directly after it there is a
       difference.  Find the largest consecutive digit strings containing (or
       starting at, or ending at) this position.  If one or both of these is
       empty, then return what strcmp(3) would have returned (numerical ordering
       of byte values).  Otherwise, compare both digit strings numerically, where
       digit strings with one or more leading zeros are interpreted as if they
       have a decimal point in front (so that in particular digit strings with
       more leading zeros come before digit strings with fewer leading zeros).
       Thus, the ordering is 000, 00, 01, 010, 09, 0, 1, 9, 10.

RETURN VALUE top

       The strverscmp() function returns an integer less than, equal to, or
       greater than zero if s1 is found, respectively, to be earlier than, equal
       to, or later than s2.

CONFORMING TO top

       This function is a GNU extension.

SEE ALSO top

       rename(1), strcasecmp(3), strcmp(3), strcoll(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2001-12-19                       STRVERSCMP(3)


strxfrm(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

STRXFRM(3)                   Linux Programmer's Manual                  STRXFRM(3)

NAME top

       strxfrm - string transformation

SYNOPSIS top

       #include <string.h>

       size_t strxfrm(char *dest, const char *src, size_t n);

DESCRIPTION top

       The strxfrm() function transforms the src string into a form such that the
       result of strcmp(3) on two strings that have been transformed with
       strxfrm() is the same as the result of strcoll(3) on the two strings before
       their transformation.  The first n bytes of the transformed string are
       placed in dest.  The transformation is based on the program's current
       locale for category LC_COLLATE.  (See setlocale(3)).

RETURN VALUE top

       The strxfrm() function returns the number of bytes required to store the
       transformed string in dest excluding the terminating null byte ('\0').  If
       the value returned is n or more, the contents of dest are indeterminate.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99.

NOTES top

       In the "POSIX" or "C" locales strxfrm() is equivalent to copying the string
       with strncpy(3).

SEE ALSO top

       bcmp(3), memcmp(3), setlocale(3), strcasecmp(3), strcmp(3), strcoll(3),
       string(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-05-10                          STRXFRM(3)


subpage_prot(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SUBPAGE_PROT(2)              Linux Programmer's Manual             SUBPAGE_PROT(2)

NAME top

       subpage_prot - define a subpage protection for an address range

SYNOPSIS top

       long subpage_prot(unsigned long addr, unsigned long len,
                         uint32_t *map);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       The PowerPC-specific subpage_prot() system call provides the facility to
       control the access permissions on individual 4kB subpages on systems
       configured with a page size of 64kB.

       The protection map is applied to the memory pages in the region starting at
       addr and continuing for len bytes.  Both of these arguments must be aligned
       to a 64-kB boundary.

       The protection map is specified in the buffer pointed to by map.  The map
       has 2 bits per 4kB subpage; thus each 32-bit word specifies the protections
       of 16 4kB subpages inside a 64kB page (so, the number of 32-bit words
       pointed to by map should equate to the number of 64-kB pages specified by
       len).  Each 2-bit field in the protection map is either 0 to allow any
       access, 1 to prevent writes, or 2 or 3 to prevent all accesses.

RETURN VALUE top

       On success, subpage_prot() returns 0.  Otherwise, one of the error codes
       specified below is returned.

ERRORS top

       EFAULT The buffer referred to by map is not accessible.

       EINVAL The addr or len arguments are incorrect.  Both of these arguments
              must be aligned to a multiple of the system page size, and they must
              not refer to a region outside of the address space of the process or
              to a region that consists of huge pages.

       ENOMEM Out of memory.

VERSIONS top

       This system call is provided on the PowerPC architecture since Linux
       2.6.25.  The system call is provided only if the kernel is configured with
       CONFIG_PPC_64K_PAGES.  No library support is provided.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).

       Normal page protections (at the 64-kB page level) also apply; the subpage
       protection mechanism is an additional constraint, so putting 0 in a 2-bit
       field won't allow writes to a page that is otherwise write-protected.

Rationale

       This system call is provided to assist writing emulators that operate using
       64-kB pages on PowerPC systems.  When emulating systems such as x86, which
       uses a smaller page size, the emulator can no longer use the memory-
       management unit (MMU) and normal system calls for controlling page
       protections.  (The emulator could emulate the MMU by checking and possibly
       remapping the address for each memory access in software, but that is
       slow.)  The idea is that the emulator supplies an array of protection masks
       to apply to a specified range of virtual addresses.  These masks are
       applied at the level where hardware page-table entries (PTEs) are inserted
       into the hardware page table based on the Linux PTEs, so the Linux PTEs are
       not affected.  Implicit in this is that the regions of the address space
       that are protected are switched to use 4-kB hardware pages rather than
       64-kB hardware pages (on machines with hardware 64-kB page support).

SEE ALSO top

       mprotect(2), syscall(2)

       Documentation/vm/hugetlbpage.txt in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                     SUBPAGE_PROT(2)


suffixes(7) - Linux manual page

NAME | DESCRIPTION | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SUFFIXES(7)                  Linux Programmer's Manual                 SUFFIXES(7)

NAME top

       suffixes - list of file suffixes

DESCRIPTION top

       It is customary to indicate the contents of a file with the file suffix,
       which consists of a period, followed by one or more letters.  Many standard
       utilities, such as compilers, use this to recognize the type of file they
       are dealing with.  The make(1) utility is driven by rules based on file
       suffix.

       Following is a list of suffixes which are likely to be found on a Linux
       system.
                     |
       Suffix        | File type
       --------------+-----------------------------------------------------
        ,v           | files for RCS (Revision Control System)
        -            | backup file
        .C           | C++ source code, equivalent to .cc
        .F           | Fortran source with cpp(1) directives
                     | or file compressed using freeze
        .S           | assembler source with cpp(1) directives
        .Y           | file compressed using yabba
        .Z           | file compressed using compress(1)
        .[0-9]+gf    | TeX generic font files
        .[0-9]+pk    | TeX packed font files
        .[1-9]       | manual page for the corresponding section
        .[1-9][a-z]  | manual page for section plus subsection
        .a           | static object code library
        .ad          | X application default resource file
        .ada         | Ada source (may be body, spec, or combination)
        .adb         | Ada body source
        .ads         | Ada spec source
        .afm         | PostScript font metrics
        .al          | Perl autoload file
        .am          | automake(1) input file
        .arc         | arc(1) archive
        .arj         | arj(1) archive
        .asc         | PGP ASCII-armored data
        .asm         | (GNU) assembler source file
        .au          | Audio sound file
        .aux         | LaTeX auxiliary file
        .avi         | (msvideo) movie
        .awk         | AWK language program
        .b           | LILO boot loader image
        .bak         | backup file
        .bash        | bash(1) shell script
        .bb          | basic block list data produced by
                     | gcc -ftest-coverage
        .bbg         | basic block graph data produced by
                     | gcc -ftest-coverage
        .bbl         | BibTeX output
        .bdf         | X font file
        .bib         | TeX bibliographic database, BibTeX input
        .bm          | bitmap source
        .bmp         | bitmap
        .bz2         | file compressed using bzip2(1)
        .c           | C source
        .cat         | message catalog files
        .cc          | C++ source
        .cf          | configuration file
        .cfg         | configuration file
        .cgi         | WWW content generating script or program
        .cls         | LaTeX Class definition
        .class       | Java compiled byte-code
        .conf        | configuration file
        .config      | configuration file
        .cpp         | equivalent to .cc
        .csh         | csh(1) shell script
        .cxx         | equivalent to .cc
        .dat         | data file
        .deb         | Debian software package
        .def         | Modula-2 source for definition modules
        .def         | other definition files
        .desc        | initial part of mail message unpacked with
                     | munpack(1)
        .diff        | file differences (diff(1) command output)
        .dir         | dbm data base directory file
        .doc         | documentation file
        .dsc         | Debian Source Control (source package)
        .dtx         | LaTeX package source file
        .dvi         | TeX's device independent output
        .el          | Emacs-Lisp source
        .elc         | compiled Emacs-Lisp source
        .eps         | encapsulated PostScript
        .exp         | Expect source code
        .f           | Fortran source
        .f77         | Fortran 77 source
        .f90         | Fortran 90 source
        .fas         | precompiled Common-Lisp
        .fi          | Fortran include files
        .fig         | FIG image file (used by xfig(1))
        .fmt         | TeX format file
        .gif         | Compuserve Graphics Image File format
        .gmo         | GNU format message catalog
        .gsf         | Ghostscript fonts
        .gz          | file compressed using gzip(1)
        .h           | C or C++ header files
        .help        | help file
        .hf          | equivalent to .help
        .hlp         | equivalent to .help
        .htm         | poor man's .html
        .html        | HTML document used with the World Wide Web
        .hqx         | 7-bit encoded Macintosh file
        .i           | C source after preprocessing
        .icon        | bitmap source
        .idx         | reference or datum-index file for hypertext
                     | or database system
        .image       | bitmap source
        .in          | configuration template, especially for GNU Autoconf
        .info        | files for the Emacs info browser
        .info-[0-9]+ | split info files
        .ins         | LaTeX package install file for docstrip
        .itcl        | itcl source code;
                     | itcl ([incr Tcl]) is an OO extension of tcl
        .java        | a Java source file
        .jpeg        | Joint Photographic Experts Group format
        .jpg         | poor man's .jpeg
        .kmap        | lyx(1) keymap
        .l           | equivalent to .lex or .lisp
        .lex         | lex(1) or flex(1) files
        .lha         | lharc archive
        .lib         | Common-Lisp library
        .lisp        | Lisp source
        .ln          | files for use with lint(1)
        .log         | log file, in particular produced by TeX
        .lsm         | Linux Software Map entry
        .lsp         | Common-Lisp source
        .lzh         | lharc archive
        .m           | Objective-C source code
        .m4          | m4(1) source
        .mac         | macro files for various programs
        .man         | manual page (usually source rather than formatted)
        .map         | map files for various programs
        .me          | Nroff source using the me macro package
        .mf          | Metafont (font generator for TeX) source
        .mgp         | MagicPoint file
        .mm          | sources for groff(1) in mm - format
        .mo          | Message catalog binary file
        .mod         | Modula-2 source for implementation modules
        .mov         | (quicktime) movie
        .mp          | Metapost source
        .mp2         | MPEG Layer 2 (audio) file
        .mp3         | MPEG Layer 3 (audio) file
        .mpeg        | movie file
        .o           | object file
        .old         | old or backup file
        .orig        | backup (original) version of a file, from patch(1)
        .out         | output file, often executable program (a.out)
        .p           | Pascal source
        .pag         | dbm data base data file
        .patch       | file differences for patch(1)
        .pbm         | portable bitmap format
        .pcf         | X11 font files
        .pdf         | Adobe Portable Data Format
                     | (use Acrobat/acroread or xpdf)
        .perl        | Perl source (see .ph, .pl and .pm)
        .pfa         | PostScript font definition files, ASCII format
        .pfb         | PostScript font definition files, binary format
        .pgm         | portable greymap format
        .pgp         | PGP binary data
        .ph          | Perl header file
        .php         | PHP program file
        .php3        | PHP3 program file
        .pid         | File to store daemon PID (e.g., crond.pid)
        .pl          | TeX property list file or Perl library file
        .pm          | Perl module
        .png         | Portable Network Graphics file
        .po          | Message catalog source
        .pod         | perldoc(1) file
        .ppm         | portable pixmap format
        .pr          | bitmap source
        .ps          | PostScript file
        .py          | Python source
        .pyc         | compiled python
        .qt          | quicktime movie
        .r           | RATFOR source (obsolete)
        .rej         | patches that patch(1) couldn't apply
        .rpm         | RPM software package
        .rtf         | Rich Text Format file
        .rules       | rules for something
        .s           | assembler source
        .sa          | stub libraries for a.out shared libraries
        .sc          | sc(1) spreadsheet commands
        .scm         | Scheme source code
        .sed         | sed source file
        .sgml        | SGML source file
        .sh          | sh(1) scripts
        .shar        | archive created by the shar(1) utility
        .so          | Shared library or dynamically loadable object
        .sql         | SQL source
        .sqml        | SQML schema or query program
        .sty         | LaTeX style files
        .sym         | Modula-2 compiled definition modules
        .tar         | archive created by the tar(1) utility
        .tar.Z       | tar(1) archive compressed with compress(1)
        .tar.bz2     | tar(1) archive compressed with bzip2(1)
        .tar.gz      | tar(1) archive compressed with gzip(1)
        .taz         | tar(1) archive compressed with compress(1)
        .tcl         | tcl source code
        .tex         | TeX or LaTeX source
        .texi        | equivalent to .texinfo
        .texinfo     | Texinfo documentation source
        .text        | text file
        .tfm         | TeX font metric file
        .tgz         | tar archive compressed with gzip(1)
        .tif         | poor man's .tiff
        .tiff        | Tagged Image File Format
        .tk          | tcl/tk script
        .tmp         | temporary file
        .tmpl        | template files
        .txt         | equivalent to .text
        .uu          | equivalent to .uue
        .uue         | binary file encoded with uuencode(1)
        .vf          | TeX virtual font file
        .vpl         | TeX virtual property list file
        .w           | Silvio Levi's CWEB
        .wav         | wave sound file
        .web         | Donald Knuth's WEB
        .wml         | Source file for Web Meta Language
        .xbm         | X11 bitmap source
        .xcf         | GIMP graphic
        .xml         | eXtended Markup Language file
        .xpm         | X11 pixmap source
        .xs          | Perl xsub file produced by h2xs
        .xsl         | XSL stylesheet
        .y           | yacc(1) or bison(1) (parser generator) files
        .z           | File compressed using pack(1) (or an old gzip(1))
        .zip         | zip(1) archive
        .zoo         | zoo(1) archive
        ~            | Emacs or patch(1) backup file
        rc           | startup (`run control') file, e.g., .newsrc

CONFORMING TO top

       General UNIX conventions.

BUGS top

       This list is not exhaustive.

SEE ALSO top

       file(1), make(1)

COLOPHON top

       This page is part of release 3.45 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-11-16                         SUFFIXES(7)


swab(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SWAB(3)                      Linux Programmer's Manual                     SWAB(3)

NAME top

       swab - swap adjacent bytes

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <unistd.h>

       void swab(const void *from, void *to, ssize_t n);

DESCRIPTION top

       The swab() function copies n bytes from the array pointed to by from to the
       array pointed to by to, exchanging adjacent even and odd bytes.  This
       function is used to exchange data between machines that have different
       low/high byte ordering.

       This function does nothing when n is negative.  When n is positive and odd,
       it handles n-1 bytes as above, and does something unspecified with the last
       byte.  (In other words, n should be even.)

RETURN VALUE top

       The swab() function returns no value.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

SEE ALSO top

       bstring(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2001-12-15                             SWAB(3)


swapon(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SWAPON(2)                    Linux Programmer's Manual                   SWAPON(2)

NAME top

       swapon, swapoff - start/stop swapping to file/device

SYNOPSIS top

       #include <unistd.h>
       #include <asm/page.h> /* to find PAGE_SIZE */
       #include <sys/swap.h>

       int swapon(const char *path, int swapflags);
       int swapoff(const char *path);

DESCRIPTION top

       swapon() sets the swap area to the file or block device specified by path.
       swapoff() stops swapping to the file or block device specified by path.

       If the SWAP_FLAG_PREFER flag is specified in the swapon() swapflags
       argument, the new swap area will have a higher priority than default.  The
       priority is encoded within swapflags as:

           (prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK

       If the SWAP_FLAG_DISCARD flag is specified in the swapon() swapflags
       argument, freed swap pages will be discarded before they are reused, if the
       swap device supports the discard or trim operation.  (This may improve
       performance on some Solid State Devices, but often it does not.)  See also
       NOTES.

       These functions may only be used by a privileged process (one having the
       CAP_SYS_ADMIN capability).

Priority

       Each swap area has a priority, either high or low.  The default priority is
       low.  Within the low-priority areas, newer areas are even lower priority
       than older areas.

       All priorities set with swapflags are high-priority, higher than default.
       They may have any nonnegative value chosen by the caller.  Higher numbers
       mean higher priority.

       Swap pages are allocated from areas in priority order, highest priority
       first.  For areas with different priorities, a higher-priority area is
       exhausted before using a lower-priority area.  If two or more areas have
       the same priority, and it is the highest priority available, pages are
       allocated on a round-robin basis between them.

       As of Linux 1.3.6, the kernel usually follows these rules, but there are
       exceptions.

RETURN VALUE top

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

ERRORS top

       EBUSY  (for swapon()) The specified path is already being used as a swap
              area.

       EINVAL The file path exists, but refers neither to a regular file nor to a
              block device; or, for swapon(), the indicated path does not contain
              a valid swap signature or resides on an in-memory file system like
              tmpfs; or, for swapoff(), path is not currently a swap area.

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

       ENOENT The file path does not exist.

       ENOMEM The system has insufficient memory to start swapping.

       EPERM  The caller does not have the CAP_SYS_ADMIN capability.
              Alternatively, the maximum number of swap files are already in use;
              see NOTES below.

CONFORMING TO top

       These functions are Linux-specific and should not be used in programs
       intended to be portable.  The second swapflags argument was introduced in
       Linux 1.3.2.

NOTES top

       The partition or path must be prepared with mkswap(8).

       There is an upper limit on the number of swap files that may be used,
       defined by the kernel constant MAX_SWAPFILES.  Before kernel 2.4.10,
       MAX_SWAPFILES has the value 8; since kernel 2.4.10, it has the value 32.
       Since kernel 2.6.18, the limit is decreased by 2 (thus: 30) if the kernel
       is built with the CONFIG_MIGRATION option (which reserves two swap table
       entries for the page migration features of mbind(2) and migrate_pages(2)).
       Since kernel 2.6.32, the limit is further decreased by 1 if the kernel is
       built with the CONFIG_MEMORY_FAILURE option.

       Discard of swap pages was introduced in kernel 2.6.29, then made
       conditional on the SWAP_FLAG_DISCARD flag in kernel 2.6.36, which still
       discards the entire swap area when swapon() is called, even if that flag
       bit is not set.

SEE ALSO top

       mkswap(8), swapoff(8), swapon(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-11-15                           SWAPON(2)


symlink(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYMLINK(2)                   Linux Programmer's Manual                  SYMLINK(2)

NAME top

       symlink - make a new name for a file

SYNOPSIS top

       #include <unistd.h>

       int symlink(const char *oldpath, const char *newpath);

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

       symlink():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE >= 200112L

DESCRIPTION top

       symlink() creates a symbolic link named newpath which contains the string
       oldpath.

       Symbolic links are interpreted at run time as if the contents of the link
       had been substituted into the path being followed to find a file or
       directory.

       Symbolic links may contain ..  path components, which (if used at the start
       of the link) refer to the parent directories of that in which the link
       resides.

       A symbolic link (also known as a soft link) may point to an existing file
       or to a nonexistent one; the latter case is known as a dangling link.

       The permissions of a symbolic link are irrelevant; the ownership is ignored
       when following the link, but is checked when removal or renaming of the
       link is requested and the link is in a directory with the sticky bit
       (S_ISVTX) set.

       If newpath exists it will not be overwritten.

RETURN VALUE top

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

ERRORS top

       EACCES Write access to the directory containing newpath is denied, or one
              of the directories in the path prefix of newpath did not allow
              search permission.  (See also path_resolution(7).)

       EEXIST newpath already exists.

       EFAULT oldpath or newpath points outside your accessible address space.

       EIO    An I/O error occurred.

       ELOOP  Too many symbolic links were encountered in resolving newpath.

       ENAMETOOLONG
              oldpath or newpath was too long.

       ENOENT A directory component in newpath does not exist or is a dangling
              symbolic link, or oldpath is the empty string.

       ENOMEM Insufficient kernel memory was available.

       ENOSPC The device containing the file has no room for the new directory
              entry.

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

       EPERM  The file system containing newpath does not support the creation of
              symbolic links.

       EROFS  newpath is on a read-only file system.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       No checking of oldpath is done.

       Deleting the name referred to by a symlink will actually delete the file
       (unless it also has other hard links).  If this behavior is not desired,
       use link(2).

SEE ALSO top

       ln(1), lchown(2), link(2), lstat(2), open(2), readlink(2), rename(2),
       symlinkat(2), unlink(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-20                          SYMLINK(2)


symlink(7) - Linux manual page

NAME | SYMBOLIC LINK HANDLING | SEE ALSO | COLOPHON The Linux Programming Interface

SYMLINK(7)                   Linux Programmer's Manual                  SYMLINK(7)

NAME top

       symlink - symbolic link handling

SYMBOLIC LINK HANDLING top

       Symbolic  links  are  files that act as pointers to other files.  To under-
       stand their behavior, you must first understand how hard links work.

       A hard link to a file is indistinguishable from the original  file  because
       it  is  a reference to the object underlying the original filename.  (To be
       precise: each of the hard links to a file is a reference to the same i-node
       number,  where  an  i-node  number is an index into the i-node table, which
       contains metadata about all files on a file system.  See stat(2).)  Changes
       to  a  file  are  independent of the name used to reference the file.  Hard
       links may not refer to directories (to prevent  the  possibility  of  loops
       within the file system tree, which would confuse many programs) and may not
       refer to files on different file systems (because i-node  numbers  are  not
       unique across file systems).

       A  symbolic link is a special type of file whose contents are a string that
       is the pathname another file, the file to which the link refers.  In  other
       words, a symbolic link is a pointer to another name, and not to an underly-
       ing object.  For this reason, symbolic links may refer to  directories  and
       may cross file system boundaries.

       There  is  no  requirement that the pathname referred to by a symbolic link
       should exist.  A symbolic link that refers to  a  pathname  that  does  not
       exist is said to be a dangling link.

       Because  a symbolic link and its referenced object coexist in the file sys-
       tem name space, confusion can arise  in  distinguishing  between  the  link
       itself and the referenced object.  On historical systems, commands and sys-
       tem calls adopted their own link-following conventions in a somewhat ad-hoc
       fashion.   Rules  for  a  more uniform approach, as they are implemented on
       Linux and other systems, are outlined here.  It  is  important  that  site-
       local  applications also conform to these rules, so that the user interface
       can be as consistent as possible.

Symbolic link ownership, permissions, and timestamps

       The owner and group of an existing  symbolic  link  can  be  changed  using
       lchown(2).   The only time that the ownership of a symbolic link matters is
       when the link is being removed or renamed  in  a  directory  that  has  the
       sticky bit set (see stat(2)).

       The  last access and last modification timestamps of a symbolic link can be
       changed using utimensat(2) or lutimes(3).

       On Linux, the permissions of a symbolic link are not  used  in  any  opera-
       tions;  the  permissions  are always 0777 (read, write, and execute for all
       user categories), and can't be changed.

Handling of symbolic links by system calls and commands

       Symbolic links are handled either by operating on the link  itself,  or  by
       operating  on  the  object referred to by the link.  In the latter case, an
       application or system call is said to follow the link.  Symbolic links  may
       refer  to  other  symbolic  links, in which case the links are dereferenced
       until an object that is not a symbolic link is found, a symbolic link  that
       refers  to  a  file  which  does not exist is found, or a loop is detected.
       (Loop detection is done by placing an upper limit on the  number  of  links
       that may be followed, and an error results if this limit is exceeded.)

       There are three separate areas that need to be discussed.  They are as fol-
       lows:

       1. Symbolic links used as filename arguments for system calls.

       2. Symbolic links specified as command-line arguments to utilities that are
          not traversing a file tree.

       3. Symbolic  links encountered by utilities that are traversing a file tree
          (either specified on the command line or encountered as part of the file
          hierarchy walk).

System calls

       The  first  area  is  symbolic  links used as filename arguments for system
       calls.

       Except as noted below, all system calls follow symbolic links.   For  exam-
       ple,  if  there  were  a  symbolic link slink which pointed to a file named
       afile, the system call open("slink" ...) would  return  a  file  descriptor
       referring to the file afile.

       Various  system calls do not follow links, and operate on the symbolic link
       itself.  They are: lchown(2), lgetxattr(2), llistxattr(2), lremovexattr(2),
       lsetxattr(2),  lstat(2),  readlink(2),  rename(2), rmdir(2), and unlink(2).
       Certain other system calls optionally follow  symbolic  links.   They  are:
       faccessat(2),  fchownat(2),  fstatat(2), linkat(2), open(2), openat(2), and
       utimensat(2); see their manual pages for details.  Because remove(3) is  an
       alias  for  unlink(2),  that library function also does not follow symbolic
       links.  When rmdir(2) is applied to a symbolic  link,  it  fails  with  the
       error  ENOTDIR.   The  link(2)  warrants  special discussion.  POSIX.1-2001
       specifies that link(2) should dereference oldpath if it is a symbolic link.
       However,  Linux does not do this.  (By default Solaris is the same, but the
       POSIX.1-2001 specified behavior can  be  obtained  with  suitable  compiler
       options.)  The upcoming POSIX.1 revision changes the specification to allow
       either behavior in an implementation.

Commands not traversing a file tree

       The second area is symbolic links, specified as command-line filename argu-
       ments, to commands which are not traversing a file tree.

       Except as noted below, commands follow symbolic links named as command-line
       arguments.  For example, if there were a symbolic link slink which  pointed
       to  a file named afile, the command cat slink would display the contents of
       the file afile.

       It is important to realize that  this  rule  includes  commands  which  may
       optionally traverse file trees, e.g., the command chown file is included in
       this rule, while the command chown -R file, which performs a  tree  traver-
       sal, is not.  (The latter is described in the third area, below.)

       If  it is explicitly intended that the command operate on the symbolic link
       instead of following the symbolic link, e.g.,  it  is  desired  that  chown
       slink  change the ownership of the file that slink is, whether it is a sym-
       bolic link or not, the -h option should be used.   In  the  above  example,
       chown  root  slink  would  change  the ownership of the file referred to by
       slink, while chown -h root  slink  would  change  the  ownership  of  slink
       itself.

       There are some exceptions to this rule:

       * The  mv(1) and rm(1) commands do not follow symbolic links named as argu-
         ments, but respectively attempt to rename and delete them.  (Note, if the
         symbolic link references a file via a relative path, moving it to another
         directory may very well cause it to stop working, since the path  may  no
         longer be correct.)

       * The  ls(1)  command is also an exception to this rule.  For compatibility
         with historic systems (when ls(1) is not doing a tree walk, i.e., the  -R
         option  is not specified), the ls(1) command follows symbolic links named
         as arguments if the -H or -L option is specified, or if the -F, -d, or -l
         options  are not specified.  (The ls(1) command is the only command where
         the -H and -L options affect its behavior even though it is not  doing  a
         walk of a file tree.)

       * The  file(1) command is also an exception to this rule.  The file(1) com-
         mand does not follow symbolic links named as argument  by  default.   The
         file(1)  command  does  follow symbolic links named as argument if the -L
         option is specified.

Commands traversing a file tree

       The following commands either optionally or  always  traverse  file  trees:
       chgrp(1),  chmod(1), chown(1), cp(1), du(1), find(1), ls(1), pax(1), rm(1),
       and tar(1).

       It is important to realize that the following rules apply equally  to  sym-
       bolic  links  encountered during the file tree traversal and symbolic links
       listed as command-line arguments.

       The first rule applies to symbolic links that reference  files  other  than
       directories.   Operations that apply to symbolic links are performed on the
       links themselves, but otherwise the links are ignored.

       The command rm -r slink directory will remove slink, as well  as  any  sym-
       bolic  links  encountered  in the tree traversal of directory, because sym-
       bolic links may be removed.  In no case will rm(1) affect the file referred
       to by slink.

       The  second rule applies to symbolic links that refer to directories.  Sym-
       bolic links that refer to directories are never followed by default.   This
       is  often  referred to as a "physical" walk, as opposed to a "logical" walk
       (where symbolic links the refer to directories are followed).

       Certain conventions are (should be) followed as consistently as possible by
       commands that perform file tree walks:

       * A  command  can be made to follow any symbolic links named on the command
         line, regardless of the type of file they reference, by specifying the -H
         (for  "half-logical")  flag.   This flag is intended to make the command-
         line name space look like the logical name space.   (Note,  for  commands
         that  do  not always do file tree traversals, the -H flag will be ignored
         if the -R flag is not also specified.)

         For example, the command chown -HR user  slink  will  traverse  the  file
         hierarchy  rooted  in  the file pointed to by slink.  Note, the -H is not
         the same as the previously discussed -h flag.  The -H  flag  causes  sym-
         bolic links specified on the command line to be dereferenced for the pur-
         poses of both the action to be performed and the tree walk, and it is  as
         if the user had specified the name of the file to which the symbolic link
         pointed.

       * A command can be made to follow any symbolic links named on  the  command
         line,  as  well  as  any symbolic links encountered during the traversal,
         regardless of the type of file they reference, by specifying the -L  (for
         "logical")  flag.   This  flag  is intended to make the entire name space
         look like the logical name space.  (Note, for commands that do not always
         do  file  tree  traversals, the -L flag will be ignored if the -R flag is
         not also specified.)

         For example, the command chown -LR user slink will change  the  owner  of
         the  file  referred  to  by slink.  If slink refers to a directory, chown
         will traverse the file hierarchy rooted in the directory that  it  refer-
         ences.   In  addition,  if any symbolic links are encountered in any file
         tree that chown traverses, they will be treated in the  same  fashion  as
         slink.

       * A  command  can be made to provide the default behavior by specifying the
         -P (for "physical") flag.  This flag is intended to make the entire  name
         space look like the physical name space.

       For  commands  that  do not by default do file tree traversals, the -H, -L,
       and -P flags are ignored if the -R flag is not also  specified.   In  addi-
       tion,  you  may specify the -H, -L, and -P options more than once; the last
       one specified determines the command's behavior.  This is intended to  per-
       mit you to alias commands to behave one way or the other, and then override
       that behavior on the command line.

       The ls(1) and rm(1) commands have exceptions to these rules:

       * The rm(1) command operates on the symbolic link, and not the file it ref-
         erences,  and therefore never follows a symbolic link.  The rm(1) command
         does not support the -H, -L, or -P options.

       * To maintain compatibility with historic systems, the ls(1) command acts a
         little  differently.   If  you  do  not specify the -F, -d or -l options,
         ls(1) will follow symbolic links specified on the command line.   If  the
         -L  flag  is  specified,  ls(1) follows all symbolic links, regardless of
         their type, whether specified on the command line or encountered  in  the
         tree walk.

SEE ALSO top

       chgrp(1),   chmod(1),  find(1),  ln(1),  ls(1),  mv(1),  rm(1),  lchown(2),
       link(2), lstat(2), readlink(2), rename(2), symlink(2),  unlink(2),  utimen-
       sat(2), lutimes(3), path_resolution(7)

COLOPHON top

       This  page  is  part  of  release  3.45  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-06-18                          SYMLINK(7)


symlinkat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYMLINKAT(2)                 Linux Programmer's Manual                SYMLINKAT(2)

NAME top

       symlinkat - create a symbolic link relative to a directory file descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <unistd.h>

       int symlinkat(const char *oldpath, int newdirfd, const char *newpath);

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

       symlinkat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The symlinkat() system call operates in exactly the same way as symlink(2),
       except for the differences described in this manual page.

       If the pathname given in newpath is relative, then it is interpreted
       relative to the directory referred to by the file descriptor newdirfd
       (rather than relative to the current working directory of the calling
       process, as is done by symlink(2) for a relative pathname).

       If newpath is relative and newdirfd is the special value AT_FDCWD, then
       newpath is interpreted relative to the current working directory of the
       calling process (like symlink(2)).

       If newpath is absolute, then newdirfd is ignored.

RETURN VALUE top

       On success, symlinkat() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for symlink(2) can also occur for symlinkat().
       The following additional errors can occur for symlinkat():

       EBADF  newdirfd is not a valid file descriptor.

       ENOTDIR
              newpath is relative and newdirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       symlinkat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       See openat(2) for an explanation of the need for symlinkat().

SEE ALSO top

       openat(2), symlink(2), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                        SYMLINKAT(2)


sync(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SYNC(2)                      Linux Programmer's Manual                     SYNC(2)

NAME top

       sync, syncfs - commit buffer cache to disk

SYNOPSIS top

       #include <unistd.h>

       void sync(void);

       int syncfs(int fd);

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

       sync():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

       syncfs():
           _GNU_SOURCE

DESCRIPTION top

       sync() causes all buffered modifications to file metadata and data to be
       written to the underlying file systems.

       syncfs() is like sync(), but synchronizes just the file system containing
       file referred to by the open file descriptor fd.

RETURN VALUE top

       syncfs() returns 0 on success; on error, it returns -1 and sets errno to
       indicate the error.

ERRORS top

       sync() is always successful.

       syncfs() can fail for at least the following reason:

       EBADF  fd is not a valid file descriptor.

VERSIONS top

       syncfs() first appeared in Linux 2.6.39; library support was added to glibc
       in version 2.14.

CONFORMING TO top

       sync(): SVr4, 4.3BSD, POSIX.1-2001.

       syncfs() is Linux-specific.

NOTES top

       Since glibc 2.2.2 the Linux prototype for sync() is as listed above,
       following the various standards.  In libc4, libc5, and glibc up to 2.2.1 it
       was "int sync(void)", and sync() always returned 0.

BUGS top

       According to the standard specification (e.g., POSIX.1-2001), sync()
       schedules the writes, but may return before the actual writing is done.
       However, since version 1.3.20 Linux does actually wait.  (This still does
       not guarantee data integrity: modern disks have large caches.)

SEE ALSO top

       bdflush(2), fdatasync(2), fsync(2), sync(8), update(8)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                             SYNC(2)


sync(8) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYNC(8)                      Linux Programmer's Manual                     SYNC(8)

NAME top

       sync - synchronize data on disk with memory

SYNOPSIS top

       sync [--help] [--version]

DESCRIPTION top

       sync writes any data buffered in memory out to disk.  This can include (but
       is not limited to) modified superblocks, modified inodes, and delayed reads
       and writes.  This must be implemented by the kernel; The sync program does
       nothing but exercise the sync(2) system call.

       The kernel keeps data in memory to avoid doing (relatively slow) disk reads
       and writes.  This improves performance, but if the computer crashes, data
       may be lost or the file system corrupted as a result.  sync ensures that
       everything in memory is written to disk.

       sync should be called before the processor is halted in an unusual manner
       (e.g., before causing a kernel panic when debugging new kernel code).  In
       general, the processor should be halted using the shutdown(8) or reboot(8)
       or halt(8) commands, which will attempt to put the system in a quiescent
       state before calling sync(2).  (Various implementations of these commands
       exist; consult your documentation; on some systems one should not call
       reboot(8) and halt(8) directly.)

OPTIONS top

       --help Print a usage message on standard output and exit successfully.

       --version
              Print version information on standard output, then exit
              successfully.

       --     Terminate option list.

ENVIRONMENT top

       The variables LANG, LC_ALL, LC_CTYPE, and LC_MESSAGES have the usual
       meaning.

CONFORMING TO top

       POSIX.2.

NOTES top

       On Linux, sync is only guaranteed to schedule the dirty blocks for writing;
       it can actually take a short time before all the blocks are finally
       written.  The reboot(8) and halt(8) commands take this into account by
       sleeping for a few seconds after calling sync(2).

       This page describes sync as found in the fileutils-4.0 package; other
       versions may differ slightly.

SEE ALSO top

       sync(2), halt(8), reboot(8), update(8)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1998-11-01                             SYNC(8)


syscall(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SYSCALL(2)                   Linux Programmer's Manual                  SYSCALL(2)

NAME top

       syscall - indirect system call

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(int number, ...);

DESCRIPTION top

       syscall() is a small library function that invokes the system call whose
       assembly language interface has the specified number with the specified
       arguments.  Employing syscall() is useful, for example, when invoking a
       system call that has no wrapper function in the C library.

       syscall() saves CPU registers before making the system call, restores the
       registers upon return from the system call, and stores any error code
       returned by the system call in errno(3) if an error occurs.

       Symbolic constants for system call numbers can be found in the header file
       <sys/syscall.h>.

RETURN VALUE top

       The return value is defined by the system call being invoked.  In general,
       a 0 return value indicates success.  A -1 return value indicates an error,
       and an error code is stored in errno.

NOTES top

       syscall() first appeared in 4BSD.

EXAMPLE top

       #define _GNU_SOURCE
       #include <unistd.h>
       #include <sys/syscall.h>
       #include <sys/types.h>

       int
       main(int argc, char *argv[])
       {
           pid_t tid;

           tid = syscall(SYS_gettid);
           tid = syscall(SYS_tgkill, getpid(), tid);
       }

SEE ALSO top

       _syscall(2), intro(2), syscalls(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-08-14                          SYSCALL(2)


syscalls(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYSCALLS(2)                  Linux Programmer's Manual                 SYSCALLS(2)

NAME top

       syscalls - Linux system calls

SYNOPSIS top

       Linux system calls.

DESCRIPTION top

       The system call is the fundamental interface between an application and the
       Linux kernel.

System calls and library wrapper functions

       System calls are generally not invoked directly, but rather via wrapper
       functions in glibc (or perhaps some other library).  For details of direct
       invocation of a system call, see intro(2).  Often, but not always, the name
       of the wrapper function is the same as the name of the system call that it
       invokes.  For example, glibc contains a function truncate() which invokes
       the underlying "truncate" system call.

       Often the glibc wrapper function is quite thin, doing little work other
       than copying arguments to the right registers before invoking the system
       call, and then setting errno appropriately after the system call has
       returned.  (These are the same steps that are performed by syscall(2),
       which can be used to invoke system calls for which no wrapper function is
       provided.)  Note: system calls indicate a failure by returning a negative
       error number to the caller; when this happens, the wrapper function negates
       the returned error number (to make it positive), copies it to errno, and
       returns -1 to the caller of the wrapper.

       Sometimes, however, the wrapper function does some extra work before
       invoking the system call.  For example, nowadays there are (for reasons
       described below) two related system calls, truncate(2) and truncate64(2),
       and the glibc truncate() wrapper function checks which of those system
       calls are provided by the kernel and determines which should be employed.

System call list

       Below is a list of those system calls that are common to most platforms.
       In the list, the Kernel column indicates the kernel version for those
       system calls that were new in Linux 2.2, or have appeared since that kernel
       version.  Note the following points:

       *  Where no kernel version is indicated, the system call appeared in kernel
          1.0 or earlier.

       *  Where a system call is marked "1.2" this means the system call probably
          appeared in a 1.1.x kernel version, and first appeared in a stable
          kernel with 1.2.  (Development of the 1.2 kernel was initiated from a
          branch of kernel 1.0.6 via the 1.1.x unstable kernel series.)

       *  Where a system call is marked "2.0" this means the system call probably
          appeared in a 1.3.x kernel version, and first appeared in a stable
          kernel with 2.0.  (Development of the 2.0 kernel was initiated from a
          branch of kernel 1.2.x, somewhere around 1.2.10, via the 1.3.x unstable
          kernel series.)

       *  Where a system call is marked "2.2" this means the system call probably
          appeared in a 2.1.x kernel version, and first appeared in a stable
          kernel with 2.2.0.  (Development of the 2.2 kernel was initiated from a
          branch of kernel 2.0.21 via the 2.1.x unstable kernel series.)

       *  Where a system call is marked "2.4" this means the system call probably
          appeared in a 2.3.x kernel version, and first appeared in a stable
          kernel with 2.4.0.  (Development of the 2.4 kernel was initiated from a
          branch of kernel 2.2.8 via the 2.3.x unstable kernel series.)

       *  Where a system call is marked "2.6" this means the system call probably
          appeared in a 2.5.x kernel version, and first appeared in a stable
          kernel with 2.6.0.  (Development of kernel 2.6 was initiated from a
          branch of kernel 2.4.15 via the 2.5.x unstable kernel series.)

       *  Starting with kernel 2.6.0, the development model changed, and new
          system calls may appear in each 2.6.x release.  In this case, the exact
          version number where the system call appeared is shown.  This convention
          continues with the 3.x kernel series, which followed on from kernel
          2.6.39.

       *  In some cases, a system call was added to a stable kernel series after
          it branched from the previous stable kernel series, and then backported
          into the earlier stable kernel series.  For example some system calls
          that appeared in 2.6.x were also backported into a 2.4.x release after
          2.4.15.  When this is so, the version where the system call appeared in
          both of the major kernel series is listed.

       The list of system calls that are available as at kernel 3.5 (or in a few
       cases only on older kernels) is as follows:

       System call                 Kernel        Notes
       ---------------------------------------------------------------

       _llseek(2)                  1.2
       _newselect(2)
       _sysctl(2)
       accept(2)
       accept4(2)                  2.6.28
       access(2)
       acct(2)
       add_key(2)                  2.6.11
       adjtimex(2)
       alarm(2)
       alloc_hugepages(2)          2.5.36        Removed in 2.5.44
       bdflush(2)                                Deprecated (does
                                                 nothing) since 2.6
       bind(2)
       brk(2)
       cacheflush(2)               1.2           Not on x86
       capget(2)                   2.2
       capset(2)                   2.2
       chdir(2)
       chmod(2)
       chown(2)
       chown32(2)                  2.4
       chroot(2)
       clock_adjtime(2)            2.6.39
       clock_getres(2)             2.6
       clock_gettime(2)            2.6
       clock_nanosleep(2)          2.6
       clock_settime(2)            2.6
       clone(2)
       close(2)
       connect(2)
       creat(2)
       create_module(2)                          Removed in 2.6
       delete_module(2)
       dup(2)
       dup2(2)
       dup3(2)                     2.6.27
       epoll_create(2)             2.6
       epoll_create1(2)            2.6.27

       epoll_ctl(2)                2.6
       epoll_pwait(2)              2.6.19
       epoll_wait(2)               2.6
       eventfd(2)                  2.6.22
       eventfd2(2)                 2.6.27
       execve(2)
       exit(2)
       exit_group(2)               2.6
       faccessat(2)                2.6.16
       fadvise64(2)                2.6
       fadvise64_64(2)             2.6
       fallocate(2)                2.6.23
       fanotify_init(2)            2.6.37
       fanotify_mark(2)            2.6.37
       fchdir(2)
       fchmod(2)
       fchmodat(2)                 2.6.16
       fchown(2)
       fchown32(2)                 2.4
       fchownat(2)                 2.6.16
       fcntl(2)
       fcntl64(2)                  2.4
       fdatasync(2)
       fgetxattr(2)                2.6; 2.4.18
       flistxattr(2)               2.6; 2.4.18
       flock(2)                    2.0
       fork(2)
       free_hugepages(2)           2.5.36        Removed in 2.5.44
       fremovexattr(2)             2.6; 2.4.18
       fsetxattr(2)                2.6; 2.4.18
       fstat(2)
       fstat64(2)                  2.4
       fstatat64(2)                2.6.16
       fstatfs(2)
       fstatfs64(2)                2.6
       fsync(2)
       ftruncate(2)
       ftruncate64(2)              2.4
       futex(2)                    2.6
       futimesat(2)                2.6.16
       get_kernel_syms(2)                        Removed in 2.6
       get_mempolicy(2)            2.6.6
       get_robust_list(2)          2.6.17
       get_thread_area(2)          2.6
       getcpu(2)                   2.6.19
       getcwd(2)                   2.2
       getdents(2)                 2.0
       getdents64(2)               2.4
       getegid(2)
       getegid32(2)                2.4
       geteuid(2)
       geteuid32(2)                2.4
       getgid(2)
       getgid32(2)                 2.4
       getgroups(2)
       getgroups32(2)              2.4
       getitimer(2)
       getpeername(2)
       getpagesize(2)              2.0           Not on x86
       getpgid(2)
       getpgrp(2)
       getpid(2)
       getppid(2)
       getpriority(2)
       getresgid(2)                2.2

       getresgid32(2)              2.4
       getresuid(2)                2.2
       getresuid32(2)              2.4
       getrlimit(2)
       getrusage(2)
       getsid(2)                   2.0
       getsockname(2)
       getsockopt(2)
       gettid(2)                   2.4.11
       gettimeofday(2)
       getuid(2)
       getuid32(2)                 2.4
       getxattr(2)                 2.6; 2.4.18
       init_module(2)
       inotify_add_watch(2)        2.6.13
       inotify_init(2)             2.6.13
       inotify_init1(2)            2.6.27
       inotify_rm_watch(2)         2.6.13
       io_cancel(2)                2.6
       io_destroy(2)               2.6
       io_getevents(2)             2.6
       io_setup(2)                 2.6
       io_submit(2)                2.6
       ioctl(2)
       ioperm(2)
       iopl(2)
       ioprio_get(2)               2.6.13
       ioprio_set(2)               2.6.13
       ipc(2)
       kcmp(2)                     3.5
       kexec_load(2)               2.6.13
       keyctl(2)                   2.6.11
       kill(2)
       lchown(2)                   2.2
       lchown32(2)                 2.4
       lgetxattr(2)                2.6; 2.4.18
       link(2)
       linkat(2)                   2.6.16
       listen(2)
       listxattr(2)                2.6; 2.4.18
       llistxattr(2)               2.6; 2.4.18
       lookup_dcookie(2)           2.6
       lremovexattr(2)             2.6; 2.4.18
       lseek(2)
       lsetxattr(2)                2.6; 2.4.18
       lstat(2)
       lstat64(2)                  2.4
       madvise(2)                  2.4
       madvise1(2)                 2.4
       mbind(2)                    2.6.6
       migrate_pages(2)            2.6.16
       mincore(2)                  2.4
       mkdir(2)
       mkdirat(2)                  2.6.16
       mknod(2)
       mknodat(2)                  2.6.16
       mlock(2)
       mlockall(2)
       mmap(2)
       mmap2(2)                    2.4
       modify_ldt(2)
       mount(2)
       move_pages(2)               2.6.18
       mprotect(2)
       mq_getsetattr(2)            2.6.6

       mq_notify(2)                2.6.6
       mq_open(2)                  2.6.6
       mq_timedreceive(2)          2.6.6
       mq_timedsend(2)             2.6.6
       mq_unlink(2)
       mremap(2)                   2.0
       msgctl(2)
       msgget(2)
       msgrcv(2)
       msgsnd(2)
       msync(2)                    2.0
       munlock(2)
       munlockall(2)
       munmap(2)
       name_to_handle_at(2)        2.6.39
       nanosleep(2)                2.0
       nfsservctl(2)               2.2           Removed in 3.1
       nice(2)
       oldfstat(2)
       oldlstat(2)
       oldolduname(2)
       oldstat(2)
       olduname(2)
       open(2)
       open_by_handle_at(2)        2.6.39
       openat(2)                   2.6.16
       pause(2)
       pciconfig_iobase(2)         2.2.15; 2.4   Not on x86
       pciconfig_read(2)           2.0.26; 2.2   Not on x86
       pciconfig_write(2)          2.0.26; 2.2   Not on x86
       perf_event_open(2)          2.6.31        Was called
                                                 perf_counter_open()
                                                 in 2.6.31; renamed
                                                 in 2.6.32
       personality(2)              1.2
       pipe(2)
       pipe2(2)                    2.6.27
       pivot_root(2)               2.4
       poll(2)                     2.2
       ppoll(2)                    2.6.16
       prctl(2)                    2.2
       pread64(2)                                Added as "pread" in
                                                 2.2; renamed
                                                 "pread64" in 2.6
       preadv(2)                   2.6.30
       prlimit(2)                  2.6.36
       process_vm_readv(2)         3.2
       process_vm_writev(2)        3.2
       pselect6(2)                 2.6.16
       ptrace(2)
       pwrite64(2)                               Added as "pwrite" in
                                                 2.2; renamed
                                                 "pwrite64" in 2.6
       pwritev(2)                  2.6.30
       query_module(2)             2.2           Removed in 2.6
       quotactl(2)
       read(2)
       readahead(2)                2.4.13
       readdir(2)
       readlink(2)
       readlinkat(2)               2.6.16
       readv(2)                    2.0
       reboot(2)
       recv(2)
       recvfrom(2)

       recvmsg(2)
       recvmmsg(2)                 2.6.33
       remap_file_pages(2)         2.6
       removexattr(2)              2.6; 2.4.18
       rename(2)
       renameat(2)                 2.6.16
       request_key(2)              2.6.11
       restart_syscall(2)          2.6
       rmdir(2)
       rt_sigaction(2)             2.2
       rt_sigpending(2)            2.2
       rt_sigprocmask(2)           2.2
       rt_sigqueueinfo(2)          2.2
       rt_sigreturn(2)             2.2
       rt_sigsuspend(2)            2.2
       rt_sigtimedwait(2)          2.2
       rt_tgsigqueueinfo(2)        2.6.31
       s390_runtime_instr(2)       3.7           s390 only
       sched_get_priority_max(2)   2.0
       sched_get_priority_min(2)   2.0
       sched_getaffinity(2)        2.6
       sched_getparam(2)           2.0
       sched_getscheduler(2)       2.0
       sched_rr_get_interval(2)    2.0
       sched_setaffinity(2)        2.6
       sched_setparam(2)           2.0
       sched_setscheduler(2)       2.0
       sched_yield(2)              2.0
       select(2)
       semctl(2)
       semget(2)
       semop(2)
       semtimedop(2)               2.6; 2.4.22
       send(2)
       sendfile(2)                 2.2
       sendfile64(2)               2.6; 2.4.19
       sendmmsg(2)                 3.0
       sendmsg(2)
       sendto(2)
       set_mempolicy(2)            2.6.6
       set_robust_list(2)          2.6.17
       set_thread_area(2)          2.6
       set_tid_address(2)          2.6
       setdomainname(2)
       setfsgid(2)                 1.2
       setfsgid32(2)               2.4
       setfsuid(2)                 1.2
       setfsuid32(2)               2.4
       setgid(2)
       setgid32(2)                 2.4
       setgroups(2)
       setgroups32(2)              2.4
       sethostname(2)
       setitimer(2)
       setns(2)                    3.0
       setpgid(2)
       setpriority(2)
       setregid(2)
       setregid32(2)               2.4
       setresgid(2)                2.2
       setresgid32(2)              2.4
       setresuid(2)                2.2
       setresuid32(2)              2.4
       setreuid(2)
       setreuid32(2)               2.4

       setrlimit(2)
       setsid(2)
       setsockopt(2)
       settimeofday(2)
       setuid(2)
       setuid32(2)                 2.4
       setup(2)                                  Removed in 2.2
       setxattr(2)                 2.6; 2.4.18
       sgetmask(2)
       shmat(2)
       shmctl(2)
       shmdt(2)
       shmget(2)
       shutdown(2)
       sigaction(2)
       sigaltstack(2)              2.2
       signal(2)
       signalfd(2)                 2.6.22
       signalfd4(2)                2.6.27
       sigpending(2)
       sigprocmask(2)
       sigreturn(2)
       sigsuspend(2)
       socket(2)
       socketcall(2)
       socketpair(2)
       splice(2)                   2.6.17
       spu_create(2)               2.6.16        PowerPC only
       spu_run(2)                  2.6.16        PowerPC only
       ssetmask(2)
       stat(2)
       stat64(2)                   2.4
       statfs(2)
       statfs64(2)                 2.6
       stime(2)
       subpage_prot(2)             2.6.25        PowerPC if
                                                 CONFIG_PPC_64K_PAGES
       swapoff(2)
       swapon(2)
       symlink(2)
       symlinkat(2)                2.6.16
       sync(2)
       sync_file_range(2)          2.6.17
       sync_file_range2(2)         2.6.22        Architecture-
                                                 specific variant of
                                                 sync_file_range(2)
       syncfs(2)                   2.6.39
       sysfs(2)                    1.2
       sysinfo(2)
       syslog(2)
       tee(2)                      2.6.17
       tgkill(2)                   2.6
       time(2)
       timer_create(2)             2.6
       timer_delete(2)             2.6
       timer_getoverrun(2)         2.6
       timer_gettime(2)            2.6
       timer_settime(2)            2.6
       timerfd_create(2)           2.6.25
       timerfd_gettime(2)          2.6.25
       timerfd_settime(2)          2.6.25
       times(2)
       tkill(2)                    2.6; 2.4.22
       truncate(2)
       truncate64(2)               2.4

       ugetrlimit(2)               2.4
       umask(2)
       umount(2)
       umount2(2)                  2.2
       uname(2)
       unlink(2)
       unlinkat(2)                 2.6.16
       unshare(2)                  2.6.16
       uselib(2)
       ustat(2)
       utime(2)
       utimensat(2)                2.6.22
       utimes(2)                   2.2
       vfork(2)
       vhangup(2)
       vm86old(2)
       vmsplice(2)                 2.6.17
       wait4(2)
       waitid(2)                   2.6.10
       waitpid(2)
       write(2)
       writev(2)                   2.0

       On  many platforms, including x86-32, socket calls are all multiplexed (via
       glibc wrapper functions) through socketcall(2) and similarly System  V  IPC
       calls are multiplexed through ipc(2).

       Although  slots  are  reserved  for  them  in  the  system  call table, the
       following  system  calls  are  not  implemented  in  the  standard  kernel:
       afs_syscall(2),  break(2), ftime(2), getpmsg(2), gtty(2), idle(2), lock(2),
       madvise1(2), mpx(2), phys(2), prof(2), profil(2), putpmsg(2),  security(2),
       stty(2), tuxcall(2), ulimit(2), and vserver(2) (see also unimplemented(2)).
       However, ftime(3), profil(3) and ulimit(3) exist as library routines.   The
       slot for phys(2) is in use since kernel 2.1.116 for umount(2); phys(2) will
       never be implemented.  The getpmsg(2) and putpmsg(2) calls are for  kernels
       patched to support STREAMS, and may never be in the standard kernel.

       There  was  briefly set_zone_reclaim(2), added in Linux 2.6.13, and removed
       in 2.6.16; this system call was never available to user space.

NOTES top

       Roughly speaking, the  code  belonging  to  the  system  call  with  number
       __NR_xxx  defined  in  /usr/include/asm/unistd.h  can be found in the Linux
       kernel source in the routine sys_xxx().  (The dispatch table for  i386  can
       be  found  in  /usr/src/linux/arch/i386/kernel/entry.S.)   There  are  many
       exceptions, however, mostly because older system calls were  superseded  by
       newer  ones,  and  this  has  been  treated  somewhat unsystematically.  On
       platforms with proprietary  operating-system  emulation,  such  as  parisc,
       sparc,  sparc64  and  alpha, there are many additional system calls; mips64
       also contains a full set of 32-bit system calls.

       Over time, changes to  the  interfaces  of  some  system  calls  have  been
       necessary.   One  reason for such changes was the need to increase the size
       of structures or scalar values passed to the system call.  Because of these
       changes,  there  are  now  various  groups  of  related system calls (e.g.,
       truncate(2) and truncate64(2)) which perform similar tasks, but which  vary
       in  details  such  as  the  size  of  their  arguments.  (As noted earlier,
       applications are generally unaware of this: the glibc wrapper functions  do
       some  work  to  ensure  that the right system call is invoked, and that ABI
       compatibility is preserved for old binaries.)  Examples  of  systems  calls
       that exist in multiple versions are the following:

       *  By  now  there are three different versions of stat(2): sys_stat() (slot
          __NR_oldstat), sys_newstat() (slot __NR_stat),  and  sys_stat64()  (slot
          __NR_stat64),  with  the  last  being the most current.  A similar story
          applies for lstat(2) and fstat(2).

       *  Similarly, the defines __NR_oldolduname, __NR_olduname,  and  __NR_uname
          refer to the routines sys_olduname(), sys_uname() and sys_newuname().

       *  In  Linux  2.0,  a new version of vm86(2) appeared, with the old and the
          new kernel routines being named sys_vm86old() and sys_vm86().

       *  In Linux 2.4, a new version of getrlimit(2) appeared, with the  old  and
          the   new   kernel   routines   being  named  sys_old_getrlimit()  (slot
          __NR_getrlimit) and sys_getrlimit() (slot __NR_ugetrlimit).

       *  Linux 2.4 increased the size of user and group IDs from 16 to  32  bits.
          To  support  this  change,  a  range  of  system calls were added (e.g.,
          chown32(2), getuid32(2),  getgroups32(2),  setresuid32(2)),  superseding
          earlier calls of the same name without the "32" suffix.

       *  Linux  2.4  added  support  for  applications on 32-bit architectures to
          access large files (i.e., files for which the  sizes  and  file  offsets
          can't  be represented in 32 bits.)  To support this change, replacements
          were required for system calls that deal with file  offsets  and  sizes.
          Thus  the following system calls were added: fcntl64(2), ftruncate64(2),
          getdents64(2), stat64(2), statfs64(2), and their analogs that work  with
          file  descriptors  or  symbolic links.  These system calls supersede the
          older system calls which, except in the case of the "stat"  calls,  have
          the same name without the "64" suffix.

          On  newer  platforms  that  only have 64-bit file access and 32-bit uids
          (e.g., alpha, ia64, s390x) there are no *64 or *32 calls.  Where the *64
          and *32 calls exist, the other versions are obsolete.

       *  The  rt_sig*  calls  were added in kernel 2.2 to support the addition of
          real-time signals (see signal(7)).  These  system  calls  supersede  the
          older system calls of the same name without the "rt_" prefix.

       *  The select(2) and mmap(2) system calls use five or more arguments, which
          caused problems the way argument passing on the i386 used to be set  up.
          Thus,   while  other  architectures  have  sys_select()  and  sys_mmap()
          corresponding  to  __NR_select  and  __NR_mmap,  on   i386   one   finds
          old_select()  and  old_mmap() (routines that use a pointer to a argument
          block) instead.  These days passing five arguments is not a problem  any
          more,  and  there  is  a  __NR__newselect  that  corresponds directly to
          sys_select() and similarly __NR_mmap2.

SEE ALSO top

       syscall(2), unimplemented(2), libc(7)

COLOPHON top

       This page is part of release  3.45  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                               2012-12-16                         SYSCALLS(2)


sysconf(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

SYSCONF(3)                   Linux Programmer's Manual                  SYSCONF(3)

NAME top

       sysconf - get configuration information at run time

SYNOPSIS top

       #include <unistd.h>

       long sysconf(int name);

DESCRIPTION top

       POSIX allows an application to test at compile or run time whether certain
       options are supported, or what the value is of certain configurable
       constants or limits.

       At compile time this is done by including <unistd.h> and/or <limits.h> and
       testing the value of certain macros.

       At run time, one can ask for numerical values using the present function
       sysconf().  One can ask for numerical values that may depend on the file
       system a file is in using the calls fpathconf(3) and pathconf(3).  One can
       ask for string values using confstr(3).

       The values obtained from these functions are system configuration
       constants.  They do not change during the lifetime of a process.

       For options, typically, there is a constant _POSIX_FOO that may be defined
       in <unistd.h>.  If it is undefined, one should ask at run time.  If it is
       defined to -1, then the option is not supported.  If it is defined to 0,
       then relevant functions and headers exist, but one has to ask at run time
       what degree of support is available.  If it is defined to a value other
       than -1 or 0, then the option is supported.  Usually the value (such as
       200112L) indicates the year and month of the POSIX revision describing the
       option.  Glibc uses the value 1 to indicate support as long as the POSIX
       revision has not been published yet.  The sysconf() argument will be
       _SC_FOO.  For a list of options, see posixoptions(7).

       For variables or limits, typically, there is a constant _FOO, maybe defined
       in <limits.h>, or _POSIX_FOO, maybe defined in <unistd.h>.  The constant
       will not be defined if the limit is unspecified.  If the constant is
       defined, it gives a guaranteed value, and a greater value might actually be
       supported.  If an application wants to take advantage of values which may
       change between systems, a call to sysconf() can be made.  The sysconf()
       argument will be _SC_FOO.

POSIX.1 Variables

       We give the name of the variable, the name of the sysconf() argument used
       to inquire about its value, and a short description.

       First, the POSIX.1 compatible values.

       ARG_MAX - _SC_ARG_MAX
              The maximum length of the arguments to the exec(3) family of
              functions.  Must not be less than _POSIX_ARG_MAX (4096).

       CHILD_MAX - _SC_CHILD_MAX
              The max number of simultaneous processes per user ID.  Must not be
              less than _POSIX_CHILD_MAX (25).

       HOST_NAME_MAX - _SC_HOST_NAME_MAX
              Max length of a hostname, not including the terminating null byte,
              as returned by gethostname(2).  Must not be less than
              _POSIX_HOST_NAME_MAX (255).

       LOGIN_NAME_MAX - _SC_LOGIN_NAME_MAX
              Maximum length of a login name, including the terminating null byte.
              Must not be less than _POSIX_LOGIN_NAME_MAX (9).

       clock ticks - _SC_CLK_TCK
              The number of clock ticks per second.  The corresponding variable is
              obsolete.  It was of course called CLK_TCK.  (Note: the macro
              CLOCKS_PER_SEC does not give information: it must equal 1000000.)

       OPEN_MAX - _SC_OPEN_MAX
              The maximum number of files that a process can have open at any
              time.  Must not be less than _POSIX_OPEN_MAX (20).

       PAGESIZE - _SC_PAGESIZE
              Size of a page in bytes.  Must not be less than 1.  (Some systems
              use PAGE_SIZE instead.)

       RE_DUP_MAX - _SC_RE_DUP_MAX
              The number of repeated occurrences of a BRE permitted by regexec(3)
              and regcomp(3).  Must not be less than _POSIX2_RE_DUP_MAX (255).

       STREAM_MAX - _SC_STREAM_MAX
              The maximum number of streams that a process can have open at any
              time.  If defined, it has the same value as the standard C macro
              FOPEN_MAX.  Must not be less than _POSIX_STREAM_MAX (8).

       SYMLOOP_MAX - _SC_SYMLOOP_MAX
              The maximum number of symbolic links seen in a pathname before
              resolution returns ELOOP.  Must not be less than _POSIX_SYMLOOP_MAX
              (8).

       TTY_NAME_MAX - _SC_TTY_NAME_MAX
              The maximum length of terminal device name, including the
              terminating null byte.  Must not be less than _POSIX_TTY_NAME_MAX
              (9).

       TZNAME_MAX - _SC_TZNAME_MAX
              The maximum number of bytes in a timezone name.  Must not be less
              than _POSIX_TZNAME_MAX (6).

       _POSIX_VERSION - _SC_VERSION
              indicates the year and month the POSIX.1 standard was approved in
              the format YYYYMML; the value 199009L indicates the Sept. 1990
              revision.

POSIX.2 Variables

       Next, the POSIX.2 values, giving limits for utilities.

       BC_BASE_MAX - _SC_BC_BASE_MAX
              indicates the maximum obase value accepted by the bc(1) utility.

       BC_DIM_MAX - _SC_BC_DIM_MAX
              indicates the maximum value of elements permitted in an array by
              bc(1).

       BC_SCALE_MAX - _SC_BC_SCALE_MAX
              indicates the maximum scale value allowed by bc(1).

       BC_STRING_MAX - _SC_BC_STRING_MAX
              indicates the maximum length of a string accepted by bc(1).

       COLL_WEIGHTS_MAX - _SC_COLL_WEIGHTS_MAX
              indicates the maximum numbers of weights that can be assigned to an
              entry of the LC_COLLATE order keyword in the locale definition file,

       EXPR_NEST_MAX - _SC_EXPR_NEST_MAX
              is the maximum number of expressions which can be nested within
              parentheses by expr(1).

       LINE_MAX - _SC_LINE_MAX
              The maximum length of a utility's input line, either from standard
              input or from a file.  This includes space for a trailing newline.

       RE_DUP_MAX - _SC_RE_DUP_MAX
              The maximum number of repeated occurrences of a regular expression
              when the interval notation \{m,n\} is used.

       POSIX2_VERSION - _SC_2_VERSION
              indicates the version of the POSIX.2 standard in the format of
              YYYYMML.

       POSIX2_C_DEV - _SC_2_C_DEV
              indicates whether the POSIX.2 C language development facilities are
              supported.

       POSIX2_FORT_DEV - _SC_2_FORT_DEV
              indicates whether the POSIX.2 FORTRAN development utilities are
              supported.

       POSIX2_FORT_RUN - _SC_2_FORT_RUN
              indicates whether the POSIX.2 FORTRAN run-time utilities are
              supported.

       _POSIX2_LOCALEDEF - _SC_2_LOCALEDEF
              indicates whether the POSIX.2 creation of locates via localedef(1)
              is supported.

       POSIX2_SW_DEV - _SC_2_SW_DEV
              indicates whether the POSIX.2 software development utilities option
              is supported.

       These values also exist, but may not be standard.

        - _SC_PHYS_PAGES
              The number of pages of physical memory.  Note that it is possible
              for the product of this value and the value of _SC_PAGE_SIZE to
              overflow.

        - _SC_AVPHYS_PAGES
              The number of currently available pages of physical memory.

        - _SC_NPROCESSORS_CONF
              The number of processors configured.

        - _SC_NPROCESSORS_ONLN
              The number of processors currently online (available).

RETURN VALUE top

       If name is invalid, -1 is returned, and errno is set to EINVAL.  Otherwise,
       the value returned is the value of the system resource and errno is not
       changed.  In the case of options, a positive value is returned if a queried
       option is available, and -1 if it is not.  In the case of limits, -1 means
       that there is no definite limit.

CONFORMING TO top

       POSIX.1-2001.

BUGS top

       It is difficult to use ARG_MAX because it is not specified how much of the
       argument space for exec(3) is consumed by the user's environment variables.

       Some returned values may be huge; they are not suitable for allocating
       memory.

SEE ALSO top

       bc(1), expr(1), getconf(1), locale(1), fpathconf(3), pathconf(3),
       posixoptions(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-15                          SYSCONF(3)


sysctl(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

SYSCTL(2)                    Linux Programmer's Manual                   SYSCTL(2)

NAME top

       sysctl - read/write system parameters

SYNOPSIS top

       #include <unistd.h>
       #include <linux/sysctl.h>

       int _sysctl(struct __sysctl_args *args);

       Note: There is no glibc wrapper for this system call; see NOTES.

DESCRIPTION top

       Do not use this system call!  See NOTES.

       The _sysctl() call reads and/or writes kernel parameters.  For example, the
       hostname, or the maximum number of open files.  The argument has the form

           struct __sysctl_args {
               int    *name;    /* integer vector describing variable */
               int     nlen;    /* length of this vector */
               void   *oldval;  /* 0 or address where to store old value */
               size_t *oldlenp; /* available room for old value,
                                   overwritten by actual size of old value */
               void   *newval;  /* 0 or address of new value */
               size_t  newlen;  /* size of new value */
           };

       This call does a search in a tree structure, possibly resembling a
       directory tree under /proc/sys, and if the requested item is found calls
       some appropriate routine to read or modify the value.

RETURN VALUE top

       Upon successful completion, _sysctl() returns 0.  Otherwise, a value of -1
       is returned and errno is set to indicate the error.

ERRORS top

       EFAULT The invocation asked for the previous value by setting oldval non-
              NULL, but allowed zero room in oldlenp.

       ENOTDIR
              name was not found.

       EPERM  No search permission for one of the encountered "directories", or no
              read permission where oldval was nonzero, or no write permission
              where newval was nonzero.

CONFORMING TO top

       This call is Linux-specific, and should not be used in programs intended to
       be portable.  A sysctl() call has been present in Linux since version
       1.3.57.  It originated in 4.4BSD.  Only Linux has the /proc/sys mirror, and
       the object naming schemes differ between Linux and 4.4BSD, but the
       declaration of the sysctl() function is the same in both.

NOTES top

       Glibc does not provide a wrapper for this system call; call it using
       syscall(2).  Or rather...  don't call it: use of this system call has long
       been discouraged, and it is so unloved that it is likely to disappear in a
       future kernel version.  Since Linix 2.6.24, uses of this system call result
       in warnings in the kernel log.  Remove it from your programs now; use the
       /proc/sys interface instead.

       This system call is available only if the kernel was configured with the
       CONFIG_SYSCTL_SYSCALL option.

BUGS top

       The object names vary between kernel versions, making this system call
       worthless for applications.

       Not all available objects are properly documented.

       It is not yet possible to change operating system by writing to
       /proc/sys/kernel/ostype.

EXAMPLE top

       #define _GNU_SOURCE
       #include <unistd.h>
       #include <sys/syscall.h>
       #include <string.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <linux/sysctl.h>

       int _sysctl(struct __sysctl_args *args );

       #define OSNAMESZ 100

       int
       main(void)
       {
           struct __sysctl_args args;
           char osname[OSNAMESZ];
           size_t osnamelth;
           int name[] = { CTL_KERN, KERN_OSTYPE };

           memset(&args, 0, sizeof(struct __sysctl_args));
           args.name = name;
           args.nlen = sizeof(name)/sizeof(name[0]);
           args.oldval = osname;
           args.oldlenp = &osnamelth;

           osnamelth = sizeof(osname);

           if (syscall(SYS__sysctl, &args) == -1) {
               perror("_sysctl");
               exit(EXIT_FAILURE);
           }
           printf("This machine is running %*s\n", osnamelth, osname);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       proc(5)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-21                           SYSCTL(2)


sysfs(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | COLOPHON The Linux Programming Interface

SYSFS(2)                     Linux Programmer's Manual                    SYSFS(2)

NAME top

       sysfs - get file system type information

SYNOPSIS top

       int sysfs(int option, const char *fsname);

       int sysfs(int option, unsigned int fs_index, char *buf);

       int sysfs(int option);

DESCRIPTION top

       sysfs() returns information about the file system types currently present
       in the kernel.  The specific form of the sysfs() call and the information
       returned depends on the option in effect:

       1  Translate the file-system identifier string fsname into a file-system
          type index.

       2  Translate the file-system type index fs_index into a null-terminated
          file-system identifier string.  This string will be written to the
          buffer pointed to by buf.  Make sure that buf has enough space to accept
          the string.

       3  Return the total number of file system types currently present in the
          kernel.

       The numbering of the file-system type indexes begins with zero.

RETURN VALUE top

       On success, sysfs() returns the file-system index for option 1, zero for
       option 2, and the number of currently configured file systems for option 3.
       On error, -1 is returned, and errno is set appropriately.

ERRORS top

       EFAULT Either fsname or buf is outside your accessible address space.

       EINVAL fsname is not a valid file-system type identifier; fs_index is out-
              of-bounds; option is invalid.

CONFORMING TO top

       SVr4.

NOTES top

       This System-V derived system call is obsolete; don't use it.  On systems
       with /proc, the same information can be obtained via /proc/filesystems; use
       that interface instead.

BUGS top

       There is no libc or glibc support.  There is no way to guess how large buf
       should be.

COLOPHON top

       This page is part of release 3.45 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                               2010-06-27                            SYSFS(2)


sysinfo(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

SYSINFO(2)                   Linux Programmer's Manual                  SYSINFO(2)

NAME top

       sysinfo - returns information on overall system statistics

SYNOPSIS top

       #include <sys/sysinfo.h>

       int sysinfo(struct sysinfo *info);

DESCRIPTION top

       Until Linux 2.3.16, sysinfo() used to return information in the following
       structure:

           struct sysinfo {
               long uptime;             /* Seconds since boot */
               unsigned long loads[3];  /* 1, 5, and 15 minute load averages */
               unsigned long totalram;  /* Total usable main memory size */
               unsigned long freeram;   /* Available memory size */
               unsigned long sharedram; /* Amount of shared memory */
               unsigned long bufferram; /* Memory used by buffers */
               unsigned long totalswap; /* Total swap space size */
               unsigned long freeswap;  /* swap space still available */
               unsigned short procs;    /* Number of current processes */
               char _f[22];             /* Pads structure to 64 bytes */
           };

       and the sizes were given in bytes.

       Since Linux 2.3.23 (i386), 2.3.48 (all architectures) the structure is:

           struct sysinfo {
               long uptime;             /* Seconds since boot */
               unsigned long loads[3];  /* 1, 5, and 15 minute load averages */
               unsigned long totalram;  /* Total usable main memory size */
               unsigned long freeram;   /* Available memory size */
               unsigned long sharedram; /* Amount of shared memory */
               unsigned long bufferram; /* Memory used by buffers */
               unsigned long totalswap; /* Total swap space size */
               unsigned long freeswap;  /* swap space still available */
               unsigned short procs;    /* Number of current processes */
               unsigned long totalhigh; /* Total high memory size */
               unsigned long freehigh;  /* Available high memory size */
               unsigned int mem_unit;   /* Memory unit size in bytes */
               char _f[20-2*sizeof(long)-sizeof(int)]; /* Padding to 64 bytes */
           };

       and the sizes are given as multiples of mem_unit bytes.

       sysinfo() provides a simple way of getting overall system statistics.  This
       is more portable than reading /dev/kmem.

RETURN VALUE top

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

ERRORS top

       EFAULT pointer to struct sysinfo is invalid

CONFORMING TO top

       This function is Linux-specific, and should not be used in programs
       intended to be portable.

       The Linux kernel has a sysinfo() system call since 0.98.pl6.  Linux libc
       contains a sysinfo() routine since 5.3.5, and glibc has one since 1.90.

SEE ALSO top

       proc(5)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-05                          SYSINFO(2)


system(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYSTEM(3)                    Linux Programmer's Manual                   SYSTEM(3)

NAME top

       system - execute a shell command

SYNOPSIS top

       #include <stdlib.h>

       int system(const char *command);

DESCRIPTION top

       system() executes a command specified in command by calling /bin/sh -c
       command, and returns after the command has been completed.  During
       execution of the command, SIGCHLD will be blocked, and SIGINT and SIGQUIT
       will be ignored.

RETURN VALUE top

       The value returned is -1 on error (e.g., fork(2) failed), and the return
       status of the command otherwise.  This latter return status is in the
       format specified in wait(2).  Thus, the exit code of the command will be
       WEXITSTATUS(status).  In case /bin/sh could not be executed, the exit
       status will be that of a command that does exit(127).

       If the value of command is NULL, system() returns nonzero if the shell is
       available, and zero if not.

       system() does not affect the wait status of any other children.

CONFORMING TO top

       C89, C99, POSIX.1-2001.

NOTES top

       If the _XOPEN_SOURCE feature test macro is defined (before including any
       header files), then the macros described in wait(2) (WEXITSTATUS(), etc.)
       are made available when including <stdlib.h>.

       As mentioned, system() ignores SIGINT and SIGQUIT.  This may make programs
       that call it from a loop uninterruptible, unless they take care themselves
       to check the exit status of the child.  E.g.

           while (something) {
               int ret = system("foo");

               if (WIFSIGNALED(ret) &&
                   (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT))
                       break;
           }

       Do not use system() from a program with set-user-ID or set-group-ID
       privileges, because strange values for some environment variables might be
       used to subvert system integrity.  Use the exec(3) family of functions
       instead, but not execlp(3) or execvp(3).  system() will not, in fact, work
       properly from programs with set-user-ID or set-group-ID privileges on
       systems on which /bin/sh is bash version 2, since bash 2 drops privileges
       on startup.  (Debian uses a modified bash which does not do this when
       invoked as sh.)

       In versions of glibc before 2.1.3, the check for the availability of
       /bin/sh was not actually performed if command was NULL; instead it was
       always assumed to be available, and system() always returned 1 in this
       case.  Since glibc 2.1.3, this check is performed because, even though
       POSIX.1-2001 requires a conforming implementation to provide a shell, that
       shell may not be available or executable if the calling program has
       previously called chroot(2) (which is not specified by POSIX.1-2001).

       It is possible for the shell command to return 127, so that code is not a
       sure indication that the execve(2) call failed.

SEE ALSO top

       sh(1), signal(2), wait(2), exec(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-10                           SYSTEM(3)


sysv_signal(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

SYSV_SIGNAL(3)               Linux Programmer's Manual              SYSV_SIGNAL(3)

NAME top

       sysv_signal - signal handling with System V semantics

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <signal.h>

       typedef void (*sighandler_t)(int);

       sighandler_t sysv_signal(int signum, sighandler_t handler);

DESCRIPTION top

       The sysv_signal() function takes the same arguments, and performs the same
       task, as signal(2).

       However sysv_signal() provides the System V unreliable signal semantics,
       that is: a) the disposition of the signal is reset to the default when the
       handler is invoked; b) delivery of further instances of the signal is not
       blocked while the signal handler is executing; and c) if the handler
       interrupts (certain) blocking system calls, then the system call is not
       automatically restarted.

RETURN VALUE top

       The sysv_signal() function returns the previous value of the signal
       handler, or SIG_ERR on error.

ERRORS top

       As for signal(2).

CONFORMING TO top

       This function is nonstandard.

NOTES top

       Use of sysv_signal() should be avoided; use sigaction(2) instead.

       On older Linux systems, sysv_signal() and signal(2) were equivalent.  But
       on newer systems, signal(2) provides reliable signal semantics; see
       signal(2) for details.

       The use of sighandler_t is a GNU extension; this type is only defined if
       the _GNU_SOURCE feature test macro is defined.

SEE ALSO top

       sigaction(2), signal(2), bsd_signal(3), signal(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-05-04                      SYSV_SIGNAL(3)


tan(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TAN(3)                       Linux Programmer's Manual                      TAN(3)

NAME top

       tan, tanf, tanl - tangent function

SYNOPSIS top

       #include <math.h>

       double tan(double x);
       float tanf(float x);
       long double tanl(long double x);

       Link with -lm.

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

       tanf(), tanl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The tan() function returns the tangent of x, where x is given in radians.

RETURN VALUE top

       On success, these functions return the tangent of x.

       If x is a NaN, a NaN is returned.

       If x is positive infinity or negative infinity, a domain error occurs, and
       a NaN is returned.

       If the correct result would overflow, a range error occurs, and the
       functions return HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with the
       mathematically correct sign.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is an infinity
              errno is set to EDOM (but see BUGS).  An invalid floating-point
              exception (FE_INVALID) is raised.

       Range error: result overflow
              An overflow floating-point exception (FE_OVERFLOW) is raised.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

BUGS top

       Before version 2.10, the glibc implementation did not set errno to EDOM
       when a domain error occurred.

SEE ALSO top

       acos(3), asin(3), atan(3), atan2(3), cos(3), ctan(3), sin(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-11                              TAN(3)


tanh(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

TANH(3)                      Linux Programmer's Manual                     TANH(3)

NAME top

       tanh, tanhf, tanhl - hyperbolic tangent function

SYNOPSIS top

       #include <math.h>

       double tanh(double x);
       float tanhf(float x);
       long double tanhl(long double x);

       Link with -lm.

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

       tanhf(), tanhl():
           _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
           || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The tanh() function returns the hyperbolic tangent of x, which is defined
       mathematically as:

           tanh(x) = sinh(x) / cosh(x)

RETURN VALUE top

       On success, these functions return the hyperbolic tangent of x.

       If x is a NaN, a NaN is returned.

       If x is +0 (-0), +0 (-0) is returned.

       If x is positive infinity (negative infinity), +1 (-1) is returned.

ERRORS top

       No errors occur.

CONFORMING TO top

       C99, POSIX.1-2001.  The variant returning double also conforms to SVr4,
       4.3BSD, C89.

SEE ALSO top

       acosh(3), asinh(3), atanh(3), cosh(3), ctanh(3), sinh(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                             TANH(3)


tcgetpgrp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TCGETPGRP(3)                 Linux Programmer's Manual                TCGETPGRP(3)

NAME top

       tcgetpgrp, tcsetpgrp - get and set terminal foreground process group

SYNOPSIS top

       #include <unistd.h>

       pid_t tcgetpgrp(int fd);

       int tcsetpgrp(int fd, pid_t pgrp);

DESCRIPTION top

       The function tcgetpgrp() returns the process group ID of the foreground
       process group on the terminal associated to fd, which must be the
       controlling terminal of the calling process.

       The function tcsetpgrp() makes the process group with process group ID pgrp
       the foreground process group on the terminal associated to fd, which must
       be the controlling terminal of the calling process, and still be associated
       with its session.  Moreover, pgrp must be a (nonempty) process group
       belonging to the same session as the calling process.

       If tcsetpgrp() is called by a member of a background process group in its
       session, and the calling process is not blocking or ignoring SIGTTOU, a
       SIGTTOU signal is sent to all members of this background process group.

RETURN VALUE top

       When fd refers to the controlling terminal of the calling process, the
       function tcgetpgrp() will return the foreground process group ID of that
       terminal if there is one, and some value larger than 1 that is not
       presently a process group ID otherwise.  When fd does not refer to the
       controlling terminal of the calling process, -1 is returned, and errno is
       set appropriately.

       When successful, tcsetpgrp() returns 0.  Otherwise, it returns -1, and
       errno is set appropriately.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       EINVAL pgrp has an unsupported value.

       ENOTTY The calling process does not have a controlling terminal, or it has
              one but it is not described by fd, or, for tcsetpgrp(), this
              controlling terminal is no longer associated with the session of the
              calling process.

       EPERM  pgrp has a supported value, but is not the process group ID of a
              process in the same session as the calling process.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       These functions are implemented via the TIOCGPGRP and TIOCSPGRP ioctls.

History

       The ioctls appeared in 4.2BSD.  The functions are POSIX inventions.

SEE ALSO top

       setpgid(2), setsid(2), credentials(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2003-01-28                        TCGETPGRP(3)


tcgetsid(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TCGETSID(3)                  Linux Programmer's Manual                 TCGETSID(3)

NAME top

       tcgetsid - get session ID

SYNOPSIS top

       #define _XOPEN_SOURCE 500        /* See feature_test_macros(7) */
       #include <termios.h>

       pid_t tcgetsid(int fd);

DESCRIPTION top

       The function tcgetsid() returns the session ID of the current session that
       has the terminal associated to fd as controlling terminal.  This terminal
       must be the controlling terminal of the calling process.

RETURN VALUE top

       When fd refers to the controlling terminal of our session, the function
       tcgetsid() will return the session ID of this session.  Otherwise, -1 is
       returned, and errno is set appropriately.

ERRORS top

       EBADF  fd is not a valid file descriptor.

       ENOTTY The calling process does not have a controlling terminal, or it has
              one but it is not described by fd.

VERSIONS top

       tcgetsid() is provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       This function is implemented via the TIOCGSID ioctl(2), present since Linux
       2.1.71.

SEE ALSO top

       getsid(2)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                         TCGETSID(3)


tcp(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TCP(7)                       Linux Programmer's Manual                      TCP(7)

NAME top

       tcp - TCP protocol

SYNOPSIS top

       #include <sys/socket.h>
       #include <netinet/in.h>
       #include <netinet/tcp.h>

       tcp_socket = socket(AF_INET, SOCK_STREAM, 0);

DESCRIPTION top

       This is an implementation of the TCP protocol defined in RFC 793, RFC 1122
       and RFC 2001 with the NewReno and SACK extensions.  It provides a reliable,
       stream-oriented, full-duplex connection between two sockets on top of
       ip(7), for both v4 and v6 versions.  TCP guarantees that the data arrives
       in order and retransmits lost packets.  It generates and checks a per-
       packet checksum to catch transmission errors.  TCP does not preserve record
       boundaries.

       A newly created TCP socket has no remote or local address and is not fully
       specified.  To create an outgoing TCP connection use connect(2) to
       establish a connection to another TCP socket.  To receive new incoming
       connections, first bind(2) the socket to a local address and port and then
       call listen(2) to put the socket into the listening state.  After that a
       new socket for each incoming connection can be accepted using accept(2).  A
       socket which has had accept(2) or connect(2) successfully called on it is
       fully specified and may transmit data.  Data cannot be transmitted on
       listening or not yet connected sockets.

       Linux supports RFC 1323 TCP high performance extensions.  These include
       Protection Against Wrapped Sequence Numbers (PAWS), Window Scaling and
       Timestamps.  Window scaling allows the use of large (> 64K) TCP windows in
       order to support links with high latency or bandwidth.  To make use of
       them, the send and receive buffer sizes must be increased.  They can be set
       globally with the /proc/sys/net/ipv4/tcp_wmem and
       /proc/sys/net/ipv4/tcp_rmem files, or on individual sockets by using the
       SO_SNDBUF and SO_RCVBUF socket options with the setsockopt(2) call.

       The maximum sizes for socket buffers declared via the SO_SNDBUF and
       SO_RCVBUF mechanisms are limited by the values in the
       /proc/sys/net/core/rmem_max and /proc/sys/net/core/wmem_max files.  Note
       that TCP actually allocates twice the size of the buffer requested in the
       setsockopt(2) call, and so a succeeding getsockopt(2) call will not return
       the same size of buffer as requested in the setsockopt(2) call.  TCP uses
       the extra space for administrative purposes and internal kernel structures,
       and the /proc file values reflect the larger sizes compared to the actual
       TCP windows.  On individual connections, the socket buffer size must be set
       prior to the listen(2) or connect(2) calls in order to have it take effect.
       See socket(7) for more information.

       TCP supports urgent data.  Urgent data is used to signal the receiver that
       some important message is part of the data stream and that it should be
       processed as soon as possible.  To send urgent data specify the MSG_OOB
       option to send(2).  When urgent data is received, the kernel sends a SIGURG
       signal to the process or process group that has been set as the socket
       "owner" using the SIOCSPGRP or FIOSETOWN ioctls (or the
       POSIX.1-2001-specified fcntl(2) F_SETOWN operation).  When the SO_OOBINLINE
       socket option is enabled, urgent data is put into the normal data stream (a
       program can test for its location using the SIOCATMARK ioctl described
       below), otherwise it can be only received when the MSG_OOB flag is set for
       recv(2) or recvmsg(2).

       Linux 2.4 introduced a number of changes for improved throughput and
       scaling, as well as enhanced functionality.  Some of these features include
       support for zero-copy sendfile(2), Explicit Congestion Notification, new
       management of TIME_WAIT sockets, keep-alive socket options and support for
       Duplicate SACK extensions.

Address Formats

       TCP is built on top of IP (see ip(7)).  The address formats defined by
       ip(7) apply to TCP.  TCP only supports point-to-point communication;
       broadcasting and multicasting are not supported.

/proc interfaces

       System-wide TCP parameter settings can be accessed by files in the
       directory /proc/sys/net/ipv4/.  In addition, most IP /proc interfaces also
       apply to TCP; see ip(7).  Variables described as Boolean take an integer
       value, with a nonzero value ("true") meaning that the corresponding option
       is enabled, and a zero value ("false") meaning that the option is disabled.

       tcp_abc (Integer; default: 0; since Linux 2.6.15)
              Control the Appropriate Byte Count (ABC), defined in RFC 3465.  ABC
              is a way of increasing the congestion window (cwnd) more slowly in
              response to partial acknowledgments.  Possible values are:

              0  increase cwnd once per acknowledgment (no ABC)

              1  increase cwnd once per acknowledgment of full sized segment

              2  allow increase cwnd by two if acknowledgment is of two segments
                 to compensate for delayed acknowledgments.

       tcp_abort_on_overflow (Boolean; default: disabled; since Linux 2.4)
              Enable resetting connections if the listening service is too slow
              and unable to keep up and accept them.  It means that if overflow
              occurred due to a burst, the connection will recover.  Enable this
              option only if you are really sure that the listening daemon cannot
              be tuned to accept connections faster.  Enabling this option can
              harm the clients of your server.

       tcp_adv_win_scale (integer; default: 2; since Linux 2.4)
              Count buffering overhead as bytes/2^tcp_adv_win_scale, if
              tcp_adv_win_scale is greater than 0; or bytes-
              bytes/2^(-tcp_adv_win_scale), if tcp_adv_win_scale is less than or
              equal to zero.

              The socket receive buffer space is shared between the application
              and kernel.  TCP maintains part of the buffer as the TCP window,
              this is the size of the receive window advertised to the other end.
              The rest of the space is used as the "application" buffer, used to
              isolate the network from scheduling and application latencies.  The
              tcp_adv_win_scale default value of 2 implies that the space used for
              the application buffer is one fourth that of the total.

       tcp_allowed_congestion_control (String; default: see text; since Linux
       2.4.20)
              Show/set the congestion control algorithm choices available to
              unprivileged processes (see the description of the TCP_CONGESTION
              socket option).  The list is a subset of those listed in
              tcp_available_congestion_control.  The default value for this list
              is "reno" plus the default setting of tcp_congestion_control.

       tcp_available_congestion_control (String; read-only; since Linux 2.4.20)
              Show a list of the congestion-control algorithms that are
              registered.  This list is a limiting set for the list in
              tcp_allowed_congestion_control.  More congestion-control algorithms
              may be available as modules, but not loaded.

       tcp_app_win (integer; default: 31; since Linux 2.4)
              This variable defines how many bytes of the TCP window are reserved
              for buffering overhead.

              A maximum of (window/2^tcp_app_win, mss) bytes in the window are
              reserved for the application buffer.  A value of 0 implies that no
              amount is reserved.

       tcp_base_mss (Integer; default: 512; since Linux 2.6.17)
              The initial value of search_low to be used by the packetization
              layer Path MTU discovery (MTU probing).  If MTU probing is enabled,
              this is the initial MSS used by the connection.

       tcp_bic (Boolean; default: disabled; Linux 2.4.27/2.6.6 to 2.6.13)
              Enable BIC TCP congestion control algorithm.  BIC-TCP is a sender-
              side only change that ensures a linear RTT fairness under large
              windows while offering both scalability and bounded TCP-
              friendliness.  The protocol combines two schemes called additive
              increase and binary search increase.  When the congestion window is
              large, additive increase with a large increment ensures linear RTT
              fairness as well as good scalability.  Under small congestion
              windows, binary search increase provides TCP friendliness.

       tcp_bic_low_window (integer; default: 14; Linux 2.4.27/2.6.6 to 2.6.13)
              Set the threshold window (in packets) where BIC TCP starts to adjust
              the congestion window.  Below this threshold BIC TCP behaves the
              same as the default TCP Reno.

       tcp_bic_fast_convergence (Boolean; default: enabled; Linux 2.4.27/2.6.6 to
       2.6.13)
              Force BIC TCP to more quickly respond to changes in congestion
              window.  Allows two flows sharing the same connection to converge
              more rapidly.

       tcp_congestion_control (String; default: see text; since Linux 2.4.13)
              Set the default congestion-control algorithm to be used for new
              connections.  The algorithm "reno" is always available, but
              additional choices may be available depending on kernel
              configuration.  The default value for this file is set as part of
              kernel configuration.

       tcp_dma_copybreak (integer; default: 4096; since Linux 2.6.24)
              Lower limit, in bytes, of the size of socket reads that will be
              offloaded to a DMA copy engine, if one is present in the system and
              the kernel was configured with the CONFIG_NET_DMA option.

       tcp_dsack (Boolean; default: enabled; since Linux 2.4)
              Enable RFC 2883 TCP Duplicate SACK support.

       tcp_ecn (Boolean; default: disabled; since Linux 2.4)
              Enable RFC 2884 Explicit Congestion Notification.  When enabled,
              connectivity to some destinations could be affected due to older,
              misbehaving routers along the path causing connections to be
              dropped.

       tcp_fack (Boolean; default: enabled; since Linux 2.2)
              Enable TCP Forward Acknowledgement support.

       tcp_fin_timeout (integer; default: 60; since Linux 2.2)
              This specifies how many seconds to wait for a final FIN packet
              before the socket is forcibly closed.  This is strictly a violation
              of the TCP specification, but required to prevent denial-of-service
              attacks.  In Linux 2.2, the default value was 180.

       tcp_frto (integer; default: 0; since Linux 2.4.21/2.6)
              Enable F-RTO, an enhanced recovery algorithm for TCP retransmission
              timeouts (RTOs).  It is particularly beneficial in wireless
              environments where packet loss is typically due to random radio
              interference rather than intermediate router congestion.  See RFC
              4138 for more details.

              This file can have one of the following values:

              0  Disabled.

              1  The basic version F-RTO algorithm is enabled.

              2  Enable SACK-enhanced F-RTO if flow uses SACK.  The basic version
                 can be used also when SACK is in use though in that case
                 scenario(s) exists where F-RTO interacts badly with the packet
                 counting of the SACK-enabled TCP flow.

              Before Linux 2.6.22, this parameter was a Boolean value, supporting
              just values 0 and 1 above.

       tcp_frto_response (integer; default: 0; since Linux 2.6.22)
              When F-RTO has detected that a TCP retransmission timeout was
              spurious (i.e, the timeout would have been avoided had TCP set a
              longer retransmission timeout), TCP has several options concerning
              what to do next.  Possible values are:

              0  Rate halving based; a smooth and conservative response, results
                 in halved congestion window (cwnd) and slow-start threshold
                 (ssthresh) after one RTT.

              1  Very conservative response; not recommended because even though
                 being valid, it interacts poorly with the rest of Linux TCP;
                 halves cwnd and ssthresh immediately.

              2  Aggressive response; undoes congestion-control measures that are
                 now known to be unnecessary (ignoring the possibility of a lost
                 retransmission that would require TCP to be more cautious); cwnd
                 and ssthresh are restored to the values prior to timeout.

       tcp_keepalive_intvl (integer; default: 75; since Linux 2.4)
              The number of seconds between TCP keep-alive probes.

       tcp_keepalive_probes (integer; default: 9; since Linux 2.2)
              The maximum number of TCP keep-alive probes to send before giving up
              and killing the connection if no response is obtained from the other
              end.

       tcp_keepalive_time (integer; default: 7200; since Linux 2.2)
              The number of seconds a connection needs to be idle before TCP
              begins sending out keep-alive probes.  Keep-alives are only sent
              when the SO_KEEPALIVE socket option is enabled.  The default value
              is 7200 seconds (2 hours).  An idle connection is terminated after
              approximately an additional 11 minutes (9 probes an interval of 75
              seconds apart) when keep-alive is enabled.

              Note that underlying connection tracking mechanisms and application
              timeouts may be much shorter.

       tcp_low_latency (Boolean; default: disabled; since Linux 2.4.21/2.6)
              If enabled, the TCP stack makes decisions that prefer lower latency
              as opposed to higher throughput.  It this option is disabled, then
              higher throughput is preferred.  An example of an application where
              this default should be changed would be a Beowulf compute cluster.

       tcp_max_orphans (integer; default: see below; since Linux 2.4)
              The maximum number of orphaned (not attached to any user file
              handle) TCP sockets allowed in the system.  When this number is
              exceeded, the orphaned connection is reset and a warning is printed.
              This limit exists only to prevent simple denial-of-service attacks.
              Lowering this limit is not recommended.  Network conditions might
              require you to increase the number of orphans allowed, but note that
              each orphan can eat up to ~64K of unswappable memory.  The default
              initial value is set equal to the kernel parameter NR_FILE.  This
              initial default is adjusted depending on the memory in the system.

       tcp_max_syn_backlog (integer; default: see below; since Linux 2.2)
              The maximum number of queued connection requests which have still
              not received an acknowledgement from the connecting client.  If this
              number is exceeded, the kernel will begin dropping requests.  The
              default value of 256 is increased to 1024 when the memory present in
              the system is adequate or greater (>= 128Mb), and reduced to 128 for
              those systems with very low memory (<= 32Mb).  It is recommended
              that if this needs to be increased above 1024, TCP_SYNQ_HSIZE in
              include/net/tcp.h be modified to keep
              TCP_SYNQ_HSIZE*16<=tcp_max_syn_backlog, and the kernel be
              recompiled.

       tcp_max_tw_buckets (integer; default: see below; since Linux 2.4)
              The maximum number of sockets in TIME_WAIT state allowed in the
              system.  This limit exists only to prevent simple denial-of-service
              attacks.  The default value of NR_FILE*2 is adjusted depending on
              the memory in the system.  If this number is exceeded, the socket is
              closed and a warning is printed.

       tcp_moderate_rcvbuf (Boolean; default: enabled; since Linux 2.4.17/2.6.7)
              If enabled, TCP performs receive buffer auto-tuning, attempting to
              automatically size the buffer (no greater than tcp_rmem[2]) to match
              the size required by the path for full throughput.

       tcp_mem (since Linux 2.4)
              This is a vector of 3 integers: [low, pressure, high].  These
              bounds, measured in units of the system page size, are used by TCP
              to track its memory usage.  The defaults are calculated at boot time
              from the amount of available memory.  (TCP can only use low memory
              for this, which is limited to around 900 megabytes on 32-bit
              systems.  64-bit systems do not suffer this limitation.)

              low       TCP doesn't regulate its memory allocation when the number
                        of pages it has allocated globally is below this number.

              pressure  When the amount of memory allocated by TCP exceeds this
                        number of pages, TCP moderates its memory consumption.
                        This memory pressure state is exited once the number of
                        pages allocated falls below the low mark.

              high      The maximum number of pages, globally, that TCP will
                        allocate.  This value overrides any other limits imposed
                        by the kernel.

       tcp_mtu_probing (integer; default: 0; since Linux 2.6.17)
              This parameter controls TCP Packetization-Layer Path MTU Discovery.
              The following values may be assigned to the file:

              0  Disabled

              1  Disabled by default, enabled when an ICMP black hole detected

              2  Always enabled, use initial MSS of tcp_base_mss.

       tcp_no_metrics_save (Boolean; default: disabled; since Linux 2.6.6)
              By default, TCP saves various connection metrics in the route cache
              when the connection closes, so that connections established in the
              near future can use these to set initial conditions.  Usually, this
              increases overall performance, but it may sometimes cause
              performance degradation.  If tcp_no_metrics_save is enabled, TCP
              will not cache metrics on closing connections.

       tcp_orphan_retries (integer; default: 8; since Linux 2.4)
              The maximum number of attempts made to probe the other end of a
              connection which has been closed by our end.

       tcp_reordering (integer; default: 3; since Linux 2.4)
              The maximum a packet can be reordered in a TCP packet stream without
              TCP assuming packet loss and going into slow start.  It is not
              advisable to change this number.  This is a packet reordering
              detection metric designed to minimize unnecessary back off and
              retransmits provoked by reordering of packets on a connection.

       tcp_retrans_collapse (Boolean; default: enabled; since Linux 2.2)
              Try to send full-sized packets during retransmit.

       tcp_retries1 (integer; default: 3; since Linux 2.2)
              The number of times TCP will attempt to retransmit a packet on an
              established connection normally, without the extra effort of getting
              the network layers involved.  Once we exceed this number of
              retransmits, we first have the network layer update the route if
              possible before each new retransmit.  The default is the RFC
              specified minimum of 3.

       tcp_retries2 (integer; default: 15; since Linux 2.2)
              The maximum number of times a TCP packet is retransmitted in
              established state before giving up.  The default value is 15, which
              corresponds to a duration of approximately between 13 to 30 minutes,
              depending on the retransmission timeout.  The RFC 1122 specified
              minimum limit of 100 seconds is typically deemed too short.

       tcp_rfc1337 (Boolean; default: disabled; since Linux 2.2)
              Enable TCP behavior conformant with RFC 1337.  When disabled, if a
              RST is received in TIME_WAIT state, we close the socket immediately
              without waiting for the end of the TIME_WAIT period.

       tcp_rmem (since Linux 2.4)
              This is a vector of 3 integers: [min, default, max].  These
              parameters are used by TCP to regulate receive buffer sizes.  TCP
              dynamically adjusts the size of the receive buffer from the defaults
              listed below, in the range of these values, depending on memory
              available in the system.

              min       minimum size of the receive buffer used by each TCP
                        socket.  The default value is the system page size.  (On
                        Linux 2.4, the default value is 4K, lowered to PAGE_SIZE
                        bytes in low-memory systems.)  This value is used to
                        ensure that in memory pressure mode, allocations below
                        this size will still succeed.  This is not used to bound
                        the size of the receive buffer declared using SO_RCVBUF on
                        a socket.

              default   the default size of the receive buffer for a TCP socket.
                        This value overwrites the initial default buffer size from
                        the generic global net.core.rmem_default defined for all
                        protocols.  The default value is 87380 bytes.  (On Linux
                        2.4, this will be lowered to 43689 in low-memory systems.)
                        If larger receive buffer sizes are desired, this value
                        should be increased (to affect all sockets).  To employ
                        large TCP windows, the net.ipv4.tcp_window_scaling must be
                        enabled (default).

              max       the maximum size of the receive buffer used by each TCP
                        socket.  This value does not override the global
                        net.core.rmem_max.  This is not used to limit the size of
                        the receive buffer declared using SO_RCVBUF on a socket.
                        The default value is calculated using the formula

                            max(87380, min(4MB, tcp_mem[1]*PAGE_SIZE/128))

                        (On Linux 2.4, the default is 87380*2 bytes, lowered to
                        87380 in low-memory systems).

       tcp_sack (Boolean; default: enabled; since Linux 2.2)
              Enable RFC 2018 TCP Selective Acknowledgements.

       tcp_slow_start_after_idle (Boolean; default: enabled; since Linux 2.6.18)
              If enabled, provide RFC 2861 behavior and time out the congestion
              window after an idle period.  An idle period is defined as the
              current RTO (retransmission timeout).  If disabled, the congestion
              window will not be timed out after an idle period.

       tcp_stdurg (Boolean; default: disabled; since Linux 2.2)
              If this option is enabled, then use the RFC 1122 interpretation of
              the TCP urgent-pointer field.  According to this interpretation, the
              urgent pointer points to the last byte of urgent data.  If this
              option is disabled, then use the BSD-compatible interpretation of
              the urgent pointer: the urgent pointer points to the first byte
              after the urgent data.  Enabling this option may lead to
              interoperability problems.

       tcp_syn_retries (integer; default: 5; since Linux 2.2)
              The maximum number of times initial SYNs for an active TCP
              connection attempt will be retransmitted.  This value should not be
              higher than 255.  The default value is 5, which corresponds to
              approximately 180 seconds.

       tcp_synack_retries (integer; default: 5; since Linux 2.2)
              The maximum number of times a SYN/ACK segment for a passive TCP
              connection will be retransmitted.  This number should not be higher
              than 255.

       tcp_syncookies (Boolean; since Linux 2.2)
              Enable TCP syncookies.  The kernel must be compiled with
              CONFIG_SYN_COOKIES.  Send out syncookies when the syn backlog queue
              of a socket overflows.  The syncookies feature attempts to protect a
              socket from a SYN flood attack.  This should be used as a last
              resort, if at all.  This is a violation of the TCP protocol, and
              conflicts with other areas of TCP such as TCP extensions.  It can
              cause problems for clients and relays.  It is not recommended as a
              tuning mechanism for heavily loaded servers to help with overloaded
              or misconfigured conditions.  For recommended alternatives see
              tcp_max_syn_backlog, tcp_synack_retries, and tcp_abort_on_overflow.

       tcp_timestamps (Boolean; default: enabled; since Linux 2.2)
              Enable RFC 1323 TCP timestamps.

       tcp_tso_win_divisor (integer; default: 3; since Linux 2.6.9)
              This parameter controls what percentage of the congestion window can
              be consumed by a single TCP Segmentation Offload (TSO) frame.  The
              setting of this parameter is a tradeoff between burstiness and
              building larger TSO frames.

       tcp_tw_recycle (Boolean; default: disabled; since Linux 2.4)
              Enable fast recycling of TIME_WAIT sockets.  Enabling this option is
              not recommended since this causes problems when working with NAT
              (Network Address Translation).

       tcp_tw_reuse (Boolean; default: disabled; since Linux 2.4.19/2.6)
              Allow to reuse TIME_WAIT sockets for new connections when it is safe
              from protocol viewpoint.  It should not be changed without
              advice/request of technical experts.

       tcp_vegas_cong_avoid (Boolean; default: disabled; Linux 2.2 to 2.6.13)
              Enable TCP Vegas congestion avoidance algorithm.  TCP Vegas is a
              sender-side only change to TCP that anticipates the onset of
              congestion by estimating the bandwidth.  TCP Vegas adjusts the
              sending rate by modifying the congestion window.  TCP Vegas should
              provide less packet loss, but it is not as aggressive as TCP Reno.

       tcp_westwood (Boolean; default: disabled; Linux 2.4.26/2.6.3 to 2.6.13)
              Enable TCP Westwood+ congestion control algorithm.  TCP Westwood+ is
              a sender-side only modification of the TCP Reno protocol stack that
              optimizes the performance of TCP congestion control.  It is based on
              end-to-end bandwidth estimation to set congestion window and slow
              start threshold after a congestion episode.  Using this estimation,
              TCP Westwood+ adaptively sets a slow start threshold and a
              congestion window which takes into account the bandwidth used at the
              time congestion is experienced.  TCP Westwood+ significantly
              increases fairness with respect to TCP Reno in wired networks and
              throughput over wireless links.

       tcp_window_scaling (Boolean; default: enabled; since Linux 2.2)
              Enable RFC 1323 TCP window scaling.  This feature allows the use of
              a large window (> 64K) on a TCP connection, should the other end
              support it.  Normally, the 16 bit window length field in the TCP
              header limits the window size to less than 64K bytes.  If larger
              windows are desired, applications can increase the size of their
              socket buffers and the window scaling option will be employed.  If
              tcp_window_scaling is disabled, TCP will not negotiate the use of
              window scaling with the other end during connection setup.

       tcp_wmem (since Linux 2.4)
              This is a vector of 3 integers: [min, default, max].  These
              parameters are used by TCP to regulate send buffer sizes.  TCP
              dynamically adjusts the size of the send buffer from the default
              values listed below, in the range of these values, depending on
              memory available.

              min       Minimum size of the send buffer used by each TCP socket.
                        The default value is the system page size.  (On Linux 2.4,
                        the default value is 4K bytes.)  This value is used to
                        ensure that in memory pressure mode, allocations below
                        this size will still succeed.  This is not used to bound
                        the size of the send buffer declared using SO_SNDBUF on a
                        socket.

              default   The default size of the send buffer for a TCP socket.
                        This value overwrites the initial default buffer size from
                        the generic global /proc/sys/net/core/wmem_default defined
                        for all protocols.  The default value is 16K bytes.  If
                        larger send buffer sizes are desired, this value should be
                        increased (to affect all sockets).  To employ large TCP
                        windows, the /proc/sys/net/ipv4/tcp_window_scaling must be
                        set to a nonzero value (default).

              max       The maximum size of the send buffer used by each TCP
                        socket.  This value does not override the value in
                        /proc/sys/net/core/wmem_max.  This is not used to limit
                        the size of the send buffer declared using SO_SNDBUF on a
                        socket.  The default value is calculated using the formula

                            max(65536, min(4MB, tcp_mem[1]*PAGE_SIZE/128))

                        (On Linux 2.4, the default value is 128K bytes, lowered
                        64K depending on low-memory systems.)

       tcp_workaround_signed_windows (Boolean; default: disabled; since Linux
       2.6.26)
              If enabled, assume that no receipt of a window-scaling option means
              that the remote TCP is broken and treats the window as a signed
              quantity.  If disabled, assume that the remote TCP is not broken
              even if we do not receive a window scaling option from it.

Socket Options

       To set or get a TCP socket option, call getsockopt(2) to read or
       setsockopt(2) to write the option with the option level argument set to
       IPPROTO_TCP.  In addition, most IPPROTO_IP socket options are valid on TCP
       sockets.  For more information see ip(7).

       TCP_CORK (since Linux 2.2)
              If set, don't send out partial frames.  All queued partial frames
              are sent when the option is cleared again.  This is useful for
              prepending headers before calling sendfile(2), or for throughput
              optimization.  As currently implemented, there is a 200 millisecond
              ceiling on the time for which output is corked by TCP_CORK.  If this
              ceiling is reached, then queued data is automatically transmitted.
              This option can be combined with TCP_NODELAY only since Linux
              2.5.71.  This option should not be used in code intended to be
              portable.

       TCP_DEFER_ACCEPT (since Linux 2.4)
              Allow a listener to be awakened only when data arrives on the
              socket.  Takes an integer value (seconds), this can bound the
              maximum number of attempts TCP will make to complete the connection.
              This option should not be used in code intended to be portable.

       TCP_INFO (since Linux 2.4)
              Used to collect information about this socket.  The kernel returns a
              struct tcp_info as defined in the file /usr/include/linux/tcp.h.
              This option should not be used in code intended to be portable.

       TCP_KEEPCNT (since Linux 2.4)
              The maximum number of keepalive probes TCP should send before
              dropping the connection.  This option should not be used in code
              intended to be portable.

       TCP_KEEPIDLE (since Linux 2.4)
              The time (in seconds) the connection needs to remain idle before TCP
              starts sending keepalive probes, if the socket option SO_KEEPALIVE
              has been set on this socket.  This option should not be used in code
              intended to be portable.

       TCP_KEEPINTVL (since Linux 2.4)
              The time (in seconds) between individual keepalive probes.  This
              option should not be used in code intended to be portable.

       TCP_LINGER2 (since Linux 2.4)
              The lifetime of orphaned FIN_WAIT2 state sockets.  This option can
              be used to override the system-wide setting in the file
              /proc/sys/net/ipv4/tcp_fin_timeout for this socket.  This is not to
              be confused with the socket(7) level option SO_LINGER.  This option
              should not be used in code intended to be portable.

       TCP_MAXSEG
              The maximum segment size for outgoing TCP packets.  In Linux 2.2 and
              earlier, and in Linux 2.6.28 and later, if this option is set before
              connection establishment, it also changes the MSS value announced to
              the other end in the initial packet.  Values greater than the
              (eventual) interface MTU have no effect.  TCP will also impose its
              minimum and maximum bounds over the value provided.

       TCP_NODELAY
              If set, disable the Nagle algorithm.  This means that segments are
              always sent as soon as possible, even if there is only a small
              amount of data.  When not set, data is buffered until there is a
              sufficient amount to send out, thereby avoiding the frequent sending
              of small packets, which results in poor utilization of the network.
              This option is overridden by TCP_CORK; however, setting this option
              forces an explicit flush of pending output, even if TCP_CORK is
              currently set.

       TCP_QUICKACK (since Linux 2.4.4)
              Enable quickack mode if set or disable quickack mode if cleared.  In
              quickack mode, acks are sent immediately, rather than delayed if
              needed in accordance to normal TCP operation.  This flag is not
              permanent, it only enables a switch to or from quickack mode.
              Subsequent operation of the TCP protocol will once again enter/leave
              quickack mode depending on internal protocol processing and factors
              such as delayed ack timeouts occurring and data transfer.  This
              option should not be used in code intended to be portable.

       TCP_SYNCNT (since Linux 2.4)
              Set the number of SYN retransmits that TCP should send before
              aborting the attempt to connect.  It cannot exceed 255.  This option
              should not be used in code intended to be portable.

       TCP_WINDOW_CLAMP (since Linux 2.4)
              Bound the size of the advertised window to this value.  The kernel
              imposes a minimum size of SOCK_MIN_RCVBUF/2.  This option should not
              be used in code intended to be portable.

Sockets API

       TCP provides limited support for out-of-band data, in the form of (a single
       byte of) urgent data.  In Linux this means if the other end sends newer
       out-of-band data the older urgent data is inserted as normal data into the
       stream (even when SO_OOBINLINE is not set).  This differs from BSD-based
       stacks.

       Linux uses the BSD compatible interpretation of the urgent pointer field by
       default.  This violates RFC 1122, but is required for interoperability with
       other stacks.  It can be changed via /proc/sys/net/ipv4/tcp_stdurg.

       It is possible to peek at out-of-band data using the recv(2) MSG_PEEK flag.

       Since version 2.4, Linux supports the use of MSG_TRUNC in the flags
       argument of recv(2) (and recvmsg(2)).  This flag causes the received bytes
       of data to be discarded, rather than passed back in a caller-supplied
       buffer.  Since Linux 2.4.4, MSG_PEEK also has this effect when used in
       conjunction with MSG_OOB to receive out-of-band data.

Ioctls

       The following ioctl(2) calls return information in value.  The correct
       syntax is:

              int value;
              error = ioctl(tcp_socket, ioctl_type, &value);

       ioctl_type is one of the following:

       SIOCINQ
              Returns the amount of queued unread data in the receive buffer.  The
              socket must not be in LISTEN state, otherwise an error (EINVAL) is
              returned.  SIOCINQ is defined in <linux/sockios.h>.  Alternatively,
              you can use the synonymous FIONREAD, defined in <sys/ioctl.h>.

       SIOCATMARK
              Returns true (i.e., value is nonzero) if the inbound data stream is
              at the urgent mark.

              If the SO_OOBINLINE socket option is set, and SIOCATMARK returns
              true, then the next read from the socket will return the urgent
              data.  If the SO_OOBINLINE socket option is not set, and SIOCATMARK
              returns true, then the next read from the socket will return the
              bytes following the urgent data (to actually read the urgent data
              requires the recv(MSG_OOB) flag).

              Note that a read never reads across the urgent mark.  If an
              application is informed of the presence of urgent data via select(2)
              (using the exceptfds argument) or through delivery of a SIGURG
              signal, then it can advance up to the mark using a loop which
              repeatedly tests SIOCATMARK and performs a read (requesting any
              number of bytes) as long as SIOCATMARK returns false.

       SIOCOUTQ
              Returns the amount of unsent data in the socket send queue.  The
              socket must not be in LISTEN state, otherwise an error (EINVAL) is
              returned.  SIOCOUTQ is defined in <linux/sockios.h>.  Alternatively,
              you can use the synonymous TIOCOUTQ, defined in <sys/ioctl.h>.

Error Handling

       When a network error occurs, TCP tries to resend the packet.  If it doesn't
       succeed after some time, either ETIMEDOUT or the last received error on
       this connection is reported.

       Some applications require a quicker error notification.  This can be
       enabled with the IPPROTO_IP level IP_RECVERR socket option.  When this
       option is enabled, all incoming errors are immediately passed to the user
       program.  Use this option with care -- it makes TCP less tolerant to
       routing changes and other normal network conditions.

ERRORS top

       EAFNOTSUPPORT
              Passed socket address type in sin_family was not AF_INET.

       EPIPE  The other end closed the socket unexpectedly or a read is executed
              on a shut down socket.

       ETIMEDOUT
              The other end didn't acknowledge retransmitted data after some time.

       Any errors defined for ip(7) or the generic socket layer may also be
       returned for TCP.

VERSIONS top

       Support for Explicit Congestion Notification, zero-copy sendfile(2),
       reordering support and some SACK extensions (DSACK) were introduced in 2.4.
       Support for forward acknowledgement (FACK), TIME_WAIT recycling, and per-
       connection keepalive socket options were introduced in 2.3.

BUGS top

       Not all errors are documented.
       IPv6 is not described.

SEE ALSO top

       accept(2), bind(2), connect(2), getsockopt(2), listen(2), recvmsg(2),
       sendfile(2), sendmsg(2), socket(2), ip(7), socket(7)

       RFC 793 for the TCP specification.
       RFC 1122 for the TCP requirements and a description of the Nagle algorithm.
       RFC 1323 for TCP timestamp and window scaling options.
       RFC 1337 for a description of TIME_WAIT assassination hazards.
       RFC 3168 for a description of Explicit Congestion Notification.
       RFC 2581 for TCP congestion control algorithms.
       RFC 2018 and RFC 2883 for SACK and extensions to SACK.

COLOPHON top

       This page is part of release 3.45 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                               2012-04-23                              TCP(7)


tsearch(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TSEARCH(3)                   Linux Programmer's Manual                  TSEARCH(3)

NAME top

       tsearch, tfind, tdelete, twalk, tdestroy - manage a binary tree

SYNOPSIS top

       #include <search.h>

       void *tsearch(const void *key, void **rootp,
                       int (*compar)(const void *, const void *));

       void *tfind(const void *key, const void **rootp,
                       int (*compar)(const void *, const void *));

       void *tdelete(const void *key, void **rootp,
                       int (*compar)(const void *, const void *));

       void twalk(const void *root, void (*action)(const void *nodep,
                                          const VISIT which,
                                          const int depth));

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <search.h>

       void tdestroy(void *root, void (*free_node)(void *nodep));

DESCRIPTION top

       tsearch(), tfind(), twalk(), and tdelete() manage a binary tree.  They are
       generalized from Knuth (6.2.2) Algorithm T.  The first field in each node
       of the tree is a pointer to the corresponding data item.  (The calling
       program must store the actual data.)  compar points to a comparison
       routine, which takes pointers to two items.  It should return an integer
       which is negative, zero, or positive, depending on whether the first item
       is less than, equal to, or greater than the second.

       tsearch() searches the tree for an item.  key points to the item to be
       searched for.  rootp points to a variable which points to the root of the
       tree.  If the tree is empty, then the variable that rootp points to should
       be set to NULL.  If the item is found in the tree, then tsearch() returns a
       pointer to it.  If it is not found, then tsearch() adds it, and returns a
       pointer to the newly added item.

       tfind() is like tsearch(), except that if the item is not found, then
       tfind() returns NULL.

       tdelete() deletes an item from the tree.  Its arguments are the same as for
       tsearch().

       twalk() performs depth-first, left-to-right traversal of a binary tree.
       root points to the starting node for the traversal.  If that node is not
       the root, then only part of the tree will be visited.  twalk() calls the
       user function action each time a node is visited (that is, three times for
       an internal node, and once for a leaf).  action, in turn, takes three
       arguments.  The first argument is a pointer to the node being visited.  The
       structure of the node is unspecified, but it is possible to cast the
       pointer to a pointer-to-pointer-to-element in order to access the element
       stored within the node.  The application must not modify the structure
       pointed to by this argument.  The second argument is an integer which takes
       one of the values preorder, postorder, or endorder depending on whether
       this is the first, second, or third visit to the internal node, or the
       value leaf if this is the single visit to a leaf node.  (These symbols are
       defined in <search.h>.)  The third argument is the depth of the node; the
       root node has depth zero.

       (More commonly, preorder, postorder, and endorder are known as preorder,
       inorder, and postorder: before visiting the children, after the first and
       before the second, and after visiting the children.  Thus, the choice of
       name postorder is rather confusing.)

       tdestroy() removes the whole tree pointed to by root, freeing all resources
       allocated by the tsearch() function.  For the data in each tree node the
       function free_node is called.  The pointer to the data is passed as the
       argument to the function.  If no such work is necessary, free_node must
       point to a function doing nothing.

RETURN VALUE top

       tsearch() returns a pointer to a matching item in the tree, or to the newly
       added item, or NULL if there was insufficient memory to add the item.
       tfind() returns a pointer to the item, or NULL if no match is found.  If
       there are multiple elements that match the key, the element returned is
       unspecified.

       tdelete() returns a pointer to the parent of the item deleted, or NULL if
       the item was not found.

       tsearch(), tfind(), and tdelete() also return NULL if rootp was NULL on
       entry.

CONFORMING TO top

       SVr4, POSIX.1-2001.  The function tdestroy() is a GNU extension.

NOTES top

       twalk() takes a pointer to the root, while the other functions take a
       pointer to a variable which points to the root.

       tdelete() frees the memory required for the node in the tree.  The user is
       responsible for freeing the memory for the corresponding data.

       The example program depends on the fact that twalk() makes no further
       reference to a node after calling the user function with argument
       "endorder" or "leaf".  This works with the GNU library implementation, but
       is not in the System V documentation.

EXAMPLE top

       The following program inserts twelve random numbers into a binary tree,
       where duplicate numbers are collapsed, then prints the numbers in order.

       #define _GNU_SOURCE     /* Expose declaration of tdestroy() */
       #include <search.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <time.h>

       void *root = NULL;

       void *
       xmalloc(unsigned n)
       {
           void *p;
           p = malloc(n);
           if (p)
               return p;
           fprintf(stderr, "insufficient memory\n");
           exit(EXIT_FAILURE);
       }

       int
       compare(const void *pa, const void *pb)
       {
           if (*(int *) pa < *(int *) pb)
               return -1;
           if (*(int *) pa > *(int *) pb)
               return 1;
           return 0;
       }

       void
       action(const void *nodep, const VISIT which, const int depth)
       {
           int *datap;

           switch (which) {
           case preorder:
               break;
           case postorder:
               datap = *(int **) nodep;
               printf("%6d\n", *datap);
               break;
           case endorder:
               break;
           case leaf:
               datap = *(int **) nodep;
               printf("%6d\n", *datap);
               break;
           }
       }

       int
       main(void)
       {
           int i, *ptr;
           void *val;

           srand(time(NULL));
           for (i = 0; i < 12; i++) {
               ptr = xmalloc(sizeof(int));
               *ptr = rand() & 0xff;
               val = tsearch((void *) ptr, &root, compare);
               if (val == NULL)
                   exit(EXIT_FAILURE);
               else if ((*(int **) val) != ptr)
                   free(ptr);
           }
           twalk(root, action);
           tdestroy(root, free);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       bsearch(3), hsearch(3), lsearch(3), qsort(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-03                          TSEARCH(3)


tee(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TEE(2)                       Linux Programmer's Manual                      TEE(2)

NAME top

       tee - duplicating pipe content

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <fcntl.h>

       ssize_t tee(int fd_in, int fd_out, size_t len, unsigned int flags);

DESCRIPTION top

       tee() duplicates up to len bytes of data from the pipe referred to by the
       file descriptor fd_in to the pipe referred to by the file descriptor
       fd_out.  It does not consume the data that is duplicated from fd_in;
       therefore, that data can be copied by a subsequent splice(2).

       flags is a series of modifier flags, which share the name space with
       splice(2) and vmsplice(2):

       SPLICE_F_MOVE      Currently has no effect for tee(); see splice(2).

       SPLICE_F_NONBLOCK  Do not block on I/O; see splice(2) for further details.

       SPLICE_F_MORE      Currently has no effect for tee(), but may be
                          implemented in the future; see splice(2).

       SPLICE_F_GIFT      Unused for tee(); see vmsplice(2).

RETURN VALUE top

       Upon successful completion, tee() returns the number of bytes that were
       duplicated between the input and output.  A return value of 0 means that
       there was no data to transfer, and it would not make sense to block,
       because there are no writers connected to the write end of the pipe
       referred to by fd_in.

       On error, tee() returns -1 and errno is set to indicate the error.

ERRORS top

       EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out refer
              to the same pipe.

       ENOMEM Out of memory.

VERSIONS top

       The tee() system call first appeared in Linux 2.6.17; library support was
       added to glibc in version 2.5.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       Conceptually, tee() copies the data between the two pipes.  In reality no
       real data copying takes place though: under the covers, tee() assigns data
       in the output by merely grabbing a reference to the input.

EXAMPLE top

       The following example implements a basic tee(1) program using the tee()
       system call.

       #define _GNU_SOURCE
       #include <fcntl.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <errno.h>
       #include <limits.h>

       int
       main(int argc, char *argv[])
       {
           int fd;
           int len, slen;

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

           fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
           if (fd == -1) {
               perror("open");
               exit(EXIT_FAILURE);
           }

           do {
               /*
                * tee stdin to stdout.
                */
               len = tee(STDIN_FILENO, STDOUT_FILENO,
                         INT_MAX, SPLICE_F_NONBLOCK);

               if (len < 0) {
                   if (errno == EAGAIN)
                       continue;
                   perror("tee");
                   exit(EXIT_FAILURE);
               } else
                   if (len == 0)
                       break;

               /*
                * Consume stdin by splicing it to a file.
                */
               while (len > 0) {
                   slen = splice(STDIN_FILENO, NULL, fd, NULL,
                                 len, SPLICE_F_MOVE);
                   if (slen < 0) {
                       perror("splice");
                       break;
                   }
                   len -= slen;
               }
           } while (1);

           close(fd);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       splice(2), vmsplice(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                              TEE(2)


telldir(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TELLDIR(3)                   Linux Programmer's Manual                  TELLDIR(3)

NAME top

       telldir - return current location in directory stream

SYNOPSIS top

       #include <dirent.h>

       long telldir(DIR *dirp);

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

       telldir(): _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       The telldir() function returns the current location associated with the
       directory stream dirp.

RETURN VALUE top

       On success, the telldir() function returns the current location in the
       directory stream.  On error, -1 is returned, and errno is set
       appropriately.

ERRORS top

       EBADF  Invalid directory stream descriptor dirp.

CONFORMING TO top

       4.3BSD, POSIX.1-2001.

NOTES top

       In glibc up to version 2.1.1, the return type of telldir() was off_t.
       POSIX.1-2001 specifies long, and this is the type used since glibc 2.1.2.

SEE ALSO top

       closedir(3), opendir(3), readdir(3), rewinddir(3), scandir(3), seekdir(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2009-03-11                          TELLDIR(3)


tempnam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TEMPNAM(3)                   Linux Programmer's Manual                  TEMPNAM(3)

NAME top

       tempnam - create a name for a temporary file

SYNOPSIS top

       #include <stdio.h>

       char *tempnam(const char *dir, const char *pfx);

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

       tempnam(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The tempnam() function returns a pointer to a string that is a valid
       filename, and such that a file with this name did not exist when tempnam()
       checked.  The filename suffix of the pathname generated will start with pfx
       in case pfx is a non-NULL string of at most five bytes.  The directory
       prefix part of the pathname generated is required to be "appropriate"
       (often that at least implies writable).

       Attempts to find an appropriate directory go through the following steps:

       a) In case the environment variable TMPDIR exists and contains the name of
          an appropriate directory, that is used.

       b) Otherwise, if the dir argument is non-NULL and appropriate, it is used.

       c) Otherwise, P_tmpdir (as defined in <stdio.h>) is used when appropriate.

       d) Finally an implementation-defined directory may be used.

       The string returned by tempnam() is allocated using malloc(3) and hence
       should be freed by free(3).

RETURN VALUE top

       The tempnam() function returns a pointer to a unique temporary filename, or
       NULL if a unique name cannot be generated.

ERRORS top

       ENOMEM Allocation of storage failed.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.  POSIX.1-2008 marks tempnam() as obsolete.

NOTES top

       Although tempnam() generates names that are difficult to guess, it is
       nevertheless possible that between the time that tempnam() returns a
       pathname, and the time that the program opens it, another program might
       create that pathname using open(2), or create it as a symbolic link.  This
       can lead to security holes.  To avoid such possibilities, use the open(2)
       O_EXCL flag to open the pathname.  Or better yet, use mkstemp(3) or
       tmpfile(3).

       SUSv2 does not mention the use of TMPDIR; glibc will use it only when the
       program is not set-user-ID.  On SVr4, the directory used under d) is /tmp
       (and this is what glibc does).

       Because it dynamically allocates memory used to return the pathname,
       tempnam() is reentrant, and thus thread safe, unlike tmpnam(3).

       The tempnam() function generates a different string each time it is called,
       up to TMP_MAX (defined in <stdio.h>) times.  If it is called more than
       TMP_MAX times, the behavior is implementation defined.

       tempnam() uses at most the first five bytes from pfx.

       The glibc implementation of tempnam() will fail with the error EEXIST upon
       failure to find a unique name.

BUGS top

       The precise meaning of "appropriate" is undefined; it is unspecified how
       accessibility of a directory is determined.

       Never use this function.  Use mkstemp(3) or tmpfile(3) instead.

SEE ALSO top

       mkstemp(3), mktemp(3), tmpfile(3), tmpnam(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-06                          TEMPNAM(3)


termcap(5) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

TERMCAP(5)                   Linux Programmer's Manual                  TERMCAP(5)

NAME top

       termcap - terminal capability database

DESCRIPTION top

       The termcap database is an obsolete facility for describing the
       capabilities of character-cell terminals and printers.  It is retained only
       for capability with old programs; new ones should use the terminfo(5)
       database and associated libraries.

       /etc/termcap is an ASCII file (the database master) that lists the
       capabilities of many different types of terminals.  Programs can read
       termcap to find the particular escape codes needed to control the visual
       attributes of the terminal actually in use.  (Other aspects of the terminal
       are handled by stty(1).)  The termcap database is indexed on the TERM
       environment variable.

       Termcap entries must be defined on a single logical line, with '\' used to
       suppress the newline.  Fields are separated by ':'.  The first field of
       each entry starts at the left-hand margin, and contains a list of names for
       the terminal, separated by '|'.

       The first subfield may (in BSD termcap entries from versions 4.3 and prior)
       contain a short name consisting of two characters.  This short name may
       consist of capital or small letters.  In 4.4BSD termcap entries this field
       is omitted.

       The second subfield (first, in the newer 4.4BSD format) contains the name
       used by the environment variable TERM.  It should be spelled in lowercase
       letters.  Selectable hardware capabilities should be marked by appending a
       hyphen and a suffix to this name.  See below for an example.  Usual
       suffixes are w (more than 80 characters wide), am (automatic margins), nam
       (no automatic margins), and rv (reverse video display).  The third subfield
       contains a long and descriptive name for this termcap entry.

       Subsequent fields contain the terminal capabilities; any continued
       capability lines must be indented one tab from the left margin.

       Although there is no defined order, it is suggested to write first boolean,
       then numeric, and then string capabilities, each sorted alphabetically
       without looking at lower or upper spelling.  Capabilities of similar
       functions can be written in one line.

       Example for:

       Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\
       Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\
       Boolean: :bs:\
       Numeric: :co#80:\
       String: :sr=\E[H:\

Boolean Capabilities

       5i   Printer will not echo on screen
       am   Automatic margins which means automatic line wrap
       bs   Control-H (8 dec.) performs a backspace
       bw   Backspace on left margin wraps to previous line and right margin
       da   Display retained above screen
       db   Display retained below screen
       eo   A space erases all characters at cursor position
       es   Escape sequences and special characters work in status line
       gn   Generic device
       hc   This is a hardcopy terminal
       HC   The cursor is hard to see when not on bottom line
       hs   Has a status line
       hz   Hazeltine bug, the terminal can not print tilde characters
       in   Terminal inserts null bytes, not spaces, to fill whitespace
       km   Terminal has a meta key
       mi   Cursor movement works in insert mode
       ms   Cursor movement works in standout/underline mode
       NP   No pad character
       NR   ti does not reverse te
       nx   No padding, must use XON/XOFF
       os   Terminal can overstrike
       ul   Terminal underlines although it can not overstrike
       xb   Beehive glitch, f1 sends ESCAPE, f2 sends ^C
       xn   Newline/wraparound glitch
       xo   Terminal uses xon/xoff protocol
       xs   Text typed over standout text will be displayed in standout
       xt   Teleray glitch, destructive tabs and odd standout mode

Numeric Capabilities

       co   Number of columns
       dB   Delay in milliseconds for backspace on hardcopy terminals
       dC   Delay in milliseconds for carriage return on hardcopy terminals
       dF   Delay in milliseconds for form feed on hardcopy terminals
       dN   Delay in milliseconds for new line on hardcopy terminals
       dT   Delay in milliseconds for tabulator stop on hardcopy terminals
       dV   Delay in milliseconds for vertical tabulator stop on
            hardcopy terminals
       it   Difference between tab positions
       lh   Height of soft labels
       lm   Lines of memory
       lw   Width of soft labels
       li   Number of lines
       Nl   Number of soft labels
       pb   Lowest baud rate which needs padding
       sg   Standout glitch
       ug   Underline glitch
       vt   virtual terminal number
       ws   Width of status line if different from screen width

String Capabilities

       !1   shifted save key
       !2   shifted suspend key
       !3   shifted undo key
       #1   shifted help key
       #2   shifted home key
       #3   shifted input key
       #4   shifted cursor left key
       %0   redo key
       %1   help key
       %2   mark key
       %3   message key
       %4   move key
       %5   next-object key
       %6   open key
       %7   options key
       %8   previous-object key
       %9   print key
       %a   shifted message key
       %b   shifted move key
       %c   shifted next key
       %d   shifted options key
       %e   shifted previous key
       %f   shifted print key
       %g   shifted redo key
       %h   shifted replace key
       %i   shifted cursor right key
       %j   shifted resume key
       &0   shifted cancel key
       &1   reference key
       &2   refresh key
       &3   replace key
       &4   restart key
       &5   resume key
       &6   save key
       &7   suspend key
       &8   undo key
       &9   shifted begin key
       *0   shifted find key
       *1   shifted command key
       *2   shifted copy key
       *3   shifted create key
       *4   shifted delete character
       *5   shifted delete line
       *6   select key
       *7   shifted end key
       *8   shifted clear line key
       *9   shifted exit key
       @0   find key
       @1   begin key
       @2   cancel key
       @3   close key
       @4   command key
       @5   copy key
       @6   create key
       @7   end key
       @8   enter/send key
       @9   exit key
       al   Insert one line
       AL   Insert %1 lines
       ac   Pairs of block graphic characters to map alternate character set
       ae   End alternative character set
       as   Start alternative character set for block graphic characters
       bc   Backspace, if not ^H
       bl   Audio bell
       bt   Move to previous tab stop
       cb   Clear from beginning of line to cursor
       cc   Dummy command character
       cd   Clear to end of screen
       ce   Clear to end of line
       ch   Move cursor horizontally only to column %1
       cl   Clear screen and cursor home
       cm   Cursor move to row %1 and column %2 (on screen)
       CM   Move cursor to row %1 and column %2 (in memory)
       cr   Carriage return
       cs   Scroll region from line %1 to %2
       ct   Clear tabs
       cv   Move cursor vertically only to line %1
       dc   Delete one character
       DC   Delete %1 characters
       dl   Delete one line
       DL   Delete %1 lines
       dm   Begin delete mode
       do   Cursor down one line
       DO   Cursor down #1 lines
       ds   Disable status line
       eA   Enable alternate character set
       ec   Erase %1 characters starting at cursor
       ed   End delete mode
       ei   End insert mode
       ff   Formfeed character on hardcopy terminals
       fs   Return character to its position before going to status line
       F1   The string sent by function key f11
       F2   The string sent by function key f12
       F3   The string sent by function key f13
       ...  ...
       F9   The string sent by function key f19
       FA   The string sent by function key f20
       FB   The string sent by function key f21
       ...  ...
       FZ   The string sent by function key f45
       Fa   The string sent by function key f46
       Fb   The string sent by function key f47
       ...  ...
       Fr   The string sent by function key f63
       hd   Move cursor a half line down
       ho   Cursor home
       hu   Move cursor a half line up
       i1   Initialization string 1 at login
       i3   Initialization string 3 at login
       is   Initialization string 2 at login
       ic   Insert one character
       IC   Insert %1 characters
       if   Initialization file
       im   Begin insert mode
       ip   Insert pad time and needed special characters after insert
       iP   Initialization program
       K1   upper left key on keypad
       K2   center key on keypad
       K3   upper right key on keypad
       K4   bottom left key on keypad
       K5   bottom right key on keypad
       k0   Function key 0
       k1   Function key 1
       k2   Function key 2
       k3   Function key 3
       k4   Function key 4
       k5   Function key 5
       k6   Function key 6
       k7   Function key 7
       k8   Function key 8
       k9   Function key 9
       k;   Function key 10
       ka   Clear all tabs key
       kA   Insert line key
       kb   Backspace key
       kB   Back tab stop
       kC   Clear screen key
       kd   Cursor down key
       kD   Key for delete character under cursor
       ke   turn keypad off
       kE   Key for clear to end of line
       kF   Key for scrolling forward/down
       kh   Cursor home key
       kH   Cursor hown down key
       kI   Insert character/Insert mode key
       kl   Cursor left key
       kL   Key for delete line
       kM   Key for exit insert mode
       kN   Key for next page
       kP   Key for previous page
       kr   Cursor right key
       kR   Key for scrolling backward/up
       ks   Turn keypad on
       kS   Clear to end of screen key
       kt   Clear this tab key
       kT   Set tab here key
       ku   Cursor up key
       l0   Label of zeroth function key, if not f0
       l1   Label of first function key, if not f1
       l2   Label of first function key, if not f2
       ...  ...
       la   Label of tenth function key, if not f10
       le   Cursor left one character
       ll   Move cursor to lower left corner
       LE   Cursor left %1 characters
       LF   Turn soft labels off
       LO   Turn soft labels on
       mb   Start blinking
       MC   Clear soft margins
       md   Start bold mode
       me   End all mode like so, us, mb, md and mr
       mh   Start half bright mode
       mk   Dark mode (Characters invisible)
       ML   Set left soft margin
       mm   Put terminal in meta mode
       mo   Put terminal out of meta mode
       mp   Turn on protected attribute
       mr   Start reverse mode
       MR   Set right soft margin
       nd   Cursor right one character
       nw   Carriage return command
       pc   Padding character
       pf   Turn printer off
       pk   Program key %1 to send string %2 as if typed by user
       pl   Program key %1 to execute string %2 in local mode
       pn   Program soft label %1 to show string %2
       po   Turn the printer on
       pO   Turn the printer on for %1 (<256) bytes
       ps   Print screen contents on printer
       px   Program key %1 to send string %2 to computer
       r1   Reset string 1 to set terminal to sane modes
       r2   Reset string 2 to set terminal to sane modes
       r3   Reset string 3 to set terminal to sane modes
       RA   disable automatic margins
       rc   Restore saved cursor position
       rf   Reset string filename
       RF   Request for input from terminal
       RI   Cursor right %1 characters
       rp   Repeat character %1 for %2 times
       rP   Padding after character sent in replace mode
       rs   Reset string
       RX   Turn off XON/XOFF flow control
       sa   Set %1 %2 %3 %4 %5 %6 %7 %8 %9 attributes
       SA   enable automatic margins
       sc   Save cursor position
       se   End standout mode
       sf   Normal scroll one line
       SF   Normal scroll %1 lines
       so   Start standout mode
       sr   Reverse scroll
       SR   scroll back %1 lines
       st   Set tabulator stop in all rows at current column
       SX   Turn on XON/XOFF flow control
       ta   move to next hardware tab
       tc   Read in terminal description from another entry
       te   End program that uses cursor motion
       ti   Begin program that uses cursor motion
       ts   Move cursor to column %1 of status line
       uc   Underline character under cursor and move cursor right
       ue   End underlining
       up   Cursor up one line
       UP   Cursor up %1 lines
       us   Start underlining
       vb   Visible bell
       ve   Normal cursor visible
       vi   Cursor invisible
       vs   Standout cursor
       wi   Set window from line %1 to %2 and column %3 to %4
       XF   XOFF character if not ^S

       There are several ways of defining the control codes for string
       capabilities:

       Every normal character represents itself, except '^', '\', and '%'.

       A ^x means Control-x.  Control-A equals 1 decimal.

       \x means a special code.  x can be one of the following characters:
              E Escape (27)
              n Linefeed (10)
              r Carriage return (13)
              t Tabulation (9)
              b Backspace (8)
              f Form feed (12)
              0 Null character.  A \xxx specifies the octal character xxx.

       i      Increments parameters by one.

       r      Single parameter capability

       +      Add value of next character to this parameter and do binary output

       2      Do ASCII output of this parameter with a field with of 2

       d      Do ASCII output of this parameter with a field with of 3

       %      Print a '%'

       If you use binary output, then you should avoid the null character ('\0')
       because it terminates the string.  You should reset tabulator expansion if
       a tabulator can be the binary output of a parameter.

       Warning:
              The above metacharacters for parameters may be wrong, they document
              Minix termcap which may not be compatible with Linux termcap.

       The block graphic characters can be specified by three string capabilities:

       as     start the alternative charset

       ae     end it

       ac     pairs of characters.  The first character is the name of the block
              graphic symbol and the second characters is its definition.

       The following names are available:

       +    right arrow (>)
       ,    left arrow (<)
       .    down arrow (v)
       0    full square (#)
       I    lantern (#)
       -    upper arrow (^)
       '    rhombus (+)
       a    chess board (:)
       f    degree (')
       g    plus-minus (#)
       h    square (#)
       j    right bottom corner (+)
       k    right upper corner (+)
       l    left upper corner (+)
       m    left bottom corner (+)
       n    cross (+)
       o    upper horizontal line (-)
       q    middle horizontal line (-)
       s    bottom horizontal line (_)
       t    left tee (+)
       u    right tee (+)
       v    bottom tee (+)
       w    normal tee (+)
       x    vertical line (|)
       ~    paragraph (???)

       The values in parentheses are suggested defaults which are used by curses,
       if the capabilities are missing.

SEE ALSO top

       ncurses(3), termcap(3), terminfo(5)

COLOPHON top

       This page is part of release 3.45 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                               1996-10-21                          TERMCAP(5)


termio(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

TERMIO(7)                    Linux Programmer's Manual                   TERMIO(7)

NAME top

       termio - System V terminal driver interface

DESCRIPTION top

       termio is the name of the old System V terminal driver interface.  This
       interface defined a termio structure used to store terminal settings, and a
       range of ioctl(2) operations to get and set terminal attributes.

       The termio interface is now obsolete: POSIX.1-1990 standardized a modified
       version of this interface, under the name termios.  The POSIX.1 data
       structure differs slightly from the System V version, and POSIX.1 defined a
       suite of functions to replace the various ioctl(2) operations that existed
       in System V.  (This was done because ioctl(2) was unstandardized, and its
       variadic third argument does not allow argument type checking.)

       If you're looking for page called "termio", then you can probably find most
       of the information that you seek in either termios(3) or tty_ioctl(4).

SEE ALSO top

       termios(3), tty_ioctl(4)

COLOPHON top

       This page is part of release 3.45 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                               2006-12-28                           TERMIO(7)


tgamma(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TGAMMA(3)                    Linux Programmer's Manual                   TGAMMA(3)

NAME top

       tgamma, tgammaf, tgammal - true gamma function

SYNOPSIS top

       #include <math.h>

       double tgamma(double x);
       float tgammaf(float x);
       long double tgammal(long double x);

       Link with -lm.

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

       tgamma(), tgammaf(), tgammal():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       The Gamma function is defined by

           Gamma(x) = integral from 0 to infinity of t^(x-1) e^-t dt

       It is defined for every real number except for nonpositive integers.  For
       nonnegative integral m one has

           Gamma(m+1) = m!

       and, more generally, for all x:

           Gamma(x+1) = x * Gamma(x)

       Furthermore, the following is valid for all values of x outside the poles:

           Gamma(x) * Gamma(1 - x) = PI / sin(PI * x)

RETURN VALUE top

       On success, these functions return Gamma(x).

       If x is a NaN, a NaN is returned.

       If x is positive infinity, positive infinity is returned.

       If x is a negative integer, or is negative infinity, a domain error occurs,
       and a NaN is returned.

       If the result overflows, a range error occurs, and the functions return
       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively, with the correct
       mathematical sign.

       If the result underflows, a range error occurs, and the functions return 0,
       with the correct mathematical sign.

       If x is -0 or +0, a pole error occurs, and the functions return HUGE_VAL,
       HUGE_VALF, or HUGE_VALL, respectively, with the same sign as the 0.

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is a negative integer, or negative infinity
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised (but see BUGS).

       Pole error: x is +0 or -0
              errno is set to ERANGE.  A divide-by-zero floating-point exception
              (FE_DIVBYZERO) is raised.

       Range error: result overflow
              errno is set to ERANGE.  An overflow floating-point exception
              (FE_OVERFLOW) is raised.

       glibc also gives the following error which is not specified in C99 or
       POSIX.1-2001.

       Range error: result underflow
              An underflow floating-point exception (FE_UNDERFLOW) is raised.

              errno is not set for this case.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       This function had to be called "true gamma function" since there is already
       a function gamma(3) that returns something else (see gamma(3) for details).

BUGS top

       If x is negative infinity, errno is not set (it should be set to EDOM).

       In glibc versions 2.3.3 and earlier, an argument of +0 or -0 incorrectly
       produced a domain error (errno set to EDOM and an FE_INVALID exception
       raised), rather than a pole error.

SEE ALSO top

       gamma(3), lgamma(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                           TGAMMA(3)


tkill(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TKILL(2)                     Linux Programmer's Manual                    TKILL(2)

NAME top

       tkill, tgkill - send a signal to a thread

SYNOPSIS top

       int tkill(int tid, int sig);

       int tgkill(int tgid, int tid, int sig);

       Note: There are no glibc wrappers for these system calls; see NOTES.

DESCRIPTION top

       tgkill() sends the signal sig to the thread with the thread ID tid in the
       thread group tgid.  (By contrast, kill(2) can only be used to send a signal
       to a process (i.e., thread group) as a whole, and the signal will be
       delivered to an arbitrary thread within that process.)

       tkill() is an obsolete predecessor to tgkill().  It only allows the target
       thread ID to be specified, which may result in the wrong thread being
       signaled if a thread terminates and its thread ID is recycled.  Avoid using
       this system call.

       If tgid is specified as -1, tgkill() is equivalent to tkill().

       These are the raw system call interfaces, meant for internal thread library
       use.

RETURN VALUE top

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

ERRORS top

       EINVAL An invalid thread ID, thread group ID, or signal was specified.

       EPERM  Permission denied.  For the required permissions, see kill(2).

       ESRCH  No process with the specified thread ID (and thread group ID)
              exists.

VERSIONS top

       tkill() is supported since Linux 2.4.19 / 2.5.4.  tgkill() was added in
       Linux 2.5.75.

CONFORMING TO top

       tkill() and tgkill() are Linux-specific and should not be used in programs
       that are intended to be portable.

NOTES top

       See the description of CLONE_THREAD in clone(2) for an explanation of
       thread groups.

       Glibc does not provide wrappers for these system calls; call them using
       syscall(2).

SEE ALSO top

       clone(2), gettid(2), kill(2), rt_sigqueueinfo(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-07-13                            TKILL(2)


time(1) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXIT STATUS | ENVIRONMENT | GNU VERSION | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TIME(1)                         Linux User's Manual                        TIME(1)

NAME top

       time - time a simple command or give resource usage

SYNOPSIS top

       time [options] command [arguments...]

DESCRIPTION top

       The time command runs the specified program command with the given
       arguments.  When command finishes, time writes a message to standard error
       giving timing statistics about this program run.  These statistics consist
       of (i) the elapsed real time between invocation and termination, (ii) the
       user CPU time (the sum of the tms_utime and tms_cutime values in a struct
       tms as returned by times(2)), and (iii) the system CPU time (the sum of the
       tms_stime and tms_cstime values in a struct tms as returned by times(2)).

       Note: some shells (e.g., bash(1)) have a built-in time command that
       provides less functionality than the command described here.  To access the
       real command, you may need to specify its pathname (something like
       /usr/bin/time).

OPTIONS top

       -p     When in the POSIX locale, use the precise traditional format

                  "real %f\nuser %f\nsys %f\n"

              (with numbers in seconds) where the number of decimals in the output
              for %f is unspecified but is sufficient to express the clock tick
              accuracy, and at least one.

EXIT STATUS top

       If command was invoked, the exit status is that of command.  Otherwise it
       is 127 if command could not be found, 126 if it could be found but could
       not be invoked, and some other nonzero value (1-125) if something else went
       wrong.

ENVIRONMENT top

       The variables LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC, NLSPATH, and
       PATH are used.  The last one to search for command.  The remaining ones for
       the text and formatting of the output.

GNU VERSION top

       Below a description of the GNU 1.7 version of time.  Disregarding the name
       of the utility, GNU makes it output lots of useful information, not only
       about time used, but also on other resources like memory, I/O and IPC calls
       (where available).  The output is formatted using a format string that can
       be specified using the -f option or the TIME environment variable.

       The default format string is:

           %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
           %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps

       When the -p option is given the (portable) output format

           real %e
           user %U
           sys %S

       is used.

The format string

       The format is interpreted in the usual printf-like way.  Ordinary
       characters are directly copied, tab, newline and backslash are escaped
       using \t, \n and \\, a percent sign is represented by %%, and otherwise %
       indicates a conversion.  The program time will always add a trailing
       newline itself.  The conversions follow.  All of those used by tcsh(1) are
       supported.

       Time

       %E     Elapsed real time (in [hours:]minutes:seconds).

       %e     (Not in tcsh.) Elapsed real time (in seconds).

       %S     Total number of CPU-seconds that the process spent in kernel mode.

       %U     Total number of CPU-seconds that the process spent in user mode.

       %P     Percentage of the CPU that this job got, computed as (%U + %S) / %E.

       Memory

       %M     Maximum resident set size of the process during its lifetime, in
              Kbytes.

       %t     (Not in tcsh.) Average resident set size of the process, in Kbytes.

       %K     Average total (data+stack+text) memory use of the process, in
              Kbytes.

       %D     Average size of the process's unshared data area, in Kbytes.

       %p     (Not in tcsh.) Average size of the process's unshared stack space,
              in Kbytes.

       %X     Average size of the process's shared text space, in Kbytes.

       %Z     (Not in tcsh.) System's page size, in bytes.  This is a per-system
              constant, but varies between systems.

       %F     Number of major page faults that occurred while the process was
              running.  These are faults where the page has to be read in from
              disk.

       %R     Number of minor, or recoverable, page faults.  These are faults for
              pages that are not valid but which have not yet been claimed by
              other virtual pages.  Thus the data in the page is still valid but
              the system tables must be updated.

       %W     Number of times the process was swapped out of main memory.

       %c     Number of times the process was context-switched involuntarily
              (because the time slice expired).

       %w     Number of waits: times that the program was context-switched
              voluntarily, for instance while waiting for an I/O operation to
              complete.

       I/O

       %I     Number of file system inputs by the process.

       %O     Number of file system outputs by the process.

       %r     Number of socket messages received by the process.

       %s     Number of socket messages sent by the process.

       %k     Number of signals delivered to the process.

       %C     (Not in tcsh.) Name and command-line arguments of the command being
              timed.

       %x     (Not in tcsh.) Exit status of the command.

GNU Options

       -f FORMAT, --format=[22mFORMAT[0m
              Specify output format, possibly overriding the format specified in
              the environment variable TIME.

       -p, --portability
              Use the portable output format.

       -o FILE, --output=[22mFILE[0m
              Do not send the results to stderr, but overwrite the specified file.

       -a, --append
              (Used together with -o.) Do not overwrite but append.

       -v, --verbose
              Give very verbose output about all the program knows about.

GNU Standard Options

       --help Print a usage message on standard output and exit successfully.

       -V, --version
              Print version information on standard output, then exit
              successfully.

       --     Terminate option list.

BUGS top

       Not all resources are measured by all versions of UNIX, so some of the
       values might be reported as zero.  The present selection was mostly
       inspired by the data provided by 4.2 or 4.3BSD.

       GNU time version 1.7 is not yet localized.  Thus, it does not implement the
       POSIX requirements.

       The environment variable TIME was badly chosen.  It is not unusual for
       systems like autoconf(1) or make(1) to use environment variables with the
       name of a utility to override the utility to be used.  Uses like MORE or
       TIME for options to programs (instead of program pathnames) tend to lead to
       difficulties.

       It seems unfortunate that -o overwrites instead of appends.  (That is, the
       -a option should be the default.)

       Mail suggestions and bug reports for GNU time to
       bug-utils@prep.ai.mit.edu
       Please include the version of time, which you can get by running
       time --version
       and the operating system and C compiler you used.

SEE ALSO top

       tcsh(1), times(2), wait3(2)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-11-14                             TIME(1)


time(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TIME(2)                      Linux Programmer's Manual                     TIME(2)

NAME top

       time - get time in seconds

SYNOPSIS top

       #include <time.h>

       time_t time(time_t *t);

DESCRIPTION top

       time() returns the time as the number of seconds since the Epoch,
       1970-01-01 00:00:00 +0000 (UTC).

       If t is non-NULL, the return value is also stored in the memory pointed to
       by t.

RETURN VALUE top

       On success, the value of time in seconds since the Epoch is returned.  On
       error, ((time_t) -1) is returned, and errno is set appropriately.

ERRORS top

       EFAULT t points outside your accessible address space.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.  POSIX does not specify any error
       conditions.

NOTES top

       POSIX.1 defines seconds since the Epoch using a formula that approximates
       the number of seconds between a specified time and the Epoch.  This formula
       takes account of the facts that all years that are evenly divisible by 4
       are leap years, but years that are evenly divisible by 100 are not leap
       years unless they are also evenly divisible by 400, in which case they are
       leap years.  This value is not the same as the actual number of seconds
       between the time and the Epoch, because of leap seconds and because system
       clocks are not required to be synchronized to a standard reference.  The
       intention is that the interpretation of seconds since the Epoch values be
       consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale.

SEE ALSO top

       date(1), gettimeofday(2), ctime(3), ftime(3), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-09                             TIME(2)


time(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

TIME(7)                      Linux Programmer's Manual                     TIME(7)

NAME top

       time - overview of time and timers

DESCRIPTION top

Real time and process time

       Real time is defined as time measured from some fixed point, either from a
       standard point in the past (see the description of the Epoch and calendar
       time below), or from some point (e.g., the start) in the life of a process
       (elapsed time).

       Process time is defined as the amount of CPU time used by a process.  This
       is sometimes divided into user and system components.  User CPU time is the
       time spent executing code in user mode.  System CPU time is the time spent
       by the kernel executing in system mode on behalf of the process (e.g.,
       executing system calls).  The time(1) command can be used to determine the
       amount of CPU time consumed during the execution of a program.  A program
       can determine the amount of CPU time it has consumed using times(2),
       getrusage(2), or clock(3).

The Hardware Clock

       Most computers have a (battery-powered) hardware clock which the kernel
       reads at boot time in order to initialize the software clock.  For further
       details, see rtc(4) and hwclock(8).

The Software Clock, HZ, and Jiffies

       The accuracy of various system calls that set timeouts, (e.g., select(2),
       sigtimedwait(2)) and measure CPU time (e.g., getrusage(2)) is limited by
       the resolution of the software clock, a clock maintained by the kernel
       which measures time in jiffies.  The size of a jiffy is determined by the
       value of the kernel constant HZ.

       The value of HZ varies across kernel versions and hardware platforms.  On
       i386 the situation is as follows: on kernels up to and including 2.4.x, HZ
       was 100, giving a jiffy value of 0.01 seconds; starting with 2.6.0, HZ was
       raised to 1000, giving a jiffy of 0.001 seconds.  Since kernel 2.6.13, the
       HZ value is a kernel configuration parameter and can be 100, 250 (the
       default) or 1000, yielding a jiffies value of, respectively, 0.01, 0.004,
       or 0.001 seconds.  Since kernel 2.6.20, a further frequency is available:
       300, a number that divides evenly for the common video frame rates (PAL, 25
       HZ; NTSC, 30 HZ).

       The times(2) system call is a special case.  It reports times with a
       granularity defined by the kernel constant USER_HZ.  User-space
       applications can determine the value of this constant using
       sysconf(_SC_CLK_TCK).

High-Resolution Timers

       Before Linux 2.6.21, the accuracy of timer and sleep system calls (see
       below) was also limited by the size of the jiffy.

       Since Linux 2.6.21, Linux supports high-resolution timers (HRTs),
       optionally configurable via CONFIG_HIGH_RES_TIMERS.  On a system that
       supports HRTs, the accuracy of sleep and timer system calls is no longer
       constrained by the jiffy, but instead can be as accurate as the hardware
       allows (microsecond accuracy is typical of modern hardware).  You can
       determine whether high-resolution timers are supported by checking the
       resolution returned by a call to clock_getres(2) or looking at the
       "resolution" entries in /proc/timer_list.

       HRTs are not supported on all hardware architectures.  (Support is provided
       on x86, arm, and powerpc, among others.)

The Epoch

       UNIX systems represent time in seconds since the Epoch, 1970-01-01 00:00:00
       +0000 (UTC).

       A program can determine the calendar time using gettimeofday(2), which
       returns time (in seconds and microseconds) that have elapsed since the
       Epoch; time(2) provides similar information, but only with accuracy to the
       nearest second.  The system time can be changed using settimeofday(2).

Broken-down time

       Certain library functions use a structure of type tm to represent broken-
       down time, which stores time value separated out into distinct components
       (year, month, day, hour, minute, second, etc.).  This structure is
       described in ctime(3), which also describes functions that convert between
       calendar time and broken-down time.  Functions for converting between
       broken-down time and printable string representations of the time are
       described in ctime(3), strftime(3), and strptime(3).

Sleeping and Setting Timers

       Various system calls and functions allow a program to sleep (suspend
       execution) for a specified period of time; see nanosleep(2),
       clock_nanosleep(2), and sleep(3).

       Various system calls allow a process to set a timer that expires at some
       point in the future, and optionally at repeated intervals; see alarm(2),
       getitimer(2), timerfd_create(2), and timer_create(2).

Timer Slack

       Since Linux 2.6.28, it is possible to control the "timer slack" value for a
       thread.  The timer slack is the length of time by which the kernel may
       delay the wake-up of certain system calls that block with a timeout.
       Permitting this delay allows the kernel to coalesce wake-up events, thus
       possibly reducing the number of system wake-ups and saving power.  For more
       details, see the description of PR_SET_TIMERSLACK in prctl(2).

SEE ALSO          top
       date(1), time(1), adjtimex(2), alarm(2), clock_gettime(2),
       clock_nanosleep(2), getitimer(2), getrlimit(2), getrusage(2),
       gettimeofday(2), nanosleep(2), stat(2), time(2), timer_create(2),
       timerfd_create(2), times(2), utime(2), adjtime(3), clock(3),
       clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3), sleep(3),
       strftime(3), strptime(3), timeradd(3), usleep(3), rtc(4), hwclock(8)

COLOPHON          top
       This page is part of release 3.45 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                               2012-10-28                             TIME(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


timegm(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TIMEGM(3)                    Linux Programmer's Manual                   TIMEGM(3)

NAME top

       timegm, timelocal - inverses of gmtime and localtime

SYNOPSIS top

       #include <time.h>

       time_t timelocal(struct tm *tm);

       time_t timegm(struct tm *tm);

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

       timelocal(), timegm(): _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION top

       The functions timelocal() and timegm() are the inverses of localtime(3) and
       gmtime(3).

CONFORMING TO top

       These functions are nonstandard GNU extensions that are also present on the
       BSDs.  Avoid their use; see NOTES.

NOTES top

       The timelocal() function is equivalent to the POSIX standard function
       mktime(3).  There is no reason to ever use it.

       For a portable version of timegm(), set the TZ environment variable to UTC,
       call mktime(3) and restore the value of TZ.  Something like

           #include <time.h>
           #include <stdlib.h>

           time_t
           my_timegm(struct tm *tm)
           {
               time_t ret;
               char *tz;

               tz = getenv("TZ");
               setenv("TZ", "", 1);
               tzset();
               ret = mktime(tm);
               if (tz)
                   setenv("TZ", tz, 1);
               else
                   unsetenv("TZ");
               tzset();
               return ret;
           }

SEE ALSO top

       gmtime(3), localtime(3), mktime(3), tzset(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2007-07-26                           TIMEGM(3)


timeradd(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

TIMERADD(3)                  Linux Programmer's Manual                 TIMERADD(3)

NAME top

       timeradd, timersub, timercmp, timerclear, timerisset - timeval operations

SYNOPSIS top

       #include <sys/time.h>

       void timeradd(struct timeval *a, struct timeval *b,
                     struct timeval *res);

       void timersub(struct timeval *a, struct timeval *b,
                     struct timeval *res);

       void timerclear(struct timeval *tvp);

       int timerisset(struct timeval *tvp);

       int timercmp(struct timeval *a, struct timeval *b, CMP);

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

       All functions shown above: _BSD_SOURCE

DESCRIPTION top

       The macros are provided to operate on timeval structures, defined in
       <sys/time.h> as:

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

       timeradd() adds the time values in a and b, and places the sum in the
       timeval pointed to by res.  The result is normalized such that res->tv_usec
       has a value in the range 0 to 999,999.

       timersub() subtracts the time value in b from the time value in a, and
       places the result in the timeval pointed to by res.  The result is
       normalized such that res->tv_usec has a value in the range 0 to 999,999.

       timerclear() zeros out the timeval structure pointed to by tvp, so that it
       represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC).

       timerisset() returns true (nonzero) if either field of the timeval
       structure pointed to by tvp contains a nonzero value.

       timercmp() compares the timer values in a and b using the comparison
       operator CMP, and returns true (nonzero) or false (0) depending on the
       result of the comparison.  Some systems (but not Linux/glibc), have a
       broken timercmp() implementation, in which CMP of >=, <=, and == do not
       work; portable applications can instead use

           !timercmp(..., <)
           !timercmp(..., >)
           !timercmp(..., !=)

RETURN VALUE top

       timerisset() and timercmp() return true (nonzero) or false (0).

ERRORS top

       No errors are defined.

CONFORMING TO top

       Not in POSIX.1-2001.  Present on most BSD derivatives.

SEE ALSO top

       gettimeofday(2), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-02-25                         TIMERADD(3)


timerfd_create(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TIMERFD_CREATE(2)            Linux Programmer's Manual           TIMERFD_CREATE(2)

NAME top

       timerfd_create,  timerfd_settime,  timerfd_gettime - timers that notify via
       file descriptors

SYNOPSIS top

       #include <sys/timerfd.h>

       int timerfd_create(int clockid, int flags);

       int timerfd_settime(int fd, int flags,
                           const struct itimerspec *new_value,
                           struct itimerspec *old_value);

       int timerfd_gettime(int fd, struct itimerspec *curr_value);

DESCRIPTION top

       These system calls create and operate on a timer that delivers timer
       expiration notifications via a file descriptor.  They provide an
       alternative to the use of setitimer(2) or timer_create(2), with the
       advantage that the file descriptor may be monitored by select(2), poll(2),
       and epoll(7).

       The use of these three system calls is analogous to the use of
       timer_create(2), timer_settime(2), and timer_gettime(2).  (There is no
       analog of timer_getoverrun(2), since that functionality is provided by
       read(2), as described below.)

timerfd_create()

       timerfd_create() creates a new timer object, and returns a file descriptor
       that refers to that timer.  The clockid argument specifies the clock that
       is used to mark the progress of the timer, and must be either
       CLOCK_REALTIME or CLOCK_MONOTONIC.  CLOCK_REALTIME is a settable system-
       wide clock.  CLOCK_MONOTONIC is a nonsettable clock that is not affected by
       discontinuous changes in the system clock (e.g., manual changes to system
       time).  The current value of each of these clocks can be retrieved using
       clock_gettime(2).

       Starting with Linux 2.6.27, the following values may be bitwise ORed in
       flags to change the behavior of timerfd_create():

       TFD_NONBLOCK  Set the O_NONBLOCK file status flag on the new open file
                     description.  Using this flag saves extra calls to fcntl(2)
                     to achieve the same result.

       TFD_CLOEXEC   Set the close-on-exec (FD_CLOEXEC) flag on the new file
                     descriptor.  See the description of the O_CLOEXEC flag in
                     open(2) for reasons why this may be useful.

       In Linux versions up to and including 2.6.26, flags must be specified as
       zero.

timerfd_settime()

       timerfd_settime() arms (starts) or disarms (stops) the timer referred to by
       the file descriptor fd.

       The new_value argument specifies the initial expiration and interval for
       the timer.  The itimer structure used for this argument contains two
       fields, each of which is in turn a structure of type timespec:

           struct timespec {
               time_t tv_sec;                /* Seconds */
               long   tv_nsec;               /* Nanoseconds */
           };

           struct itimerspec {
               struct timespec it_interval;  /* Interval for periodic timer */
               struct timespec it_value;     /* Initial expiration */
           };

       new_value.it_value specifies the initial expiration of the timer, in
       seconds and nanoseconds.  Setting either field of new_value.it_value to a
       nonzero value arms the timer.  Setting both fields of new_value.it_value to
       zero disarms the timer.

       Setting one or both fields of new_value.it_interval to nonzero values
       specifies the period, in seconds and nanoseconds, for repeated timer
       expirations after the initial expiration.  If both fields of
       new_value.it_interval are zero, the timer expires just once, at the time
       specified by new_value.it_value.

       The flags argument is either 0, to start a relative timer
       (new_value.it_value specifies a time relative to the current value of the
       clock specified by clockid), or TFD_TIMER_ABSTIME, to start an absolute
       timer (new_value.it_value specifies an absolute time for the clock
       specified by clockid; that is, the timer will expire when the value of that
       clock reaches the value specified in new_value.it_value).

       If the old_value argument is not NULL, then the itimerspec structure that
       it points to is used to return the setting of the timer that was current at
       the time of the call; see the description of timerfd_gettime() following.

timerfd_gettime()

       timerfd_gettime() returns, in curr_value, an itimerspec structure that
       contains the current setting of the timer referred to by the file
       descriptor fd.

       The it_value field returns the amount of time until the timer will next
       expire.  If both fields of this structure are zero, then the timer is
       currently disarmed.  This field always contains a relative value,
       regardless of whether the TFD_TIMER_ABSTIME flag was specified when setting
       the timer.

       The it_interval field returns the interval of the timer.  If both fields of
       this structure are zero, then the timer is set to expire just once, at the
       time specified by curr_value.it_value.

Operating on a timer file descriptor

       The file descriptor returned by timerfd_create() supports the following
       operations:

       read(2)
              If the timer has already expired one or more times since its
              settings were last modified using timerfd_settime(), or since the
              last successful read(2), then the buffer given to read(2) returns an
              unsigned 8-byte integer (uint64_t) containing the number of
              expirations that have occurred.  (The returned value is in host byte
              order, i.e., the native byte order for integers on the host
              machine.)

              If no timer expirations have occurred at the time of the read(2),
              then the call either blocks until the next timer expiration, or
              fails with the error EAGAIN if the file descriptor has been made
              nonblocking (via the use of the fcntl(2) F_SETFL operation to set
              the O_NONBLOCK flag).

              A read(2) will fail with the error EINVAL if the size of the
              supplied buffer is less than 8 bytes.

       poll(2), select(2) (and similar)
              The file descriptor is readable (the select(2) readfds argument; the
              poll(2) POLLIN flag) if one or more timer expirations have occurred.

              The file descriptor also supports the other file-descriptor
              multiplexing APIs: pselect(2), ppoll(2), and epoll(7).

       close(2)
              When the file descriptor is no longer required it should be closed.
              When all file descriptors associated with the same timer object have
              been closed, the timer is disarmed and its resources are freed by
              the kernel.

fork(2) semantics

       After a fork(2), the child inherits a copy of the file descriptor created
       by timerfd_create().  The file descriptor refers to the same underlying
       timer object as the corresponding file descriptor in the parent, and
       read(2)s in the child will return information about expirations of the
       timer.

execve(2) semantics

       A file descriptor created by timerfd_create() is preserved across
       execve(2), and continues to generate timer expirations if the timer was
       armed.

RETURN VALUE top

       On success, timerfd_create() returns a new file descriptor.  On error, -1
       is returned and errno is set to indicate the error.

       timerfd_settime() and timerfd_gettime() return 0 on success; on error they
       return -1, and set errno to indicate the error.

ERRORS top

       timerfd_create() can fail with the following errors:

       EINVAL The clockid argument is neither CLOCK_MONOTONIC nor CLOCK_REALTIME;

       EINVAL flags is invalid; or, in Linux 2.6.26 or earlier, flags is nonzero.

       EMFILE The per-process limit of open file descriptors has been reached.

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

       ENODEV Could not mount (internal) anonymous inode device.

       ENOMEM There was insufficient kernel memory to create the timer.

       timerfd_settime() and timerfd_gettime() can fail with the following errors:

       EBADF  fd is not a valid file descriptor.

       EFAULT new_value, old_value, or curr_value is not valid a pointer.

       EINVAL fd is not a valid timerfd file descriptor.

       timerfd_settime() can also fail with the following errors:

       EINVAL new_value is not properly initialized (one of the tv_nsec falls
              outside the range zero to 999,999,999).

       EINVAL flags is invalid.

VERSIONS top

       These system calls are available on Linux since kernel 2.6.25.  Library
       support is provided by glibc since version 2.8.

CONFORMING TO top

       These system calls are Linux-specific.

EXAMPLE top

       The following program creates a timer and then monitors its progress.  The
       program accepts up to three command-line arguments.  The first argument
       specifies the number of seconds for the initial expiration of the timer.
       The second argument specifies the interval for the timer, in seconds.  The
       third argument specifies the number of times the program should allow the
       timer to expire before terminating.  The second and third command-line
       arguments are optional.

       The following shell session demonstrates the use of the program:

           $ a.out 3 1 100
           0.000: timer started
           3.000: read: 1; total=1
           4.000: read: 1; total=2
           ^Z                  # type control-Z to suspend the program
           [1]+  Stopped                 ./timerfd3_demo 3 1 100
           $ fg                # Resume execution after a few seconds
           a.out 3 1 100
           9.660: read: 5; total=7
           10.000: read: 1; total=8
           11.000: read: 1; total=9
           ^C                  # type control-C to suspend the program

Program source

       #include <sys/timerfd.h>
       #include <time.h>
       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <stdint.h>        /* Definition of uint64_t */

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

       static void
       print_elapsed_time(void)
       {
           static struct timespec start;
           struct timespec curr;
           static int first_call = 1;
           int secs, nsecs;

           if (first_call) {
               first_call = 0;
               if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
                   handle_error("clock_gettime");
           }

           if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
               handle_error("clock_gettime");

           secs = curr.tv_sec - start.tv_sec;
           nsecs = curr.tv_nsec - start.tv_nsec;
           if (nsecs < 0) {
               secs--;
               nsecs += 1000000000;
           }
           printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
       }

       int
       main(int argc, char *argv[])
       {
           struct itimerspec new_value;
           int max_exp, fd;
           struct timespec now;
           uint64_t exp, tot_exp;
           ssize_t s;

           if ((argc != 2) && (argc != 4)) {
               fprintf(stderr, "%s init-secs [interval-secs max-exp]\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           if (clock_gettime(CLOCK_REALTIME, &now) == -1)
               handle_error("clock_gettime");

           /* Create a CLOCK_REALTIME absolute timer with initial
              expiration and interval as specified in command line */

           new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
           new_value.it_value.tv_nsec = now.tv_nsec;
           if (argc == 2) {
               new_value.it_interval.tv_sec = 0;
               max_exp = 1;
           } else {
               new_value.it_interval.tv_sec = atoi(argv[2]);
               max_exp = atoi(argv[3]);
           }
           new_value.it_interval.tv_nsec = 0;

           fd = timerfd_create(CLOCK_REALTIME, 0);
           if (fd == -1)
               handle_error("timerfd_create");

           if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
               handle_error("timerfd_settime");

           print_elapsed_time();
           printf("timer started\n");

           for (tot_exp = 0; tot_exp < max_exp;) {
               s = read(fd, &exp, sizeof(uint64_t));
               if (s != sizeof(uint64_t))
                   handle_error("read");

               tot_exp += exp;
               print_elapsed_time();
               printf("read: %llu; total=%llu\n",
                       (unsigned long long) exp,
                       (unsigned long long) tot_exp);
           }

           exit(EXIT_SUCCESS);
       }

BUGS top

       Currently, timerfd_create() supports fewer types of clock IDs than
       timer_create(2).

SEE ALSO top

       eventfd(2), poll(2), read(2), select(2), setitimer(2), signalfd(2),
       timer_create(2), timer_gettime(2), timer_settime(2), epoll(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-14                   TIMERFD_CREATE(2)


timer_create(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TIMER_CREATE(2)              Linux Programmer's Manual             TIMER_CREATE(2)

NAME top

       timer_create - create a POSIX per-process timer

SYNOPSIS top

       #include <signal.h>
       #include <time.h>

       int timer_create(clockid_t clockid, struct sigevent *sevp,
                        timer_t *timerid);

       Link with -lrt.

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

       timer_create(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       timer_create() creates a new per-process interval timer.  The ID of the new
       timer is returned in the buffer pointed to by timerid, which must be a non-
       NULL pointer.  This ID is unique within the process, until the timer is
       deleted.  The new timer is initially disarmed.

       The clockid argument specifies the clock that the new timer uses to measure
       time.  It can be specified as one of the following values:

       CLOCK_REALTIME
              A settable system-wide real-time clock.

       CLOCK_MONOTONIC
              A nonsettable monotonically increasing clock that measures time from
              some unspecified point in the past that does not change after system
              startup.

       CLOCK_PROCESS_CPUTIME_ID (since Linux 2.6.12)
              A clock that measures (user and system) CPU time consumed by (all of
              the threads in) the calling process.

       CLOCK_THREAD_CPUTIME_ID (since Linux 2.6.12)
              A clock that measures (user and system) CPU time consumed by the
              calling thread.

       As well as the above values, clockid can be specified as the clockid
       returned by a call to clock_getcpuclockid(3) or pthread_getcpuclockid(3).

       The sevp argument points to a sigevent structure that specifies how the
       caller should be notified when the timer expires.  For the definition and
       general details of this structure, see sigevent(7).

       The sevp.sigev_notify field can have the following values:

       SIGEV_NONE
              Don't asynchronously notify when the timer expires.  Progress of the
              timer can be monitored using timer_gettime(2).

       SIGEV_SIGNAL
              Upon timer expiration, generate the signal sigev_signo for the
              process.  See sigevent(7) for general details.  The si_code field of
              the siginfo_t structure will be set to SI_TIMER.  At any point in
              time, at most one signal is queued to the process for a given timer;
              see timer_getoverrun(2) for more details.

       SIGEV_THREAD
              Upon timer expiration, invoke sigev_notify_function as if it were
              the start function of a new thread.  See sigevent(7) for details.

       SIGEV_THREAD_ID (Linux-specific)
              As for SIGEV_SIGNAL, but the signal is targeted at the thread whose
              ID is given in sigev_notify_thread_id, which must be a thread in the
              same process as the caller.  The sigev_notify_thread_id field
              specifies a kernel thread ID, that is, the value returned by
              clone(2) or gettid(2).  This flag is only intended for use by
              threading libraries.

       Specifying sevp as NULL is equivalent to specifying a pointer to a sigevent
       structure in which sigev_notify is SIGEV_SIGNAL, sigev_signo is SIGALRM,
       and sigev_value.sival_int is the timer ID.

RETURN VALUE top

       On success, timer_create() returns 0, and the ID of the new timer is placed
       in *timerid.  On failure, -1 is returned, and errno is set to indicate the
       error.

ERRORS top

       EAGAIN Temporary error during kernel allocation of timer structures.

       EINVAL Clock ID, sigev_notify, sigev_signo, or sigev_notify_thread_id is
              invalid.

       ENOMEM Could not allocate memory.

VERSIONS top

       This system call is available since Linux 2.6.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       A program may create multiple interval timers using timer_create().

       Timers are not inherited by the child of a fork(2), and are disarmed and
       deleted during an execve(2).

       The kernel preallocates a "queued real-time signal" for each timer created
       using timer_create().  Consequently, the number of timers is limited by the
       RLIMIT_SIGPENDING resource limit (see setrlimit(2)).

       The timers created by timer_create() are commonly known as "POSIX
       (interval) timers".  The POSIX timers API consists of the following
       interfaces:

       *  timer_create(): Create a timer.

       *  timer_settime(2): Arm (start) or disarm (stop) a timer.

       *  timer_gettime(2): Fetch the time remaining until the next expiration of
          a timer, along with the interval setting of the timer.

       *  timer_getoverrun(2): Return the overrun count for the last timer
          expiration.

       *  timer_delete(2): Disarm and delete a timer.

       Part of the implementation of the POSIX timers API is provided by glibc.
       In particular:

       *  The functionality for SIGEV_THREAD is implemented within glibc, rather
          than the kernel.

       *  The timer IDs presented at user level are maintained by glibc, which
          maps these IDs to the timer IDs employed by the kernel.

       The POSIX timers system calls first appeared in Linux 2.6.  Prior to this,
       glibc provided an incomplete user-space implementation (CLOCK_REALTIME
       timers only) using POSIX threads, and current glibc falls back to this
       implementation on systems running pre-2.6 Linux kernels.

EXAMPLE top

       The program below takes two arguments: a sleep period in seconds, and a
       timer frequency in nanoseconds.  The program establishes a handler for the
       signal it uses for the timer, blocks that signal, creates and arms a timer
       that expires with the given frequency, sleeps for the specified number of
       seconds, and then unblocks the timer signal.  Assuming that the timer
       expired at least once while the program slept, the signal handler will be
       invoked, and the handler displays some information about the timer
       notification.  The program terminates after one invocation of the signal
       handler.

       In the following example run, the program sleeps for 1 second, after
       creating a timer that has a frequency of 100 nanoseconds.  By the time the
       signal is unblocked and delivered, there have been around ten million
       overruns.

           $ ./a.out 1 100
           Establishing handler for signal 34
           Blocking signal 34
           timer ID is 0x804c008
           Sleeping for 1 seconds
           Unblocking signal 34
           Caught signal 34
               sival_ptr = 0xbfb174f4;     *sival_ptr = 0x804c008
               overrun count = 10004886

Program Source

       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>
       #include <signal.h>
       #include <time.h>

       #define CLOCKID CLOCK_REALTIME
       #define SIG SIGRTMIN

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

       static void
       print_siginfo(siginfo_t *si)
       {
           timer_t *tidp;
           int or;

           tidp = si->si_value.sival_ptr;

           printf("    sival_ptr = %p; ", si->si_value.sival_ptr);
           printf("    *sival_ptr = 0x%lx\n", (long) *tidp);

           or = timer_getoverrun(*tidp);
           if (or == -1)
               errExit("timer_getoverrun");
           else
               printf("    overrun count = %d\n", or);
       }

       static void
       handler(int sig, siginfo_t *si, void *uc)
       {
           /* Note: calling printf() from a signal handler is not
              strictly correct, since printf() is not async-signal-safe;
              see signal(7) */

           printf("Caught signal %d\n", sig);
           print_siginfo(si);
           signal(sig, SIG_IGN);
       }

       int
       main(int argc, char *argv[])
       {
           timer_t timerid;
           struct sigevent sev;
           struct itimerspec its;
           long long freq_nanosecs;
           sigset_t mask;
           struct sigaction sa;

           if (argc != 3) {
               fprintf(stderr, "Usage: %s <sleep-secs> <freq-nanosecs>\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           /* Establish handler for timer signal */

           printf("Establishing handler for signal %d\n", SIG);
           sa.sa_flags = SA_SIGINFO;
           sa.sa_sigaction = handler;
           sigemptyset(&sa.sa_mask);
           if (sigaction(SIG, &sa, NULL) == -1)
               errExit("sigaction");

           /* Block timer signal temporarily */

           printf("Blocking signal %d\n", SIG);
           sigemptyset(&mask);
           sigaddset(&mask, SIG);
           if (sigprocmask(SIG_SETMASK, &mask, NULL) == -1)
               errExit("sigprocmask");

           /* Create the timer */

           sev.sigev_notify = SIGEV_SIGNAL;
           sev.sigev_signo = SIG;
           sev.sigev_value.sival_ptr = &timerid;
           if (timer_create(CLOCKID, &sev, &timerid) == -1)
               errExit("timer_create");

           printf("timer ID is 0x%lx\n", (long) timerid);

           /* Start the timer */

           freq_nanosecs = atoll(argv[2]);
           its.it_value.tv_sec = freq_nanosecs / 1000000000;
           its.it_value.tv_nsec = freq_nanosecs % 1000000000;
           its.it_interval.tv_sec = its.it_value.tv_sec;
           its.it_interval.tv_nsec = its.it_value.tv_nsec;

           if (timer_settime(timerid, 0, &its, NULL) == -1)
                errExit("timer_settime");

           /* Sleep for a while; meanwhile, the timer may expire
              multiple times */

           printf("Sleeping for %d seconds\n", atoi(argv[1]));
           sleep(atoi(argv[1]));

           /* Unlock the timer signal, so that timer notification
              can be delivered */

           printf("Unblocking signal %d\n", SIG);
           if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == -1)
               errExit("sigprocmask");

           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       clock_gettime(2), setitimer(2), timer_delete(2), timer_getoverrun(2),
       timer_settime(2), timerfd_create(2), clock_getcpuclockid(3),
       pthread_getcpuclockid(3), pthreads(7), sigevent(7), signal(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2010-09-27                     TIMER_CREATE(2)


timer_delete(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

TIMER_DELETE(2)              Linux Programmer's Manual             TIMER_DELETE(2)

NAME top

       timer_delete - delete a POSIX per-process timer

SYNOPSIS top

       #include <time.h>

       int timer_delete(timer_t timerid);

       Link with -lrt.

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

       timer_delete(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       timer_delete() deletes the timer whose ID is given in timerid.  If the
       timer was armed at the time of this call, it is disarmed before being
       deleted.  The treatment of any pending signal generated by the deleted
       timer is unspecified.

RETURN VALUE top

       On success, timer_delete() returns 0.  On failure, -1 is returned, and
       errno is set to indicate the error.

ERRORS top

       EINVAL timerid is not a valid timer ID.

VERSIONS top

       This system call is available since Linux 2.6.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       clock_gettime(2), timer_create(2), timer_getoverrun(2), timer_settime(2),
       time(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-20                     TIMER_DELETE(2)


timer_getoverrun(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TIMER_GETOVERRUN(2)          Linux Programmer's Manual         TIMER_GETOVERRUN(2)

NAME top

       timer_getoverrun - get overrun count for a POSIX per-process timer

SYNOPSIS top

       #include <time.h>

       int timer_getoverrun(timer_t timerid);

       Link with -lrt.

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

       timer_getoverrun(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       timer_getoverrun() returns the "overrun count" for the timer referred to by
       timerid.  An application can use the overrun count to accurately calculate
       the number of timer expirations that would have occurred over a given time
       interval.  Timer overruns can occur both when receiving expiration
       notifications via signals (SIGEV_SIGNAL), and via threads (SIGEV_THREAD).

       When expiration notifications are delivered via a signal, overruns can
       occur as follows.  Regardless of whether or not a real-time signal is used
       for timer notifications, the system queues at most one signal per timer.
       (This is the behavior specified by POSIX.1-2001.  The alternative, queuing
       one signal for each timer expiration, could easily result in overflowing
       the allowed limits for queued signals on the system.)  Because of system
       scheduling delays, or because the signal may be temporarily blocked, there
       can be a delay between the time when the notification signal is generated
       and the time when it is delivered (e.g., caught by a signal handler) or
       accepted (e.g., using sigwaitinfo(2)).  In this interval, further timer
       expirations may occur.  The timer overrun count is the number of additional
       timer expirations that occurred between the time when the signal was
       generated and when it was delivered or accepted.

       Timer overruns can also occur when expiration notifications are delivered
       via invocation of a thread, since there may be an arbitrary delay between
       an expiration of the timer and the invocation of the notification thread,
       and in that delay interval, additional timer expirations may occur

RETURN VALUE top

       On success, timer_getoverrun() returns the overrun count of the specified
       timer; this count may be 0 if no overruns have occurred.  On failure, -1 is
       returned, and errno is set to indicate the error.

ERRORS top

       EINVAL timerid is not a valid timer ID.

VERSIONS top

       This system call is available since Linux 2.6.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       When timer notifications are delivered via signals (SIGEV_SIGNAL), on Linux
       it is also possible to obtain the overrun count via the si_overrun field of
       the siginfo_t structure (see sigaction(2)).  This allows an application to
       avoid the overhead of making a system call to obtain the overrun count, but
       is a nonportable extension to POSIX.1-2001.

       POSIX.1-2001 only discusses timer overruns in the context of timer
       notifications using signals.

BUGS top

       POSIX.1-2001 specifies that if the timer overrun count is equal to or
       greater than an implementation-defined maximum, DELAYTIMER_MAX, then
       timer_getoverrun() should return DELAYTIMER_MAX.  However, Linux does not
       implement this feature: instead, if the timer overrun value exceeds the
       maximum representable integer, the counter cycles, starting once more from
       low values.

EXAMPLE top

       See timer_create(2).

SEE ALSO top

       clock_gettime(2), sigaction(2), signalfd(2), sigwaitinfo(2),
       timer_create(2), timer_delete(2), timer_settime(2), signal(7), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2009-02-20                 TIMER_GETOVERRUN(2)


timer_settime(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TIMER_SETTIME(2)             Linux Programmer's Manual            TIMER_SETTIME(2)

NAME top

       timer_settime,  timer_gettime  -  arm/disarm  and fetch state of POSIX per-
       process timer

SYNOPSIS top

       #include <time.h>

       int timer_settime(timer_t timerid, int flags,
                         const struct itimerspec *new_value,
                         struct itimerspec * old_value);
       int timer_gettime(timer_t timerid, struct itimerspec *curr_value);

       Link with -lrt.

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

       timer_settime(), timer_gettime(): _POSIX_C_SOURCE >= 199309L

DESCRIPTION top

       timer_settime() arms or disarms the timer identified by timerid.  The
       new_value argument is pointer to an itimerspec structure that specifies the
       new initial value and the new interval for the timer.  The itimerspec
       structure is defined as follows:

           struct timespec {
               time_t tv_sec;                /* Seconds */
               long   tv_nsec;               /* Nanoseconds */
           };

           struct itimerspec {
               struct timespec it_interval;  /* Timer interval */
               struct timespec it_value;     /* Initial expiration */
           };

       Each of the substructures of the itimerspec structure is a timespec
       structure that allows a time value to be specified in seconds and
       nanoseconds.  These time values are measured according to the clock that
       was specified when the timer was created by timer_create(2)

       If new_value->it_value specifies a nonzero value (i.e., either subfield is
       nonzero), then timer_settime() arms (starts) the timer, setting it to
       initially expire at the given time.  (If the timer was already armed, then
       the previous settings are overwritten.)  If new_value->it_value specifies a
       zero value (i.e., both subfields are zero), then the timer is disarmed.

       The new_value->it_interval field specifies the period of the timer, in
       seconds and nanoseconds.  If this field is nonzero, then each time that an
       armed timer expires, the timer is reloaded from the value specified in
       new_value->it_interval.  If new_value->it_interval specifies a zero value
       then the timer expires just once, at the time specified by it_value.

       By default, the initial expiration time specified in new_value->it_value is
       interpreted relative to the current time on the timer's clock at the time
       of the call.  This can be modified by specifying TIMER_ABSTIME in flags, in
       which case new_value->it_value is interpreted as an absolute value as
       measured on the timer's clock; that is, the timer will expire when the
       clock value reaches the value specified by new_value->it_value.  If the
       specified absolute time has already passed, then the timer expires
       immediately, and the overrun count (see timer_getoverrun(2)) will be set
       correctly.

       If the value of the CLOCK_REALTIME clock is adjusted while an absolute
       timer based on that clock is armed, then the expiration of the timer will
       be appropriately adjusted.  Adjustments to the CLOCK_REALTIME clock have no
       effect on relative timers based on that clock.

       If old_value is not NULL, then it points to a buffer that is used to return
       the previous interval of the timer (in old_value->it_interval) and the
       amount of time until the timer would previously have next expired (in
       old_value->it_value).

       timer_gettime() returns the time until next expiration, and the interval,
       for the timer specified by timerid, in the buffer pointed to by curr_value.
       The time remaining until the next timer expiration is returned in
       curr_value->it_value; this is always a relative value, regardless of
       whether the TIMER_ABSTIME flag was used when arming the timer.  If the
       value returned in curr_value->it_value is zero, then the timer is currently
       disarmed.  The timer interval is returned in curr_value->it_interval.  If
       the value returned in curr_value->it_interval is zero, then this is a "one-
       shot" timer.

RETURN VALUE top

       On success, timer_settime() and timer_gettime() return 0.  On error, -1 is
       returned, and errno is set to indicate the error.

ERRORS top

       These functions may fail with the following errors:

       EFAULT new_value, old_value, or curr_value is not a valid pointer.

       EINVAL timerid is invalid.

       timer_settime() may fail with the following errors:

       EINVAL new_value.it_value is negative; or new_value.it_value.tv_nsec is
              negative or greater than 999,999,999.

VERSIONS top

       These system calls are available since Linux 2.6.

CONFORMING TO top

       POSIX.1-2001.

EXAMPLE top

       See timer_create(2).

SEE ALSO top

       timer_create(2), timer_getoverrun(2), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-15                    TIMER_SETTIME(2)


times(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TIMES(2)                     Linux Programmer's Manual                    TIMES(2)

NAME top

       times - get process times

SYNOPSIS top

       #include <sys/times.h>

       clock_t times(struct tms *buf);

DESCRIPTION top

       times() stores the current process times in the struct tms that buf points
       to.  The struct tms is as defined in <sys/times.h>:

           struct tms {
               clock_t tms_utime;  /* user time */
               clock_t tms_stime;  /* system time */
               clock_t tms_cutime; /* user time of children */
               clock_t tms_cstime; /* system time of children */
           };

       The tms_utime field contains the CPU time spent executing instructions of
       the calling process.  The tms_stime field contains the CPU time spent in
       the system while executing tasks on behalf of the calling process.  The
       tms_cutime field contains the sum of the tms_utime and tms_cutime values
       for all waited-for terminated children.  The tms_cstime field contains the
       sum of the tms_stime and tms_cstime values for all waited-for terminated
       children.

       Times for terminated children (and their descendants) are added in at the
       moment wait(2) or waitpid(2) returns their process ID.  In particular,
       times of grandchildren that the children did not wait for are never seen.

       All times reported are in clock ticks.

RETURN VALUE top

       times() returns the number of clock ticks that have elapsed since an
       arbitrary point in the past.  The return value may overflow the possible
       range of type clock_t.  On error, (clock_t) -1 is returned, and errno is
       set appropriately.

ERRORS top

       EFAULT tms points outside the process's address space.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       The number of clock ticks per second can be obtained using:

           sysconf(_SC_CLK_TCK);

       In POSIX.1-1996 the symbol CLK_TCK (defined in <time.h>) is mentioned as
       obsolescent.  It is obsolete now.

       In Linux kernel versions before 2.6.9, if the disposition of SIGCHLD is set
       to SIG_IGN then the times of terminated children are automatically included
       in the tms_cstime and tms_cutime fields, although POSIX.1-2001 says that
       this should only happen if the calling process wait(2)s on its children.
       This nonconformance is rectified in Linux 2.6.9 and later.

       On Linux, the buf argument can be specified as NULL, with the result that
       times() just returns a function result.  However, POSIX does not specify
       this behavior, and most other UNIX implementations require a non-NULL value
       for buf.

       Note that clock(3) also returns a value of type clock_t, but this value is
       measured in units of CLOCKS_PER_SEC, not the clock ticks used by times().

       On Linux, the "arbitrary point in the past" from which the return value of
       times() is measured has varied across kernel versions.  On Linux 2.4 and
       earlier this point is the moment the system was booted.  Since Linux 2.6,
       this point is (2^32/HZ) - 300 (i.e., about 429 million) seconds before
       system boot time.  This variability across kernel versions (and across UNIX
       implementations), combined with the fact that the returned value may
       overflow the range of clock_t, means that a portable application would be
       wise to avoid using this value.  To measure changes in elapsed time, use
       clock_gettime(2) instead.

Historical

       SVr1-3 returns long and the struct members are of type time_t although they
       store clock ticks, not seconds since the Epoch.  V7 used long for the
       struct members, because it had no type time_t yet.

BUGS top

       A limitation of the Linux system call conventions on some architectures
       (notably i386) means that on Linux 2.6 there is a small time window (41
       seconds) soon after boot when times() can return -1, falsely indicating
       that an error occurred.  The same problem can occur when the return value
       wraps passed the maximum value that can be stored in clock_t.

SEE ALSO top

       time(1), getrusage(2), wait(2), clock(3), sysconf(3), time(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-10-22                            TIMES(2)


tmpfile(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TMPFILE(3)                   Linux Programmer's Manual                  TMPFILE(3)

NAME top

       tmpfile - create a temporary file

SYNOPSIS top

       #include <stdio.h>

       FILE *tmpfile(void);

DESCRIPTION top

       The tmpfile() function opens a unique temporary file in binary read/write
       (w+b) mode.  The file will be automatically deleted when it is closed or
       the program terminates.

RETURN VALUE top

       The tmpfile() function returns a stream descriptor, or NULL if a unique
       filename cannot be generated or the unique file cannot be opened.  In the
       latter case, errno is set to indicate the error.

ERRORS top

       EACCES Search permission denied for directory in file's path prefix.

       EEXIST Unable to generate a unique filename.

       EINTR  The call was interrupted by a signal.

       EMFILE Too many file descriptors in use by the process.

       ENFILE Too many files open in the system.

       ENOSPC There was no room in the directory to add the new filename.

       EROFS  Read-only file system.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, SUSv2, POSIX.1-2001.

NOTES top

       POSIX.1-2001 specifies: an error message may be written to stdout if the
       stream cannot be opened.

       The standard does not specify the directory that tmpfile() will use.  Glibc
       will try the path prefix P_tmpdir defined in <stdio.h>, and if that fails
       the directory /tmp.

SEE ALSO top

       exit(3), mkstemp(3), mktemp(3), tempnam(3), tmpnam(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-07-14                          TMPFILE(3)


tmpnam(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TMPNAM(3)                    Linux Programmer's Manual                   TMPNAM(3)

NAME top

       tmpnam, tmpnam_r - create a name for a temporary file

SYNOPSIS top

       #include <stdio.h>

       char *tmpnam(char *s);

DESCRIPTION top

       The tmpnam() function returns a pointer to a string that is a valid
       filename, and such that a file with this name did not exist at some point
       in time, so that naive programmers may think it a suitable name for a
       temporary file.  If the argument s is NULL this name is generated in an
       internal static buffer and may be overwritten by the next call to tmpnam().
       If s is not NULL, the name is copied to the character array (of length at
       least L_tmpnam) pointed to by s and the value s is returned in case of
       success.

       The pathname that is created, has a directory prefix P_tmpdir.  (Both
       L_tmpnam and P_tmpdir are defined in <stdio.h>, just like the TMP_MAX
       mentioned below.)

RETURN VALUE top

       The tmpnam() function returns a pointer to a unique temporary filename, or
       NULL if a unique name cannot be generated.

ERRORS top

       No errors are defined.

CONFORMING TO top

       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.  POSIX.1-2008 marks tmpnam() as
       obsolete.

NOTES top

       The tmpnam() function generates a different string each time it is called,
       up to TMP_MAX times.  If it is called more than TMP_MAX times, the behavior
       is implementation defined.

       Although tmpnam() generates names that are difficult to guess, it is
       nevertheless possible that between the time that tmpnam() returns a
       pathname, and the time that the program opens it, another program might
       create that pathname using open(2), or create it as a symbolic link.  This
       can lead to security holes.  To avoid such possibilities, use the open(2)
       O_EXCL flag to open the pathname.  Or better yet, use mkstemp(3) or
       tmpfile(3).

       Portable applications that use threads cannot call tmpnam() with a NULL
       argument if either _POSIX_THREADS or _POSIX_THREAD_SAFE_FUNCTIONS is
       defined.

       A POSIX draft proposed to use a function tmpnam_r() defined by

           char *
           tmpnam_r(char *s)
           {
               return s ? tmpnam(s) : NULL;
           }

       apparently as a warning not to use NULL.  A few systems implement it.  To
       get a glibc prototype for this function from <stdio.h>, define _SVID_SOURCE
       or _BSD_SOURCE (before including any header file).

BUGS top

       Never use this function.  Use mkstemp(3) or tmpfile(3) instead.

SEE ALSO top

       mkstemp(3), mktemp(3), tempnam(3), tmpfile(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-10                           TMPNAM(3)


toascii(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TOASCII(3)                   Linux Programmer's Manual                  TOASCII(3)

NAME top

       toascii - convert character to ASCII

SYNOPSIS top

       #include <ctype.h>

       int toascii(int c);

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

       toascii(): _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE

DESCRIPTION top

       toascii() converts c to a 7-bit unsigned char value that fits into the
       ASCII character set, by clearing the high-order bits.

RETURN VALUE top

       The value returned is that of the converted character.

CONFORMING TO top

       SVr4, BSD, POSIX.1-2001.  POSIX.1-2008 marks toascii() as obsolete, noting
       that it cannot be use portably in a localized application.

BUGS top

       Many people will be unhappy if you use this function.  This function will
       convert accented letters into random characters.

SEE ALSO top

       isascii(3), tolower(3), toupper(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2009-03-15                          TOASCII(3)


toupper(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

TOUPPER(3)                   Linux Programmer's Manual                  TOUPPER(3)

NAME top

       toupper, tolower - convert letter to upper or lower case

SYNOPSIS top

       #include <ctype.h>

       int toupper(int c);
       int tolower(int c);

DESCRIPTION top

       toupper() converts the letter c to upper case, if possible.

       tolower() converts the letter c to lower case, if possible.

       If c is not an unsigned char value, or EOF, the behavior of these functions
       is undefined.

RETURN VALUE top

       The value returned is that of the converted letter, or c if the conversion
       was not possible.

CONFORMING TO top

       C89, C99, 4.3BSD.

BUGS top

       The details of what constitutes an uppercase or lowercase letter depend on
       the current locale.  For example, the default "C" locale does not know
       about umlauts, so no conversion is done for them.

       In some non-English locales, there are lowercase letters with no
       corresponding uppercase equivalent; the German sharp s is one example.

SEE ALSO top

       isalpha(3), setlocale(3), towlower(3), towupper(3), locale(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1993-04-04                          TOUPPER(3)


towctrans(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TOWCTRANS(3)                 Linux Programmer's Manual                TOWCTRANS(3)

NAME top

       towctrans - wide-character transliteration

SYNOPSIS top

       #include <wctype.h>

       wint_t towctrans(wint_t wc, wctrans_t desc);

DESCRIPTION top

       If wc is a wide character, the towctrans() function translates it according
       to the transliteration descriptor desc.  If wc is WEOF, WEOF is returned.

       desc must be a transliteration descriptor returned by the wctrans(3)
       function.

RETURN VALUE top

       The towctrans() function returns the translated wide character, or WEOF if
       wc is WEOF.

CONFORMING TO top

       C99.

NOTES top

       The behavior of towctrans() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       towlower(3), towupper(3), wctrans(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                        TOWCTRANS(3)


towlower(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TOWLOWER(3)                  Linux Programmer's Manual                 TOWLOWER(3)

NAME top

       towlower - convert a wide character to lowercase

SYNOPSIS top

       #include <wctype.h>

       wint_t towlower(wint_t wc);

DESCRIPTION top

       The towlower() function is the wide-character equivalent of the tolower(3)
       function.  If wc is a wide character, it is converted to lowercase.
       Characters which do not have case are returned unchanged.  If wc is WEOF,
       WEOF is returned.

RETURN VALUE top

       The towlower() function returns the lowercase equivalent of wc, or WEOF if
       wc is WEOF.

CONFORMING TO top

       C99.

NOTES top

       The behavior of towlower() depends on the LC_CTYPE category of the current
       locale.

       This function is not very appropriate for dealing with Unicode characters,
       because Unicode knows about three cases: upper, lower and title case.

SEE ALSO top

       iswlower(3), towctrans(3), towupper(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         TOWLOWER(3)


towupper(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TOWUPPER(3)                  Linux Programmer's Manual                 TOWUPPER(3)

NAME top

       towupper - convert a wide character to uppercase

SYNOPSIS top

       #include <wctype.h>

       wint_t towupper(wint_t wc);

DESCRIPTION top

       The towupper() function is the wide-character equivalent of the toupper(3)
       function.  If wc is a wide character, it is converted to uppercase.
       Characters which do not have case are returned unchanged.  If wc is WEOF,
       WEOF is returned.

RETURN VALUE top

       The towupper() function returns the uppercase equivalent of wc, or WEOF if
       wc is WEOF.

CONFORMING TO top

       C99.

NOTES top

       The behavior of towupper() depends on the LC_CTYPE category of the current
       locale.

       This function is not very appropriate for dealing with Unicode characters,
       because Unicode knows about three cases: upper, lower and title case.

SEE ALSO top

       iswupper(3), towctrans(3), towlower(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         TOWUPPER(3)


trunc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TRUNC(3)                     Linux Programmer's Manual                    TRUNC(3)

NAME top

       trunc, truncf, truncl - round to integer, toward zero

SYNOPSIS top

       #include <math.h>

       double trunc(double x);
       float truncf(float x);
       long double truncl(long double x);

       Link with -lm.

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

       trunc(), truncf(), truncl():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
           or cc -std=c99

DESCRIPTION top

       These functions round x to the nearest integer not larger in absolute
       value.

RETURN VALUE top

       These functions return the rounded integer value.

       If x is integral, infinite, or NaN, x itself is returned.

ERRORS top

       No errors occur.

VERSIONS top

       These functions first appeared in glibc in version 2.1.

CONFORMING TO top

       C99, POSIX.1-2001.

NOTES top

       The integral value returned by these functions may be too large to store in
       an integer type (int, long, etc.).  To avoid an overflow, which will
       produce undefined results, an application should perform a range check on
       the returned value before assigning it to an integer type.

SEE ALSO top

       ceil(3), floor(3), lrint(3), nearbyint(3), rint(3), round(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                            TRUNC(3)


tty(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

TTY(4)                       Linux Programmer's Manual                      TTY(4)

NAME top

       tty - controlling terminal

DESCRIPTION top

       The file /dev/tty is a character file with major number 5 and minor number
       0, usually of mode 0666 and owner.group root.tty.  It is a synonym for the
       controlling terminal of a process, if any.

       In addition to the ioctl(2) requests supported by the device that tty
       refers to, the ioctl(2) request TIOCNOTTY is supported.

TIOCNOTTY

       Detach the calling process from its controlling terminal.

       If the process is the session leader, then SIGHUP and SIGCONT signals are
       sent to the foreground process group and all processes in the current
       session lose their controlling tty.

       This ioctl(2) call only works on file descriptors connected to /dev/tty.
       It is used by daemon processes when they are invoked by a user at a
       terminal.  The process attempts to open /dev/tty.  If the open succeeds, it
       detaches itself from the terminal by using TIOCNOTTY, while if the open
       fails, it is obviously not attached to a terminal and does not need to
       detach itself.

FILES top

       /dev/tty

SEE ALSO top

       chown(1), mknod(1), ioctl(2), termios(3), console(4), tty_ioctl(4),
       ttyS(4), agetty(8), mingetty(8)

COLOPHON top

       This page is part of release 3.45 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                               2003-04-07                              TTY(4)


ttyname(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

TTYNAME(3)                   Linux Programmer's Manual                  TTYNAME(3)

NAME top

       ttyname, ttyname_r - return name of a terminal

SYNOPSIS top

       #include <unistd.h>

       char *ttyname(int fd);

       int ttyname_r(int fd, char *buf, size_t buflen);

DESCRIPTION top

       The function ttyname() returns a pointer to the null-terminated pathname of
       the terminal device that is open on the file descriptor fd, or NULL on
       error (for example, if fd is not connected to a terminal).  The return
       value may point to static data, possibly overwritten by the next call.  The
       function ttyname_r() stores this pathname in the buffer buf of length
       buflen.

RETURN VALUE top

       The function ttyname() returns a pointer to a pathname on success.  On
       error, NULL is returned, and errno is set appropriately.  The function
       ttyname_r() returns 0 on success, and an error number upon error.

ERRORS top

       EBADF  Bad file descriptor.

       ENOTTY File descriptor does not refer to a terminal device.

       ERANGE (ttyname_r()) buflen was too small to allow storing the pathname.

CONFORMING TO top

       4.2BSD, POSIX.1-2001.

SEE ALSO top

       fstat(2), ctermid(3), isatty(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-21                          TTYNAME(3)


ttyS(4) - Linux manual page

NAME | DESCRIPTION | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

TTYS(4)                      Linux Programmer's Manual                     TTYS(4)

NAME top

       ttyS - serial terminal lines

DESCRIPTION top

       ttyS[0-3] are character devices for the serial terminal lines.

       They are typically created by:

              mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x3f8
              mknod -m 660 /dev/ttyS1 c 4 65 # base address 0x2f8
              mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x3e8
              mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x2e8
              chown root:tty /dev/ttyS[0-3]

FILES top

       /dev/ttyS[0-3]

SEE ALSO top

       chown(1), mknod(1), tty(4), agetty(8), mingetty(8), setserial(8)

COLOPHON top

       This page is part of release 3.45 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                               1992-12-19                             TTYS(4)


ttyslot(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

TTYSLOT(3)                   Linux Programmer's Manual                  TTYSLOT(3)

NAME top

       ttyslot - find the slot of the current user's terminal in some file

SYNOPSIS top

       #include <unistd.h>    /* on BSD-like systems, and Linux */
       #include <stdlib.h>    /* on System V-like systems */

       int ttyslot(void);

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

       ttyslot():
           _BSD_SOURCE ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_ < 500 && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The legacy function ttyslot() returns the index of the current user's entry
       in some file.

       Now "What file?" you ask.  Well, let's first look at some history.

Ancient History

       There used to be a file /etc/ttys in UNIX V6, that was read by the init(8)
       program to find out what to do with each terminal line.  Each line
       consisted of three characters.  The first character was either '0' or '1',
       where '0' meant "ignore".  The second character denoted the terminal: '8'
       stood for "/dev/tty8".  The third character was an argument to getty(8)
       indicating the sequence of line speeds to try ('-' was: start trying 110
       baud).  Thus a typical line was "18-".  A hang on some line was solved by
       changing the '1' to a '0', signaling init, changing back again, and
       signaling init again.

       In UNIX V7 the format was changed: here the second character was the
       argument to getty(8) indicating the sequence of line speeds to try ('0'
       was: cycle through 300-1200-150-110 baud; '4' was for the on-line console
       DECwriter) while the rest of the line contained the name of the tty.  Thus
       a typical line was "14console".

       Later systems have more elaborate syntax.  System V-like systems have
       /etc/inittab instead.

Ancient History (2)

       On the other hand, there is the file /etc/utmp listing the people currently
       logged in.  It is maintained by login(1).  It has a fixed size, and the
       appropriate index in the file was determined by login(1) using the
       ttyslot() call to find the number of the line in /etc/ttys (counting from
       1).

The semantics of ttyslot

       Thus, the function ttyslot() returns the index of the controlling terminal
       of the calling process in the file /etc/ttys, and that is (usually) the
       same as the index of the entry for the current user in the file /etc/utmp.
       BSD still has the /etc/ttys file, but System V-like systems do not, and
       hence cannot refer to it.  Thus, on such systems the documentation says
       that ttyslot() returns the current user's index in the user accounting data
       base.

RETURN VALUE top

       If successful, this function returns the slot number.  On error (e.g., if
       none of the file descriptors 0, 1 or 2 is associated with a terminal that
       occurs in this data base) it returns 0 on UNIX V6 and V7 and BSD-like
       systems, but -1 on System V-like systems.

CONFORMING TO top

       SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001.  SUSv2 requires
       -1 on error.

NOTES top

       The utmp file is found various places on various systems, such as
       /etc/utmp, /var/adm/utmp, /var/run/utmp.

       The glibc2 implementation of this function reads the file _PATH_TTYS,
       defined in <ttyent.h> as "/etc/ttys".  It returns 0 on error.  Since Linux
       systems do not usually have "/etc/ttys", it will always return 0.

       Minix also has fttyslot(fd).

SEE ALSO top

       getttyent(3), ttyname(3), utmp(5)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-20                          TTYSLOT(3)


ttytype(5) - Linux manual page

NAME | DESCRIPTION | FILES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TTYTYPE(5)                   Linux Programmer's Manual                  TTYTYPE(5)

NAME top

       ttytype - terminal device to default terminal type mapping

DESCRIPTION top

       The /etc/ttytype file associates termcap/terminfo terminal type names with
       tty lines.  Each line consists of a terminal type, followed by whitespace,
       followed by a tty name (a device name without the /dev/) prefix.

       This association is used by the program tset(1) to set the environment
       variable TERM to the default terminal name for the user's current tty.

       This facility was designed for a traditional time-sharing environment
       featuring character-cell terminals hardwired to a UNIX minicomputer.  It is
       little used on modern workstation and personal UNIX systems.

FILES top

       /etc/ttytype
              the tty definitions file.

EXAMPLE top

       A typical /etc/ttytype is:

              con80x25 tty1
              vt320 ttys0

SEE ALSO top

       termcap(5), terminfo(5), agetty(8), mingetty(8)

COLOPHON top

       This page is part of release 3.45 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                               1993-07-24                          TTYTYPE(5)


tty_ioctl(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

TTY_IOCTL(4)                 Linux Programmer's Manual                TTY_IOCTL(4)

NAME top

       tty_ioctl - ioctls for terminals and serial lines

SYNOPSIS top

       #include <termios.h>

       int ioctl(int fd, int cmd, ...);

DESCRIPTION top

       The ioctl(2) call for terminals and serial ports accepts many possible
       command arguments.  Most require a third argument, of varying type, here
       called argp or arg.

       Use of ioctl makes for nonportable programs.  Use the POSIX interface
       described in termios(3) whenever possible.

Get and Set Terminal Attributes

       TCGETS    struct termios *[22margp[0m
              Equivalent to tcgetattr(fd, argp).
              Get the current serial port settings.

       TCSETS    const struct termios *[22margp[0m
              Equivalent to tcsetattr(fd, TCSANOW, argp).
              Set the current serial port settings.

       TCSETSW   const struct termios *[22margp[0m
              Equivalent to tcsetattr(fd, TCSADRAIN, argp).
              Allow the output buffer to drain, and set the current serial port
              settings.

       TCSETSF   const struct termios *[22margp[0m
              Equivalent to tcsetattr(fd, TCSAFLUSH, argp).
              Allow the output buffer to drain, discard pending input, and set the
              current serial port settings.

       The following four ioctls are just like TCGETS, TCSETS, TCSETSW, TCSETSF,
       except that they take a struct termio * instead of a struct termios *.

       TCGETA    struct termio *[22margp[0m

       TCSETA    const struct termio *[22margp[0m

       TCSETAW   const struct termio *[22margp[0m

       TCSETAF   const struct termio *[22margp[0m

Locking the termios structure

       The termios structure of a terminal can be locked.  The lock is itself a
       termios structure, with nonzero bits or fields indicating a locked value.

       TIOCGLCKTRMIOS struct termios *[22margp[0m
              Gets the locking status of the termios structure of the terminal.

       TIOCSLCKTRMIOS const struct termios *[22margp[0m
              Sets the locking status of the termios structure of the terminal.
              Only root (more precisely: a process with the CAP_SYS_ADMIN
              capability) can do this.

Get and Set Window Size

       Window sizes are kept in the kernel, but not used by the kernel (except in
       the case of virtual consoles, where the kernel will update the window size
       when the size of the virtual console changes, for example, by loading a new
       font).

       The following constants and structure are defined in <sys/ioctl.h>.

       TIOCGWINSZ     struct winsize *[22margp[0m
              Get window size.

       TIOCSWINSZ     const struct winsize *[22margp[0m
              Set window size.

       The struct used by these ioctls is defined as

           struct winsize {
               unsigned short ws_row;
               unsigned short ws_col;
               unsigned short ws_xpixel;   /* unused */
               unsigned short ws_ypixel;   /* unused */
           };

       When the window size changes, a SIGWINCH signal is sent to the foreground
       process group.

Sending a Break

       TCSBRK    int [22marg[0m
              Equivalent to tcsendbreak(fd, arg).
              If the terminal is using asynchronous serial data transmission, and
              arg is zero, then send a break (a stream of zero bits) for between
              0.25 and 0.5 seconds.  If the terminal is not using asynchronous
              serial data transmission, then either a break is sent, or the
              function returns without doing anything.  When arg is nonzero,
              nobody knows what will happen.

              (SVr4, UnixWare, Solaris, Linux treat tcsendbreak(fd,arg) with
              nonzero arg like tcdrain(fd).  SunOS treats arg as a multiplier, and
              sends a stream of bits arg times as long as done for zero arg.
              DG/UX and AIX treat arg (when nonzero) as a time interval measured
              in milliseconds.  HP-UX ignores arg.)

       TCSBRKP   int [22marg[0m
              So-called "POSIX version" of TCSBRK.  It treats nonzero arg as a
              timeinterval measured in deciseconds, and does nothing when the
              driver does not support breaks.

       TIOCSBRK  void
              Turn break on, that is, start sending zero bits.

       TIOCCBRK  void
              Turn break off, that is, stop sending zero bits.

Software flow control

       TCXONC    int [22marg[0m
              Equivalent to tcflow(fd, arg).
              See tcflow(3) for the argument values TCOOFF, TCOON, TCIOFF, TCION.

Buffer count and flushing

       FIONREAD  int *[22margp[0m
              Get the number of bytes in the input buffer.

       TIOCINQ   int *[22margp[0m
              Same as FIONREAD.

       TIOCOUTQ  int *[22margp[0m
              Get the number of bytes in the output buffer.

       TCFLSH    int [22marg[0m
              Equivalent to tcflush(fd, arg).
              See tcflush(3) for the argument values TCIFLUSH, TCOFLUSH,
              TCIOFLUSH.

Faking input

       TIOCSTI   const char *[22margp[0m
              Insert the given byte in the input queue.

Redirecting console output

       TIOCCONS  void
              Redirect output that would have gone to /dev/console or /dev/tty0 to
              the given terminal.  If that was a pseudoterminal master, send it to
              the slave.  In Linux before version 2.6.10, anybody can do this as
              long as the output was not redirected yet; since version 2.6.10,
              only root (a process with the CAP_SYS_ADMIN capability) may do this.
              If output was redirected already EBUSY is returned, but redirection
              can be stopped by using this ioctl with fd pointing at /dev/console
              or /dev/tty0.

Controlling terminal

       TIOCSCTTY int [22marg[0m
              Make the given terminal the controlling terminal of the calling
              process.  The calling process must be a session leader and not have
              a controlling terminal already.  If this terminal is already the
              controlling terminal of a different session group then the ioctl
              fails with EPERM, unless the caller is root (more precisely: has the
              CAP_SYS_ADMIN capability) and arg equals 1, in which case the
              terminal is stolen, and all processes that had it as controlling
              terminal lose it.

       TIOCNOTTY void
              If the given terminal was the controlling terminal of the calling
              process, give up this controlling terminal.  If the process was
              session leader, then send SIGHUP and SIGCONT to the foreground
              process group and all processes in the current session lose their
              controlling terminal.

Process group and session ID

       TIOCGPGRP pid_t *[22margp[0m
              When successful, equivalent to *argp = tcgetpgrp(fd).
              Get the process group ID of the foreground process group on this
              terminal.

       TIOCSPGRP const pid_t *[22margp[0m
              Equivalent to tcsetpgrp(fd, *argp).
              Set the foreground process group ID of this terminal.

       TIOCGSID  pid_t *[22margp[0m
              Get the session ID of the given terminal.  This will fail with
              ENOTTY in case the terminal is not a master pseudoterminal and not
              our controlling terminal.  Strange.

Exclusive mode

       TIOCEXCL  void
              Put the terminal into exclusive mode.  No further open(2) operations
              on the terminal are permitted.  (They will fail with EBUSY, except
              for root, that is, a process with the CAP_SYS_ADMIN capability.)

       TIOCNXCL  void
              Disable exclusive mode.

Line discipline

       TIOCGETD  int *[22margp[0m
              Get the line discipline of the terminal.

       TIOCSETD  const int *[22margp[0m
              Set the line discipline of the terminal.

Pseudoterminal ioctls

       TIOCPKT   const int *[22margp[0m
              Enable (when *argp is nonzero) or disable packet mode.  Can be
              applied to the master side of a pseudoterminal only (and will return
              ENOTTY otherwise).  In packet mode, each subsequent read(2) will
              return a packet that either contains a single nonzero control byte,
              or has a single byte containing zero (' ') followed by data written
              on the slave side of the pseudoterminal.  If the first byte is not
              TIOCPKT_DATA (0), it is an OR of one or more of the following bits:

              TIOCPKT_FLUSHREAD   The read queue for the terminal is flushed.
              TIOCPKT_FLUSHWRITE  The write queue for the terminal is flushed.
              TIOCPKT_STOP        Output to the terminal is stopped.
              TIOCPKT_START       Output to the terminal is restarted.
              TIOCPKT_DOSTOP      The start and stop characters are ^S/^Q.
              TIOCPKT_NOSTOP      The start and stop characters are not ^S/^Q.

              While this mode is in use, the presence of control status
              information to be read from the master side may be detected by a
              select(2) for exceptional conditions.

              This mode is used by rlogin(1) and rlogind(8) to implement a remote-
              echoed, locally ^S/^Q flow-controlled remote login.

              The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have not
              been implemented under Linux.

Modem control

       TIOCMGET  int *[22margp[0m
              get the status of modem bits.

       TIOCMSET  const int *[22margp[0m
              set the status of modem bits.

       TIOCMBIC  const int *[22margp[0m
              clear the indicated modem bits.

       TIOCMBIS  const int *[22margp[0m
              set the indicated modem bits.

       Bits used by these four ioctls:

       TIOCM_LE        DSR (data set ready/line enable)
       TIOCM_DTR       DTR (data terminal ready)
       TIOCM_RTS       RTS (request to send)
       TIOCM_ST        Secondary TXD (transmit)
       TIOCM_SR        Secondary RXD (receive)
       TIOCM_CTS       CTS (clear to send)
       TIOCM_CAR       DCD (data carrier detect)
       TIOCM_CD         see TIOCM_CAR
       TIOCM_RNG       RNG (ring)
       TIOCM_RI         see TIOCM_RNG
       TIOCM_DSR       DSR (data set ready)

Marking a line as local

       TIOCGSOFTCAR   int *[22margp[0m
              ("Get software carrier flag") Get the status of the CLOCAL flag in
              the c_cflag field of the termios structure.

       TIOCSSOFTCAR   const int *[22margp[0m
              ("Set software carrier flag") Set the CLOCAL flag in the termios
              structure when *argp is nonzero, and clear it otherwise.

       If the CLOCAL flag for a line is off, the hardware carrier detect (DCD)
       signal is significant, and an open(2) of the corresponding terminal will
       block until DCD is asserted, unless the O_NONBLOCK flag is given.  If
       CLOCAL is set, the line behaves as if DCD is always asserted.  The software
       carrier flag is usually turned on for local devices, and is off for lines
       with modems.

Linux-specific

       For the TIOCLINUX ioctl, see console_ioctl(4).

Kernel debugging

       #include <linux/tty.h>

       TIOCTTYGSTRUCT struct tty_struct *[22margp[0m
              Get the tty_struct corresponding to fd.

RETURN VALUE top

       The ioctl(2) system call returns 0 on success.  On error it returns -1 and
       sets errno appropriately.

ERRORS top

       EINVAL Invalid command parameter.

       ENOIOCTLCMD
              Unknown command.

       ENOTTY Inappropriate fd.

       EPERM  Insufficient permission.

EXAMPLE top

       Check the condition of DTR on the serial port.

       #include <termios.h>
       #include <fcntl.h>
       #include <sys/ioctl.h>

       int
       main(void)
       {
           int fd, serial;

           fd = open("/dev/ttyS0", O_RDONLY);
           ioctl(fd, TIOCMGET, &serial);
           if (serial & TIOCM_DTR)
               puts("TIOCM_DTR is not set");
           else
               puts("TIOCM_DTR is set");
           close(fd);
       }

SEE ALSO top

       ioctl(2), termios(3), console_ioctl(4), pty(7)

COLOPHON top

       This page is part of release 3.45 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-10-29                        TTY_IOCTL(4)


tzfile(5) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

TZFILE(5)                    Linux Programmer's Manual                   TZFILE(5)

NAME top

       tzfile - timezone information

DESCRIPTION top

       This page describes the structure of the timezone files used by tzset(3).
       These files are typically found under one of the directories
       /usr/lib/zoneinfo or /usr/share/zoneinfo.

       Timezone information files begin with the magic characters "TZif" to
       identify them as timezone information files, followed by a character
       identifying the version of the file's format (as of 2005, either an ASCII
       NUL ('\0') or a '2') followed by fifteen bytes containing zeros reserved
       for future use, followed by six four-byte values of type long, written in a
       "standard" byte order (the high-order byte of the value is written first).
       These values are, in order:

       tzh_ttisgmtcnt
              The number of UTC/local indicators stored in the file.

       tzh_ttisstdcnt
              The number of standard/wall indicators stored in the file.

       tzh_leapcnt
              The number of leap seconds for which data is stored in the file.

       tzh_timecnt
              The number of "transition times" for which data is stored in the
              file.

       tzh_typecnt
              The number of "local time types" for which data is stored in the
              file (must not be zero).

       tzh_charcnt
              The number of characters of "timezone abbreviation strings" stored
              in the file.

       The above header is followed by tzh_timecnt four-byte values of type long,
       sorted in ascending order.  These values are written in "standard" byte
       order.  Each is used as a transition time (as returned by time(2)) at which
       the rules for computing local time change.  Next come tzh_timecnt one-byte
       values of type unsigned char; each one tells which of the different types
       of "local time" types described in the file is associated with the same-
       indexed transition time.  These values serve as indices into an array of
       ttinfo structures (with tzh_typecnt entries) that appear next in the file;
       these structures are defined as follows:

           struct ttinfo {
               long         tt_gmtoff;
               int          tt_isdst;
               unsigned int tt_abbrind;
           };

       Each structure is written as a four-byte value for tt_gmtoff of type long,
       in a standard byte order, followed by a one-byte value for tt_isdst and a
       one-byte value for tt_abbrind.  In each structure, tt_gmtoff gives the
       number of seconds to be added to UTC, tt_isdst tells whether tm_isdst
       should be set by localtime(3), and tt_abbrind serves as an index into the
       array of timezone abbreviation characters that follow the ttinfo
       structure(s) in the file.

       Then there are tzh_leapcnt pairs of four-byte values, written in standard
       byte order; the first value of each pair gives the time (as returned by
       time(2)) at which a leap second occurs; the second gives the total number
       of leap seconds to be applied after the given time.  The pairs of values
       are sorted in ascending order by time.

       Then there are tzh_ttisstdcnt standard/wall indicators, each stored as a
       one-byte value; they tell whether the transition times associated with
       local time types were specified as standard time or wall clock time, and
       are used when a timezone file is used in handling POSIX-style timezone
       environment variables.

       Finally, there are tzh_ttisgmtcnt UTC/local indicators, each stored as a
       one-byte value; they tell whether the transition times associated with
       local time types were specified as UTC or local time, and are used when a
       timezone file is used in handling POSIX-style timezone environment
       variables.

       localtime(3) uses the first standard-time ttinfo structure in the file (or
       simply the first ttinfo structure in the absence of a standard-time
       structure) if either tzh_timecnt is zero or the time argument is less than
       the first transition time recorded in the file.

       For version-2-format timezone files, the above header and data is followed
       by a second header and data, identical in format except that eight bytes
       are used for each transition time or leap-second time.  After the second
       header and data comes a newline-enclosed, POSIX-TZ-environment-variable-
       style string for use in handling instants after the last transition time
       stored in the file (with nothing between the newlines if there is no POSIX
       representation for such instants).

SEE ALSO top

       ctime(3), tzset(3), tzselect(8),

       timezone/tzfile.h in the glibc source tree

COLOPHON top

       This page is part of release 3.45 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/.

                                    2012-05-04                           TZFILE(5)


tzselect(8) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | ENVIRONMENT | FILES | SEE ALSO | COLOPHON The Linux Programming Interface

TZSELECT(8)                 Linux System Administration                TZSELECT(8)

NAME top

       tzselect - select a timezone

SYNOPSIS top

       tzselect

DESCRIPTION top

       The tzselect program asks the user for information about the current
       location, and outputs the resulting timezone description to standard
       output.  The output is suitable as a value for the TZ environment variable.

       All interaction with the user is done via standard input and standard
       error.

EXIT STATUS top

       The exit status is zero if a timezone was successfully obtained from the
       user, nonzero otherwise.

ENVIRONMENT top

       AWK    Name of a Posix-compliant awk program (default: awk).

       TZDIR  Name of the directory containing timezone data files (default:
              /usr/share/zoneinfo).

FILES top

       TZDIR[22m/iso3166.tab[0m
              Table of ISO 3166 2-letter country codes and country names.

       TZDIR[22m/zone.tab[0m
              Table of country codes, latitude and longitude, TZ values, and
              descriptive comments.

       TZDIR[22m/TZ[0m
              Time zone data file for timezone TZ.

SEE ALSO top

       tzfile(5), zdump(8), zic(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-05-18                         TZSELECT(8)


ualarm(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UALARM(3)                    Linux Programmer's Manual                   UALARM(3)

NAME top

       ualarm - schedule signal after given number of microseconds

SYNOPSIS top

       #include <unistd.h>

       useconds_t ualarm(useconds_t usecs, useconds_t interval);

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

       ualarm():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The ualarm() function causes the signal SIGALRM to be sent to the invoking
       process after (not less than) usecs microseconds.  The delay may be
       lengthened slightly by any system activity or by the time spent processing
       the call or by the granularity of system timers.

       Unless caught or ignored, the SIGALRM signal will terminate the process.

       If the interval argument is nonzero, further SIGALRM signals will be sent
       every interval microseconds after the first.

RETURN VALUE top

       This function returns the number of microseconds remaining for any alarm
       that was previously set, or 0 if no alarm was pending.

ERRORS top

       EINTR  Interrupted by a signal.

       EINVAL usecs or interval is not smaller than 1000000.  (On systems where
              that is considered an error.)

CONFORMING TO top

       4.3BSD, POSIX.1-2001.  POSIX.1-2001 marks ualarm() as obsolete.
       POSIX.1-2008 removes the specification of ualarm().  4.3BSD, SUSv2, and
       POSIX do not define any errors.

NOTES top

       The type useconds_t is an unsigned integer type capable of holding integers
       in the range [0,1000000].  On the original BSD implementation, and in glibc
       before version 2.1, the arguments to ualarm() were instead typed as
       unsigned int.  Programs will be more portable if they never mention
       useconds_t explicitly.

       The interaction of this function with other timer functions such as
       alarm(2), sleep(3), nanosleep(2), setitimer(2), timer_create(2),
       timer_delete(2), timer_getoverrun(2), timer_gettime(2), timer_settime(2),
       usleep(3) is unspecified.

       This function is obsolete.  Use setitimer(2) or POSIX interval timers
       (timer_create(2), etc.)  instead.

SEE ALSO top

       alarm(2), getitimer(2), nanosleep(2), select(2), setitimer(2), usleep(3),
       time(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-09-20                           UALARM(3)


udp(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | SEE ALSO | COLOPHON The Linux Programming Interface

UDP(7)                       Linux Programmer's Manual                      UDP(7)

NAME top

       udp - User Datagram Protocol for IPv4

SYNOPSIS top

       #include <sys/socket.h>
       #include <netinet/in.h>

       udp_socket = socket(AF_INET, SOCK_DGRAM, 0);

DESCRIPTION top

       This is an implementation of the User Datagram Protocol described in
       RFC 768.  It implements a connectionless, unreliable datagram packet
       service.  Packets may be reordered or duplicated before they arrive.  UDP
       generates and checks checksums to catch transmission errors.

       When a UDP socket is created, its local and remote addresses are
       unspecified.  Datagrams can be sent immediately using sendto(2) or
       sendmsg(2) with a valid destination address as an argument.  When
       connect(2) is called on the socket, the default destination address is set
       and datagrams can now be sent using send(2) or write(2) without specifying
       a destination address.  It is still possible to send to other destinations
       by passing an address to sendto(2) or sendmsg(2).  In order to receive
       packets, the socket can be bound to a local address first by using bind(2).
       Otherwise the socket layer will automatically assign a free local port out
       of the range defined by /proc/sys/net/ipv4/ip_local_port_range and bind the
       socket to INADDR_ANY.

       All receive operations return only one packet.  When the packet is smaller
       than the passed buffer, only that much data is returned; when it is bigger,
       the packet is truncated and the MSG_TRUNC flag is set.  MSG_WAITALL is not
       supported.

       IP options may be sent or received using the socket options described in
       ip(7).  They are only processed by the kernel when the appropriate /proc
       parameter is enabled (but still passed to the user even when it is turned
       off).  See ip(7).

       When the MSG_DONTROUTE flag is set on sending, the destination address must
       refer to a local interface address and the packet is only sent to that
       interface.

       By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery.
       This means the kernel will keep track of the MTU to a specific target IP
       address and return EMSGSIZE when a UDP packet write exceeds it.  When this
       happens, the application should decrease the packet size.  Path MTU
       discovery can be also turned off using the IP_MTU_DISCOVER socket option or
       the /proc/sys/net/ipv4/ip_no_pmtu_disc file; see ip(7) for details.  When
       turned off, UDP will fragment outgoing UDP packets that exceed the
       interface MTU.  However, disabling it is not recommended for performance
       and reliability reasons.

Address Format

       UDP uses the IPv4 sockaddr_in address format described in ip(7).

Error Handling

       All fatal errors will be passed to the user as an error return even when
       the socket is not connected.  This includes asynchronous errors received
       from the network.  You may get an error for an earlier packet that was sent
       on the same socket.  This behavior differs from many other BSD socket
       implementations which don't pass any errors unless the socket is connected.
       Linux's behavior is mandated by RFC 1122.

       For compatibility with legacy code, in Linux 2.0 and 2.2 it was possible to
       set the SO_BSDCOMPAT SOL_SOCKET option to receive remote errors only when
       the socket has been connected (except for EPROTO and EMSGSIZE).  Locally
       generated errors are always passed.  Support for this socket option was
       removed in later kernels; see socket(7) for further information.

       When the IP_RECVERR option is enabled, all errors are stored in the socket
       error queue, and can be received by recvmsg(2) with the MSG_ERRQUEUE flag
       set.

/proc interfaces

       System-wide UDP parameter settings can be accessed by files in the
       directory /proc/sys/net/ipv4/.

       udp_mem (since Linux 2.6.25)
              This is a vector of three integers governing the number of pages
              allowed for queueing by all UDP sockets.

              min       Below this number of pages, UDP is not bothered about its
                        memory appetite.  When the amount of memory allocated by
                        UDP exceeds this number, UDP starts to moderate memory
                        usage.

              pressure  This value was introduced to follow the format of tcp_mem
                        (see tcp(7)).

              max       Number of pages allowed for queueing by all UDP sockets.

              Defaults values for these three items are calculated at boot time
              from the amount of available memory.

       udp_rmem_min (integer; default value: PAGE_SIZE; since Linux 2.6.25)
              Minimal size, in bytes, of receive buffers used by UDP sockets in
              moderation.  Each UDP socket is able to use the size for receiving
              data, even if total pages of UDP sockets exceed udp_mem pressure.

       udp_wmem_min (integer; default value: PAGE_SIZE; since Linux 2.6.25)
              Minimal size, in bytes, of send buffer used by UDP sockets in
              moderation.  Each UDP socket is able to use the size for sending
              data, even if total pages of UDP sockets exceed udp_mem pressure.

Socket Options

       To set or get a UDP socket option, call getsockopt(2) to read or
       setsockopt(2) to write the option with the option level argument set to
       IPPROTO_UDP.

       UDP_CORK (since Linux 2.5.44)
              If this option is enabled, then all data output on this socket is
              accumulated into a single datagram that is transmitted when the
              option is disabled.  This option should not be used in code intended
              to be portable.

Ioctls

       These ioctls can be accessed using ioctl(2).  The correct syntax is:

              int value;
              error = ioctl(udp_socket, ioctl_type, &value);

       FIONREAD (SIOCINQ)
              Gets a pointer to an integer as argument.  Returns the size of the
              next pending datagram in the integer in bytes, or 0 when no datagram
              is pending.  Warning: Using FIONREAD, it is impossible to
              distinguish the case where no datagram is pending from the case
              where the next pending datagram contains zero bytes of data.  It is
              safer to use select(2), poll(2), or epoll(7) to distinguish these
              cases.

       TIOCOUTQ (SIOCOUTQ)
              Returns the number of data bytes in the local send queue.  Only
              supported with Linux 2.4 and above.

       In addition all ioctls documented in ip(7) and socket(7) are supported.

ERRORS top

       All errors documented for socket(7) or ip(7) may be returned by a send or
       receive on a UDP socket.

       ECONNREFUSED
              No receiver was associated with the destination address.  This might
              be caused by a previous packet sent over the socket.

VERSIONS top

       IP_RECVERR is a new feature in Linux 2.2.

SEE ALSO top

       ip(7), raw(7), socket(7), udplite(7)

       RFC 768 for the User Datagram Protocol.
       RFC 1122 for the host requirements.
       RFC 1191 for a description of path MTU discovery.

COLOPHON top

       This page is part of release 3.45 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                               2010-06-13                              UDP(7)


udplite(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | BUGS | FILES | VERSIONS | SEE ALSO | COLOPHON The Linux Programming Interface

UDPLITE(7)                   Linux Programmer's Manual                  UDPLITE(7)

NAME top

       udplite - Lightweight User Datagram Protocol

SYNOPSIS top

       #include <sys/socket.h>

       sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);

DESCRIPTION top

       This is an implementation of the Lightweight User Datagram Protocol (UDP-
       Lite), as described in RFC 3828.

       UDP-Lite is an extension of UDP (RFC 768) to support variable-length
       checksums.  This has advantages for some types of multimedia transport that
       may be able to make use of slightly damaged datagrams, rather than having
       them discarded by lower-layer protocols.

       The variable-length checksum coverage is set via a setsockopt(2) option.
       If this option is not set, the only difference to UDP is in using a
       different IP protocol identifier (IANA number 136).

       The UDP-Lite implementation is a full extension of udp(7), i.e., it shares
       the same API and API behaviour, and in addition offers two socket options
       to control the checksum coverage.

Address Format

       UDP-Litev4 uses the sockaddr_in address format described in ip(7).  UDP-
       Litev6 uses the sockaddr_in6 address format described in ipv6(7).

Socket Options

       To set or get a UDP-Lite socket option, call getsockopt(2) to read or
       setsockopt(2) to write the option with the option level argument set to
       IPPROTO_UDPLITE.  In addition, all IPPROTO_UDP socket options are valid on
       a UDP-Lite socket.  See udp(7) for more information.

       The following two options are specific to UDP-Lite.

       UDPLITE_SEND_CSCOV
              This option sets the sender checksum coverage and takes an int as
              argument, with a checksum coverage value in the range 0..2^16-1.

              A value of 0 means that the entire datagram is always covered.
              Values from 1-7 are illegal (RFC 3828, 3.1) and are rounded up to
              the minimum coverage of 8.

              With regard to IPv6 jumbograms (RFC 2675), the UDP-Litev6 checksum
              coverage is limited to the first 2^16-1 octets, as per RFC 3828,
              3.5.  Higher values are therefore silently truncated to 2^16-1.  If
              in doubt, the current coverage value can always be queried using
              getsockopt(2).

       UDPLITE_RECV_CSCOV
              This is the receiver-side analogue and uses the same argument format
              and value range as UDPLITE_SEND_CSCOV.  This option is not required
              to enable traffic with partial checksum coverage.  Its function is
              that of a traffic filter: when enabled, it instructs the kernel to
              drop all packets which have a coverage less than the specified
              coverage value.

              When the value of UDPLITE_RECV_CSCOV exceeds the actual packet
              coverage, incoming packets are silently dropped, but may generate a
              warning message in the system log.

ERRORS top

       All errors documented for udp(7) may be returned.  UDP-Lite does not add
       further errors.

BUGS top

       Where glibc support is missing, the following definitions are needed:

           #define IPPROTO_UDPLITE     136
           #define UDPLITE_SEND_CSCOV  10
           #define UDPLITE_RECV_CSCOV  11

FILES top

       /proc/net/snmp - basic UDP-Litev4 statistics counters.
       /proc/net/snmp6 - basic UDP-Litev6 statistics counters.

VERSIONS top

       UDP-Litev4/v6 first appeared in Linux 2.6.20.

SEE ALSO top

       ip(7), ipv6(7), socket(7), udp(7)

       RFC 3828 for the Lightweight User Datagram Protocol (UDP-Lite).

       Documentation/networking/udplite.txt in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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-03                          UDPLITE(7)


ulimit(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

ULIMIT(3)                    Linux Programmer's Manual                   ULIMIT(3)

NAME top

       ulimit - get and set user limits

SYNOPSIS top

       #include <ulimit.h>

       long ulimit(int cmd, long newlimit);

DESCRIPTION top

       Warning: This routine is obsolete.  Use getrlimit(2), setrlimit(2), and
       sysconf(3) instead.  For the shell command ulimit(), see bash(1).

       The ulimit() call will get or set some limit for the calling process.  The
       cmd argument can have one of the following values.

       UL_GETFSIZE
              Return the limit on the size of a file, in units of 512 bytes.

       UL_SETFSIZE
              Set the limit on the size of a file.

       3      (Not implemented for Linux.)  Return the maximum possible address of
              the data segment.

       4      (Implemented but no symbolic constant provided.)  Return the maximum
              number of files that the calling process can open.

RETURN VALUE top

       On success, ulimit() returns a nonnegative value.  On error, -1 is
       returned, and errno is set appropriately.

ERRORS top

       EPERM  A unprivileged process tried to increase a limit.

CONFORMING TO top

       SVr4, POSIX.1-2001.  POSIX.1-2008 marks ulimit() as obsolete.

SEE ALSO top

       bash(1), getrlimit(2), setrlimit(2), sysconf(3)

COLOPHON top

       This page is part of release 3.45 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                           ULIMIT(3)


umask(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UMASK(2)                     Linux Programmer's Manual                    UMASK(2)

NAME top

       umask - set file mode creation mask

SYNOPSIS top

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

       mode_t umask(mode_t mask);

DESCRIPTION top

       umask() sets the calling process's file mode creation mask (umask) to mask
       & 0777 (i.e., only the file permission bits of mask are used), and returns
       the previous value of the mask.

       The umask is used by open(2), mkdir(2), and other system calls that create
       files to modify the permissions placed on newly created files or
       directories.  Specifically, permissions in the umask are turned off from
       the mode argument to open(2) and mkdir(2).

       The constants that should be used to specify mask are described under
       stat(2).

       The typical default value for the process umask is S_IWGRP | S_IWOTH (octal
       022).  In the usual case where the mode argument to open(2) is specified
       as:

           S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH

       (octal 0666) when creating a new file, the permissions on the resulting
       file will be:

           S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH

       (because 0666 & ~022 = 0644; i.e., rw-r--r--).

RETURN VALUE top

       This system call always succeeds and the previous value of the mask is
       returned.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       A child process created via fork(2) inherits its parent's umask.  The umask
       is left unchanged by execve(2).

       The umask setting also affects the permissions assigned to POSIX IPC
       objects (mq_open(3), sem_open(3), shm_open(3)), FIFOs (mkfifo(3)), and UNIX
       domain sockets (unix(7)) created by the process.  The umask does not affect
       the permissions assigned to System V IPC objects created by the process
       (using msgget(2), semget(2), shmget(2)).

SEE ALSO top

       chmod(2), mkdir(2), open(2), stat(2)

COLOPHON top

       This page is part of release 3.45 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-01-09                            UMASK(2)


umount(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UMOUNT(2)                    Linux Programmer's Manual                   UMOUNT(2)

NAME top

       umount, umount2 - unmount file system

SYNOPSIS top

       #include <sys/mount.h>

       int umount(const char *target);

       int umount2(const char *target, int flags);

DESCRIPTION top

       umount() and umount2() remove the attachment of the (topmost) file system
       mounted on target.

       Appropriate privilege (Linux: the CAP_SYS_ADMIN capability) is required to
       unmount file systems.

       Linux 2.1.116 added the umount2() system call, which, like umount(),
       unmounts a target, but allows additional flags controlling the behavior of
       the operation:

       MNT_FORCE (since Linux 2.1.116)
              Force unmount even if busy.  This can cause data loss.  (Only for
              NFS mounts.)

       MNT_DETACH (since Linux 2.4.11)
              Perform a lazy unmount: make the mount point unavailable for new
              accesses, and actually perform the unmount when the mount point
              ceases to be busy.

       MNT_EXPIRE (since Linux 2.6.8)
              Mark the mount point as expired.  If a mount point is not currently
              in use, then an initial call to umount2() with this flag fails with
              the error EAGAIN, but marks the mount point as expired.  The mount
              point remains expired as long as it isn't accessed by any process.
              A second umount2() call specifying MNT_EXPIRE unmounts an expired
              mount point.  This flag cannot be specified with either MNT_FORCE or
              MNT_DETACH.

       UMOUNT_NOFOLLOW (since Linux 2.6.34)
              Don't dereference target if it is a symbolic link.  This flag allows
              security problems to be avoided in set-user-ID-root programs that
              allow unprivileged users to unmount file systems.

RETURN VALUE top

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

ERRORS top

       The error values given below result from file-system type independent
       errors.  Each file system type may have its own special errors and its own
       special behavior.  See the Linux kernel source code for details.

       EAGAIN A call to umount2() specifying MNT_EXPIRE successfully marked an
              unbusy file system as expired.

       EBUSY  target could not be unmounted because it is busy.

       EFAULT target points outside the user address space.

       EINVAL target is not a mount point.  Or, umount2() was called with
              MNT_EXPIRE and either MNT_DETACH or MNT_FORCE.

       ENAMETOOLONG
              A pathname was longer than MAXPATHLEN.

       ENOENT A pathname was empty or had a nonexistent component.

       ENOMEM The kernel could not allocate a free page to copy filenames or data
              into.

       EPERM  The caller does not have the required privileges.

VERSIONS top

       MNT_DETACH and MNT_EXPIRE are only available in glibc since version 2.11.

CONFORMING TO top

       These functions are Linux-specific and should not be used in programs
       intended to be portable.

NOTES top

       The original umount() function was called as umount(device) and would
       return ENOTBLK when called with something other than a block device.  In
       Linux 0.98p4 a call umount(dir) was added, in order to support anonymous
       devices.  In Linux 2.3.99-pre7 the call umount(device) was removed, leaving
       only umount(dir) (since now devices can be mounted in more than one place,
       so specifying the device does not suffice).

SEE ALSO top

       mount(2), path_resolution(7), mount(8), umount(8)

COLOPHON top

       This page is part of release 3.45 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                               2010-06-19                           UMOUNT(2)


undocumented(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COLOPHON The Linux Programming Interface

UNDOCUMENTED(3)              Linux Programmer's Manual             UNDOCUMENTED(3)

NAME top

       none - undocumented library functions

SYNOPSIS top

       Undocumented library functions

DESCRIPTION top

       This man page mentions those library functions which are implemented in the
       standard libraries but not yet documented in man pages.

Solicitation

       If you have information about these functions, please look in the source
       code, write a man page (using a style similar to that of the other Linux
       section 3 man pages), and send it to mtk.manpages@gmail.com for inclusion
       in the next man page release.

The List

       authdes_create(3), authdes_getucred(3), authdes_pk_create(3),
       clntunix_create(3), creat64(3), dn_skipname(3), fcrypt(3), fp_nquery(3),
       fp_query(3), fp_resstat(3), freading(3), freopen64(3), fseeko64(3),
       ftello64(3), ftw64(3), fwscanf(3), get_avphys_pages(3), getdirentries64(3),
       getmsg(3), getnetname(3), get_nprocs(3), get_nprocs_conf(3),
       get_phys_pages(3), getpublickey(3), getsecretkey(3), h_errlist(3),
       host2netname(3), hostalias(3), inet_nsap_addr(3), inet_nsap_ntoa(3),
       init_des(3), libc_nls_init(3), lio_listio(3), mstats(3), netname2host(3),
       netname2user(3), nlist(3), obstack_free(3), parse_printf_format(3),
       p_cdname(3), p_cdnname(3), p_class(3), p_fqname(3), p_option(3),
       p_query(3), printf_size(3), printf_size_info(3), p_rr(3), p_time(3),
       p_type(3), putlong(3), putshort(3), re_compile_fastmap(3),
       re_compile_pattern(3), register_printf_function(3), re_match(3),
       re_match_2(3), re_rx_search(3), re_search(3), re_search_2(3),
       re_set_registers(3), re_set_syntax(3), res_send_setqhook(3),
       res_send_setrhook(3), ruserpass(3), setfileno(3), sethostfile(3),
       svc_exit(3), svcudp_enablecache(3), tell(3), tr_break(3), tzsetwall(3),
       ufc_dofinalperm(3), ufc_doit(3), user2netname(3), vlimit(3), vtimes(3),
       wcschrnul(3), wcsftime(3), wscanf(3), xdr_authdes_cred(3),
       xdr_authdes_verf(3), xdr_cryptkeyarg(3), xdr_cryptkeyres(3), xdr_datum(3),
       xdr_des_block(3), xdr_domainname(3), xdr_getcredres(3), xdr_keybuf(3),
       xdr_keystatus(3), xdr_mapname(3), xdr_netnamestr(3), xdr_netobj(3),
       xdr_passwd(3), xdr_peername(3), xdr_rmtcall_args(3), xdr_rmtcallres(3),
       xdr_unixcred(3), xdr_yp_buf(3), xdr_yp_inaddr(3), xdr_ypbind_binding(3),
       xdr_ypbind_resp(3), xdr_ypbind_resptype(3), xdr_ypbind_setdom(3),
       xdr_ypdelete_args(3), xdr_ypmaplist(3), xdr_ypmaplist_str(3),
       xdr_yppasswd(3), xdr_ypreq_key(3), xdr_ypreq_nokey(3), xdr_ypresp_all(3),
       xdr_ypresp_all_seq(3), xdr_ypresp_key_val(3), xdr_ypresp_maplist(3),
       xdr_ypresp_master(3), xdr_ypresp_order(3), xdr_ypresp_val(3),
       xdr_ypstat(3), xdr_ypupdate_args(3), yp_all(3), yp_bind(3),
       yperr_string(3), yp_first(3), yp_get_default_domain(3), yp_maplist(3),
       yp_master(3), yp_match(3), yp_next(3), yp_order(3), ypprot_err(3),
       yp_unbind(3), yp_update(3)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-21                     UNDOCUMENTED(3)


ungetwc(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UNGETWC(3)                   Linux Programmer's Manual                  UNGETWC(3)

NAME top

       ungetwc - push back a wide character onto a FILE stream

SYNOPSIS top

       #include <wchar.h>

       wint_t ungetwc(wint_t wc, FILE *stream);

DESCRIPTION top

       The ungetwc() function is the wide-character equivalent of the ungetc(3)
       function.  It pushes back a wide character onto stream and returns it.

       If wc is WEOF, it returns WEOF.  If wc is an invalid wide character, it
       sets errno to EILSEQ and returns WEOF.

       If wc is a valid wide character, it is pushed back onto the stream and thus
       becomes available for future wide-character read operations.  The file-
       position indicator is decremented by one or more.  The end-of-file
       indicator is cleared.  The backing storage of the file is not affected.

       Note: wc need not be the last wide-character read from the stream; it can
       be any other valid wide character.

       If the implementation supports multiple push-back operations in a row, the
       pushed-back wide characters will be read in reverse order; however, only
       one level of push-back is guaranteed.

RETURN VALUE top

       The ungetwc() function returns wc when successful, or WEOF upon failure.

CONFORMING TO top

       C99.

NOTES top

       The behavior of ungetwc() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       fgetwc(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-09-19                          UNGETWC(3)


unicode(7) - Linux manual page

NAME | DESCRIPTION | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

UNICODE(7)                   Linux Programmer's Manual                  UNICODE(7)

NAME top

       Unicode - universal character set

DESCRIPTION top

       The international standard ISO 10646 defines the Universal Character Set
       (UCS).  UCS contains all characters of all other character set standards.
       It also guarantees round-trip compatibility, i.e., conversion tables can be
       built such that no information is lost when a string is converted from any
       other encoding to UCS and back.

       UCS contains the characters required to represent practically all known
       languages.  This includes not only the Latin, Greek, Cyrillic, Hebrew,
       Arabic, Armenian, and Georgian scripts, but also Chinese, Japanese and
       Korean Han ideographs as well as scripts such as Hiragana, Katakana,
       Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu,
       Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, Tibetan, Runic, Ethiopic,
       Canadian Syllabics, Cherokee, Mongolian, Ogham, Myanmar, Sinhala, Thaana,
       Yi, and others.  For scripts not yet covered, research on how to best
       encode them for computer usage is still going on and they will be added
       eventually.  This might eventually include not only Hieroglyphs and various
       historic Indo-European languages, but even some selected artistic scripts
       such as Tengwar, Cirth, and Klingon.  UCS also covers a large number of
       graphical, typographical, mathematical and scientific symbols, including
       those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR
       fonts, as well as many word processing and publishing systems, and more are
       being added.

       The UCS standard (ISO 10646) describes a 31-bit character set architecture
       consisting of 128 24-bit groups, each divided into 256 16-bit planes made
       up of 256 8-bit rows with 256 column positions, one for each character.
       Part 1 of the standard (ISO 10646-1) defines the first 65534 code positions
       (0x0000 to 0xfffd), which form the Basic Multilingual Plane (BMP), that is
       plane 0 in group 0.  Part 2 of the standard (ISO 10646-2) adds characters
       to group 0 outside the BMP in several supplementary planes in the range
       0x10000 to 0x10ffff.  There are no plans to add characters beyond 0x10ffff
       to the standard, therefore of the entire code space, only a small fraction
       of group 0 will ever be actually used in the foreseeable future.  The BMP
       contains all characters found in the commonly used other character sets.
       The supplemental planes added by ISO 10646-2 cover only more exotic
       characters for special scientific, dictionary printing, publishing
       industry, higher-level protocol and enthusiast needs.

       The representation of each UCS character as a 2-byte word is referred to as
       the UCS-2 form (only for BMP characters), whereas UCS-4 is the
       representation of each character by a 4-byte word.  In addition, there
       exist two encoding forms UTF-8 for backward compatibility with ASCII
       processing software and UTF-16 for the backward-compatible handling of non-
       BMP characters up to 0x10ffff by UCS-2 software.

       The UCS characters 0x0000 to 0x007f are identical to those of the classic
       US-ASCII character set and the characters in the range 0x0000 to 0x00ff are
       identical to those in ISO 8859-1 Latin-1.

Combining Characters

       Some code points in UCS have been assigned to combining characters.  These
       are similar to the nonspacing accent keys on a typewriter.  A combining
       character just adds an accent to the previous character.  The most
       important accented characters have codes of their own in UCS, however, the
       combining character mechanism allows us to add accents and other
       diacritical marks to any character.  The combining characters always follow
       the character which they modify.  For example, the German character Umlaut-
       A ("Latin capital letter A with diaeresis") can either be represented by
       the precomposed UCS code 0x00c4, or alternatively as the combination of a
       normal "Latin capital letter A" followed by a "combining diaeresis": 0x0041
       0x0308.

       Combining characters are essential for instance for encoding the Thai
       script or for mathematical typesetting and users of the International
       Phonetic Alphabet.

Implementation Levels

       As not all systems are expected to support advanced mechanisms like
       combining characters, ISO 10646-1 specifies the following three
       implementation levels of UCS:

       Level 1  Combining characters and Hangul Jamo (a variant encoding of the
                Korean script, where a Hangul syllable glyph is coded as a triplet
                or pair of vovel/consonant codes) are not supported.

       Level 2  In addition to level 1, combining characters are now allowed for
                some languages where they are essential (e.g., Thai, Lao, Hebrew,
                Arabic, Devanagari, Malayalam).

       Level 3  All UCS characters are supported.

       The Unicode 3.0 Standard published by the Unicode Consortium contains
       exactly the UCS Basic Multilingual Plane at implementation level 3, as
       described in ISO 10646-1:2000.  Unicode 3.1 added the supplemental planes
       of ISO 10646-2.  The Unicode standard and technical reports published by
       the Unicode Consortium provide much additional information on the semantics
       and recommended usages of various characters.  They provide guidelines and
       algorithms for editing, sorting, comparing, normalizing, converting and
       displaying Unicode strings.

Unicode Under Linux

       Under GNU/Linux, the C type wchar_t is a signed 32-bit integer type.  Its
       values are always interpreted by the C library as UCS code values (in all
       locales), a convention that is signaled by the GNU C library to
       applications by defining the constant __STDC_ISO_10646__ as specified in
       the ISO C99 standard.

       UCS/Unicode can be used just like ASCII in input/output streams, terminal
       communication, plaintext files, filenames, and environment variables in the
       ASCII compatible UTF-8 multibyte encoding.  To signal the use of UTF-8 as
       the character encoding to all applications, a suitable locale has to be
       selected via environment variables (e.g., "LANG=en_GB.UTF-8").

       The nl_langinfo(CODESET) function returns the name of the selected
       encoding.  Library functions such as wctomb(3) and mbsrtowcs(3) can be used
       to transform the internal wchar_t characters and strings into the system
       character encoding and back and wcwidth(3) tells, how many positions (0-2)
       the cursor is advanced by the output of a character.

       Under Linux, in general only the BMP at implementation level 1 should be
       used at the moment.  Up to two combining characters per base character for
       certain scripts (in particular Thai) are also supported by some UTF-8
       terminal emulators and ISO 10646 fonts (level 2), but in general
       precomposed characters should be preferred where available (Unicode calls
       this Normalization Form C).

Private Area

       In the BMP, the range 0xe000 to 0xf8ff will never be assigned to any
       characters by the standard and is reserved for private usage.  For the
       Linux community, this private area has been subdivided further into the
       range 0xe000 to 0xefff which can be used individually by any end-user and
       the Linux zone in the range 0xf000 to 0xf8ff where extensions are
       coordinated among all Linux users.  The registry of the characters assigned
       to the Linux zone is currently maintained by H. Peter Anvin
       <Peter.Anvin@linux.org>.

Literature

       * Information technology -- Universal Multiple-Octet Coded Character Set
         (UCS) -- Part 1: Architecture and Basic Multilingual Plane.
         International Standard ISO/IEC 10646-1, International Organization for
         Standardization, Geneva, 2000.

         This is the official specification of UCS.  Available as a PDF file on
         CD-ROM from <http://www.iso.ch/>.

       * The Unicode Standard, Version 3.0.  The Unicode Consortium, Addison-Wes-
         ley, Reading, MA, 2000, ISBN 0-201-61633-5.

       * S. Harbison, G. Steele. C: A Reference Manual. Fourth edition, Prentice
         Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3.

         A good reference book about the C programming language.  The fourth edi-
         tion covers the 1994 Amendment 1 to the ISO C90 standard, which adds a
         large number of new C library functions for handling wide and multibyte
         character encodings, but it does not yet cover ISO C99, which improved
         wide and multibyte character support even further.

       * Unicode Technical Reports.
         <http://www.unicode.org/unicode/reports/>

       * Markus Kuhn: UTF-8 and Unicode FAQ for UNIX/Linux.
         <http://www.cl.cam.ac.uk/~mgk25/unicode.html>

         Provides subscription information for the linux-utf8 mailing list, which
         is the best place to look for advice on using Unicode under Linux.

       * Bruno Haible: Unicode HOWTO.
         <ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html>

BUGS top

       When this man page was last revised, the GNU C Library support for UTF-8
       locales was mature and XFree86 support was in an advanced state, but work
       on making applications (most notably editors) suitable for use in UTF-8
       locales was still fully in progress.  Current general UCS support under
       Linux usually provides for CJK double-width characters and sometimes even
       simple overstriking combining characters, but usually does not include sup-
       port for scripts with right-to-left writing direction or ligature substitu-
       tion requirements such as Hebrew, Arabic, or the Indic scripts.  These
       scripts are currently only supported in certain GUI applications (HTML
       viewers, word processors) with sophisticated text rendering engines.

SEE ALSO top

       setlocale(3), charsets(7), utf-8(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-08-05                          UNICODE(7)


units(7) - Linux manual page

NAME | DESCRIPTION | COLOPHON The Linux Programming Interface

UNITS(7)                     Linux Programmer's Manual                    UNITS(7)

NAME top

       units, kilo, kibi, mega, mebi, giga, gibi - decimal and binary prefixes

DESCRIPTION top

Decimal prefixes

       The SI system of units uses prefixes that indicate powers of ten.  A
       kilometer is 1000 meter, and a megawatt is 1000000 watt.  Below the
       standard prefixes.

              Prefix   Name    Value
              y        yocto   10^-24 = 0.000000000000000000000001
              z        zepto   10^-21 = 0.000000000000000000001
              a        atto    10^-18 = 0.000000000000000001
              f        femto   10^-15 = 0.000000000000001
              p        pico    10^-12 = 0.000000000001
              n        nano    10^-9  = 0.000000001
              u        micro   10^-6  = 0.000001
              m        milli   10^-3  = 0.001
              c        centi   10^-2  = 0.01
              d        deci    10^-1  = 0.1
              da       deka    10^ 1  = 10
              h        hecto   10^ 2  = 100
              k        kilo    10^ 3  = 1000
              M        mega    10^ 6  = 1000000
              G        giga    10^ 9  = 1000000000
              T        tera    10^12  = 1000000000000
              P        peta    10^15  = 1000000000000000
              E        exa     10^18  = 1000000000000000000
              Z        zetta   10^21  = 1000000000000000000000
              Y        yotta   10^24  = 1000000000000000000000000

       The symbol for micro is the Greek letter mu, often written u in an ASCII
       context where this Greek letter is not available.  See also

              <http://physics.nist.gov/cuu/Units/prefixes.html>

Binary prefixes

       The binary prefixes resemble the decimal ones, but have an additional 'i'
       (and "Ki" starts with a capital 'K').  The names are formed by taking the
       first syllable of the names of the decimal prefix with roughly the same
       size, followed by "bi" for "binary".

              Prefix   Name   Value
              Ki       kibi   2^10 = 1024
              Mi       mebi   2^20 = 1048576
              Gi       gibi   2^30 = 1073741824
              Ti       tebi   2^40 = 1099511627776
              Pi       pebi   2^50 = 1125899906842624
              Ei       exbi   2^60 = 1152921504606846976

       See also

       <http://physics.nist.gov/cuu/Units/binary.html>

Discussion

       Before these binary prefixes were introduced, it was fairly common to use
       k=1000 and K=1024, just like b=bit, B=byte.  Unfortunately, the M is capi-
       tal already, and cannot be capitalized to indicate binary-ness.

       At first that didn't matter too much, since memory modules and disks came
       in sizes that were powers of two, so everyone knew that in such contexts
       "kilobyte" and "megabyte" meant 1024 and 1048576 bytes, respectively.  What
       originally was a sloppy use of the prefixes "kilo" and "mega" started to
       become regarded as the "real true meaning" when computers were involved.
       But then disk technology changed, and disk sizes became arbitrary numbers.
       After a period of uncertainty all disk manufacturers settled on the stan-
       dard, namely k=1000, M=1000k, G=1000M.

       The situation was messy: in the 14k4 modems, k=1000; in the 1.44MB
       diskettes, M=1024000; etc.  In 1998 the IEC approved the standard that
       defines the binary prefixes given above, enabling people to be precise and
       unambiguous.

       Thus, today, MB = 1000000B and MiB = 1048576B.

       In the free software world programs are slowly being changed to conform.
       When the Linux kernel boots and says

              hda: 120064896 sectors (61473 MB) w/2048KiB Cache

       the MB are megabytes and the KiB are kibibytes.

COLOPHON          top
       This page is part of release 3.45 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                               2012-08-05                            UNITS(7)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


unix(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | ERRORS | VERSIONS | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

UNIX(7)                      Linux Programmer's Manual                     UNIX(7)

NAME top

       unix - sockets for local interprocess communication

SYNOPSIS top

       #include <sys/socket.h>
       #include <sys/un.h>

       unix_socket = socket(AF_UNIX, type, 0);
       error = socketpair(AF_UNIX, type, 0, int *sv);

DESCRIPTION top

       The AF_UNIX (also known as AF_LOCAL) socket family is used to communicate
       between processes on the same machine efficiently.  Traditionally, UNIX
       domain sockets can be either unnamed, or bound to a file system pathname
       (marked as being of type socket).  Linux also supports an abstract
       namespace which is independent of the file system.

       Valid types are: SOCK_STREAM, for a stream-oriented socket and SOCK_DGRAM,
       for a datagram-oriented socket that preserves message boundaries (as on
       most UNIX implementations, UNIX domain datagram sockets are always reliable
       and don't reorder datagrams); and (since Linux 2.6.4) SOCK_SEQPACKET, for a
       connection-oriented socket that preserves message boundaries and delivers
       messages in the order that they were sent.

       UNIX domain sockets support passing file descriptors or process credentials
       to other processes using ancillary data.

Address Format

       A UNIX domain socket address is represented in the following structure:

           #define UNIX_PATH_MAX    108

           struct sockaddr_un {
               sa_family_t sun_family;               /* AF_UNIX */
               char        sun_path[UNIX_PATH_MAX];  /* pathname */
           };

       sun_family always contains AF_UNIX.

       Three types of address are distinguished in this structure:

       *  pathname: a UNIX domain socket can be bound to a null-terminated file
          system pathname using bind(2).  When the address of the socket is
          returned by getsockname(2), getpeername(2), and accept(2), its length is
          offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1, and
          sun_path contains the null-terminated pathname.

       *  unnamed: A stream socket that has not been bound to a pathname using
          bind(2) has no name.  Likewise, the two sockets created by socketpair(2)
          are unnamed.  When the address of an unnamed socket is returned by
          getsockname(2), getpeername(2), and accept(2), its length is
          sizeof(sa_family_t), and sun_path should not be inspected.

       *  abstract: an abstract socket address is distinguished by the fact that
          sun_path[0] is a null byte ('\0').  The socket's address in this
          namespace is given by the additional bytes in sun_path that are covered
          by the specified length of the address structure.  (Null bytes in the
          name have no special significance.)  The name has no connection with
          file system pathnames.  When the address of an abstract socket is
          returned by getsockname(2), getpeername(2), and accept(2), the returned
          addrlen is greater than sizeof(sa_family_t) (i.e., greater than 2), and
          the name of the socket is contained in the first (addrlen -
          sizeof(sa_family_t)) bytes of sun_path.  The abstract socket namespace
          is a nonportable Linux extension.

Socket Options

       For historical reasons these socket options are specified with a SOL_SOCKET
       type even though they are AF_UNIX specific.  They can be set with
       setsockopt(2) and read with getsockopt(2) by specifying SOL_SOCKET as the
       socket family.

       SO_PASSCRED
              Enables the receiving of the credentials of the sending process in
              an ancillary message.  When this option is set and the socket is not
              yet connected a unique name in the abstract namespace will be
              generated automatically.  Expects an integer boolean flag.

Autobind Feature

       If a bind(2) call specifies addrlen as sizeof(sa_family_t), or the
       SO_PASSCRED socket option was specified for a socket that was not
       explicitly bound to an address, then the socket is autobound to an abstract
       address.  The address consists of a null byte followed by 5 bytes in the
       character set [0-9a-f].  Thus, there is a limit of 2^20 autobind addresses.
       (From Linux 2.1.15, when the autobind feature was added, 8 bytes were used,
       and the limit was thus 2^32 autobind addresses.  The change to 5 bytes came
       in Linux 2.3.15.)

Sockets API

       The following paragraphs describe domain-specific details and unsupported
       features of the sockets API for UNIX domain sockets on Linux.

       UNIX domain sockets do not support the transmission of out-of-band data
       (the MSG_OOB flag for send(2) and recv(2)).

       The send(2) MSG_MORE flag is not supported by UNIX domain sockets.

       The use of MSG_TRUNC in the flags argument of recv(2) is not supported by
       UNIX domain sockets.

       The SO_SNDBUF socket option does have an effect for UNIX domain sockets,
       but the SO_RCVBUF option does not.  For datagram sockets, the SO_SNDBUF
       value imposes an upper limit on the size of outgoing datagrams.  This limit
       is calculated as the doubled (see socket(7)) option value less 32 bytes
       used for overhead.

Ancillary Messages

       Ancillary data is sent and received using sendmsg(2) and recvmsg(2).  For
       historical reasons the ancillary message types listed below are specified
       with a SOL_SOCKET type even though they are AF_UNIX specific.  To send them
       set the cmsg_level field of the struct cmsghdr to SOL_SOCKET and the
       cmsg_type field to the type.  For more information see cmsg(3).

       SCM_RIGHTS
              Send or receive a set of open file descriptors from another process.
              The data portion contains an integer array of the file descriptors.
              The passed file descriptors behave as though they have been created
              with dup(2).

       SCM_CREDENTIALS
              Send or receive UNIX credentials.  This can be used for
              authentication.  The credentials are passed as a struct ucred
              ancillary message.  Thus structure is defined in <sys/socket.h> as
              follows:

                  struct ucred {
                      pid_t pid;    /* process ID of the sending process */
                      uid_t uid;    /* user ID of the sending process */
                      gid_t gid;    /* group ID of the sending process */
                  };

              Since glibc 2.8, the _GNU_SOURCE feature test macro must be defined
              (before including any header files) in order to obtain the
              definition of this structure.

              The credentials which the sender specifies are checked by the
              kernel.  A process with effective user ID 0 is allowed to specify
              values that do not match its own.  The sender must specify its own
              process ID (unless it has the capability CAP_SYS_ADMIN), its user
              ID, effective user ID, or saved set-user-ID (unless it has
              CAP_SETUID), and its group ID, effective group ID, or saved set-
              group-ID (unless it has CAP_SETGID).  To receive a struct ucred
              message the SO_PASSCRED option must be enabled on the socket.

Ioctls

       The following ioctl(2) calls return information in value.  The correct
       syntax is:

              int value;
              error = ioctl(unix_socket, ioctl_type, &value);

       ioctl_type can be:

       SIOCINQ
              Returns the amount of queued unread data in the receive buffer.  The
              socket must not be in LISTEN state, otherwise an error (EINVAL) is
              returned.  SIOCINQ is defined in <linux/sockios.h>.  Alternatively,
              you can use the synonymous FIONREAD, defined in <sys/ioctl.h>.

ERRORS top

       EADDRINUSE
              The specified local address is already in use or the file system
              socket object already exists.

       ECONNREFUSED
              The remote address specified by connect(2) was not a listening
              socket.  This error can also occur if the target filename is not a
              socket.

       ECONNRESET
              Remote socket was unexpectedly closed.

       EFAULT User memory address was not valid.

       EINVAL Invalid argument passed.  A common cause is that the value AF_UNIX
              was not specified in the sun_type field of passed addresses, or the
              socket was in an invalid state for the applied operation.

       EISCONN
              connect(2) called on an already connected socket or a target address
              was specified on a connected socket.

       ENOENT The pathname in the remote address specified to connect(2) did not
              exist.

       ENOMEM Out of memory.

       ENOTCONN
              Socket operation needs a target address, but the socket is not
              connected.

       EOPNOTSUPP
              Stream operation called on non-stream oriented socket or tried to
              use the out-of-band data option.

       EPERM  The sender passed invalid credentials in the struct ucred.

       EPIPE  Remote socket was closed on a stream socket.  If enabled, a SIGPIPE
              is sent as well.  This can be avoided by passing the MSG_NOSIGNAL
              flag to sendmsg(2) or recvmsg(2).

       EPROTONOSUPPORT
              Passed protocol is not AF_UNIX.

       EPROTOTYPE
              Remote socket does not match the local socket type (SOCK_DGRAM
              versus SOCK_STREAM)

       ESOCKTNOSUPPORT
              Unknown socket type.

       Other errors can be generated by the generic socket layer or by the file
       system while generating a file system socket object.  See the appropriate
       manual pages for more information.

VERSIONS top

       SCM_CREDENTIALS and the abstract namespace were introduced with Linux 2.2
       and should not be used in portable programs.  (Some BSD-derived systems
       also support credential passing, but the implementation details differ.)

NOTES top

       In the Linux implementation, sockets which are visible in the file system
       honor the permissions of the directory they are in.  Their owner, group and
       their permissions can be changed.  Creation of a new socket will fail if
       the process does not have write and search (execute) permission on the
       directory the socket is created in.  Connecting to the socket object
       requires read/write permission.  This behavior differs from many BSD-
       derived systems which ignore permissions for UNIX domain sockets.  Portable
       programs should not rely on this feature for security.

       Binding to a socket with a filename creates a socket in the file system
       that must be deleted by the caller when it is no longer needed (using
       unlink(2)).  The usual UNIX close-behind semantics apply; the socket can be
       unlinked at any time and will be finally removed from the file system when
       the last reference to it is closed.

       To pass file descriptors or credentials over a SOCK_STREAM, you need to
       send or receive at least one byte of nonancillary data in the same
       sendmsg(2) or recvmsg(2) call.

       UNIX domain stream sockets do not support the notion of out-of-band data.

EXAMPLE top

       See bind(2).

       For an example of the use of SCM_RIGHTS see cmsg(3).

SEE ALSO top

       recvmsg(2), sendmsg(2), socket(2), socketpair(2), cmsg(3), capabilities(7),
       credentials(7), socket(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-10                             UNIX(7)


unlink(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

UNLINK(2)                    Linux Programmer's Manual                   UNLINK(2)

NAME top

       unlink - delete a name and possibly the file it refers to

SYNOPSIS top

       #include <unistd.h>

       int unlink(const char *pathname);

DESCRIPTION top

       unlink() deletes a name from the file system.  If that name was the last
       link to a file and no processes have the file open the file is deleted and
       the space it was using is made available for reuse.

       If the name was the last link to a file but any processes still have the
       file open the file will remain in existence until the last file descriptor
       referring to it is closed.

       If the name referred to a symbolic link the link is removed.

       If the name referred to a socket, fifo or device the name for it is removed
       but processes which have the object open may continue to use it.

RETURN VALUE top

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

ERRORS top

       EACCES Write access to the directory containing pathname is not allowed for
              the process's effective UID, or one of the directories in pathname
              did not allow search permission.  (See also path_resolution(7).)

       EBUSY  The file pathname cannot be unlinked because it is being used by the
              system or another process; for example, it is a mount point or the
              NFS client software created it to represent an active but otherwise
              nameless inode ("NFS silly renamed").

       EFAULT pathname points outside your accessible address space.

       EIO    An I/O error occurred.

       EISDIR pathname refers to a directory.  (This is the non-POSIX value
              returned by Linux since 2.1.132.)

       ELOOP  Too many symbolic links were encountered in translating pathname.

       ENAMETOOLONG
              pathname was too long.

       ENOENT A component in pathname does not exist or is a dangling symbolic
              link, or pathname is empty.

       ENOMEM Insufficient kernel memory was available.

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

       EPERM  The system does not allow unlinking of directories, or unlinking of
              directories requires privileges that the calling process doesn't
              have.  (This is the POSIX prescribed error return; as noted above,
              Linux returns EISDIR for this case.)

       EPERM (Linux only)
              The file system does not allow unlinking of files.

       EPERM or EACCES
              The directory containing pathname has the sticky bit (S_ISVTX) set
              and the process's effective UID is neither the UID of the file to be
              deleted nor that of the directory containing it, and the process is
              not privileged (Linux: does not have the CAP_FOWNER capability).

       EROFS  pathname refers to a file on a read-only file system.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

BUGS top

       Infelicities in the protocol underlying NFS can cause the unexpected
       disappearance of files which are still being used.

SEE ALSO top

       rm(1), chmod(2), link(2), mknod(2), open(2), rename(2), rmdir(2),
       unlinkat(2), mkfifo(3), remove(3), path_resolution(7), symlink(7)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-15                           UNLINK(2)


unlinkat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UNLINKAT(2)                  Linux Programmer's Manual                 UNLINKAT(2)

NAME top

       unlinkat - remove a directory entry relative to a directory file descriptor

SYNOPSIS top

       #include <fcntl.h> /* Definition of AT_* constants */
       #include <unistd.h>

       int unlinkat(int dirfd, const char *pathname, int flags);

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

       unlinkat():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

DESCRIPTION top

       The unlinkat() system call operates in exactly the same way as either
       unlink(2) or rmdir(2) (depending on whether or not flags includes the
       AT_REMOVEDIR flag) except for the differences described in this manual
       page.

       If the pathname given in pathname is relative, then it is interpreted
       relative to the directory referred to by the file descriptor dirfd (rather
       than relative to the current working directory of the calling process, as
       is done by unlink(2) and rmdir(2) for a relative pathname).

       If the pathname given in pathname is relative and dirfd is the special
       value AT_FDCWD, then pathname is interpreted relative to the current
       working directory of the calling process (like unlink(2) and rmdir(2)).

       If the pathname given in pathname is absolute, then dirfd is ignored.

       flags is a bit mask that can either be specified as 0, or by ORing together
       flag values that control the operation of unlinkat().  Currently only one
       such flags is defined:

       AT_REMOVEDIR
              By default, unlinkat() performs the equivalent of unlink(2) on
              pathname.  If the AT_REMOVEDIR flag is specified, then performs the
              equivalent of rmdir(2) on pathname.

RETURN VALUE top

       On success, unlinkat() returns 0.  On error, -1 is returned and errno is
       set to indicate the error.

ERRORS top

       The same errors that occur for unlink(2) and rmdir(2) can also occur for
       unlinkat().  The following additional errors can occur for unlinkat():

       EBADF  dirfd is not a valid file descriptor.

       EINVAL An invalid flag value was specified in flags.

       ENOTDIR
              pathname is relative and dirfd is a file descriptor referring to a
              file other than a directory.

VERSIONS top

       unlinkat() was added to Linux in kernel 2.6.16; library support was added
       to glibc in version 2.4.

CONFORMING TO top

       POSIX.1-2008.  A similar system call exists on Solaris.

NOTES top

       See openat(2) for an explanation of the need for unlinkat().

SEE ALSO top

       openat(2), rmdir(2), unlink(2), path_resolution(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                         UNLINKAT(2)


unlockpt(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

UNLOCKPT(3)                  Linux Programmer's Manual                 UNLOCKPT(3)

NAME top

       unlockpt - unlock a pseudoterminal master/slave pair

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <stdlib.h>

       int unlockpt(int fd);

DESCRIPTION top

       The unlockpt() function unlocks the slave pseudoterminal device
       corresponding to the master pseudoterminal referred to by fd.

       unlockpt() should be called before opening the slave side of a
       pseudoterminal.

RETURN VALUE top

       When successful, unlockpt() returns 0.  Otherwise, it returns -1 and sets
       errno appropriately.

ERRORS top

       EBADF  The fd argument is not a file descriptor open for writing.

       EINVAL The fd argument is not associated with a master pseudoterminal.

VERSIONS top

       unlockpt() is provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

SEE ALSO top

       grantpt(3), posix_openpt(3), ptsname(3), pts(4), pty(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-06-14                         UNLOCKPT(3)


unshare(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UNSHARE(2)                   Linux Programmer's Manual                  UNSHARE(2)

NAME top

       unshare - disassociate parts of the process execution context

SYNOPSIS top

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sched.h>

       int unshare(int flags);

DESCRIPTION top

       unshare() allows a process to disassociate parts of its execution context
       that are currently being shared with other processes.  Part of the
       execution context, such as the mount namespace, is shared implicitly when a
       new process is created using fork(2) or vfork(2), while other parts, such
       as virtual memory, may be shared by explicit request when creating a
       process using clone(2).

       The main use of unshare() is to allow a process to control its shared
       execution context without creating a new process.

       The flags argument is a bit mask that specifies which parts of the
       execution context should be unshared.  This argument is specified by ORing
       together zero or more of the following constants:

       CLONE_FILES
              Reverse the effect of the clone(2) CLONE_FILES flag.  Unshare the
              file descriptor table, so that the calling process no longer shares
              its file descriptors with any other process.

       CLONE_FS
              Reverse the effect of the clone(2) CLONE_FS flag.  Unshare file
              system attributes, so that the calling process no longer shares its
              root directory, current directory, or umask attributes with any
              other process.  chroot(2), chdir(2), or umask(2)

       CLONE_NEWIPC (since Linux 2.6.19)
              This flag has the same effect as the clone(2) CLONE_NEWIPC flag.
              Unshare the System V IPC namespace, so that the calling process has
              a private copy of the System V IPC namespace which is not shared
              with any other process.  Specifying this flag automatically implies
              CLONE_SYSVSEM as well.  Use of CLONE_NEWIPC requires the
              CAP_SYS_ADMIN capability.

       CLONE_NEWNET (since Linux 2.6.24)
              This flag has the same effect as the clone(2) CLONE_NEWNET flag.
              Unshare the network namespace, so that the calling process is moved
              into a new network namespace which is not shared with any previously
              existing process.  CLONE_NEWNET requires the CAP_SYS_ADMIN
              capability.

       CLONE_NEWNS
              This flag has the same effect as the clone(2) CLONE_NEWNS flag.
              Unshare the mount namespace, so that the calling process has a
              private copy of its namespace which is not shared with any other
              process.  Specifying this flag automatically implies CLONE_FS as
              well.  Use of CLONE_NEWNS requires the CAP_SYS_ADMIN capability.

       CLONE_SYSVSEM (since Linux 2.6.26)
              This flag reverses the effect of the clone(2) CLONE_SYSVSEM flag.
              Unshare System V semaphore undo values, so that the calling process
              has a private copy which is not shared with any other process.  Use
              of CLONE_SYSVSEM requires the CAP_SYS_ADMIN capability.

       CLONE_NEWUTS (since Linux 2.6.19)
              This flag has the same effect as the clone(2) CLONE_NEWUTS flag.
              Unshare the UTS IPC namespace, so that the calling process has a
              private copy of the UTS namespace which is not shared with any other
              process.  Use of CLONE_NEWUTS requires the CAP_SYS_ADMIN capability.

       If flags is specified as zero, then unshare() is a no-op; no changes are
       made to the calling process's execution context.

RETURN VALUE top

       On success, zero returned.  On failure, -1 is returned and errno is set to
       indicate the error.

ERRORS top

       EINVAL An invalid bit was specified in flags.

       ENOMEM Cannot allocate sufficient memory to copy parts of caller's context
              that need to be unshared.

       EPERM  The calling process did not have the required privileges for this
              operation.

VERSIONS top

       The unshare() system call was added to Linux in kernel 2.6.16.

CONFORMING TO top

       The unshare() system call is Linux-specific.

NOTES top

       Not all of the process attributes that can be shared when a new process is
       created using clone(2) can be unshared using unshare().  In particular, as
       at kernel 2.6.16, unshare() does not implement flags that reverse the
       effects of CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, or CLONE_VM.  Such
       functionality may be added in the future, if required.

SEE ALSO top

       clone(2), fork(2), vfork(2)

       Documentation/unshare.txt in the Linux kernel source tree

COLOPHON top

       This page is part of release 3.45 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                               2010-10-30                          UNSHARE(2)


uri(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

URI(7)                       Linux Programmer's Manual                      URI(7)

NAME top

       uri, url, urn - uniform resource identifier (URI), including a URL or URN

SYNOPSIS top

       URI = [ absoluteURI | relativeURI ] [ "#" fragment ]

       absoluteURI = scheme ":" ( hierarchical_part | opaque_part )

       relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ]

       scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
                  "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...

       hierarchical_part = ( net_path | absolute_path ) [ "?" query ]

       net_path = "//" authority [ absolute_path ]

       absolute_path = "/"  path_segments

       relative_path = relative_segment [ absolute_path ]

DESCRIPTION top

       A Uniform Resource Identifier (URI) is a short string of characters
       identifying an abstract or physical resource (for example, a web page).  A
       Uniform Resource Locator (URL) is a URI that identifies a resource through
       its primary access mechanism (e.g., its network "location"), rather than by
       name or some other attribute of that resource.  A Uniform Resource Name
       (URN) is a URI that must remain globally unique and persistent even when
       the resource ceases to exist or becomes unavailable.

       URIs are the standard way to name hypertext link destinations for tools
       such as web browsers.  The string "http://www.kernelnotes.org" is a URL
       (and thus it is also a URI).  Many people use the term URL loosely as a
       synonym for URI (though technically URLs are a subset of URIs).

       URIs can be absolute or relative.  An absolute identifier refers to a
       resource independent of context, while a relative identifier refers to a
       resource by describing the difference from the current context.  Within a
       relative path reference, the complete path segments "." and ".." have
       special meanings: "the current hierarchy level" and "the level above this
       hierarchy level", respectively, just like they do in UNIX-like systems.  A
       path segment which contains a colon character can't be used as the first
       segment of a relative URI path (e.g., "this:that"), because it would be
       mistaken for a scheme name; precede such segments with ./ (e.g.,
       "./this:that").  Note that descendants of MS-DOS (e.g., Microsoft Windows)
       replace devicename colons with the vertical bar ("|") in URIs, so "C:"
       becomes "C|".

       A fragment identifier, if included, refers to a particular named portion
       (fragment) of a resource; text after a '#' identifies the fragment.  A URI
       beginning with '#' refers to that fragment in the current resource.

Usage

       There are many different URI schemes, each with specific additional rules
       and meanings, but they are intentionally made to be as similar as possible.
       For example, many URL schemes permit the authority to be the following
       format, called here an ip_server (square brackets show what's optional):

       ip_server = [user [ : password ] @ ] host [ : port]

       This format allows you to optionally insert a username, a user plus
       password, and/or a port number.  The host is the name of the host computer,
       either its name as determined by DNS or an IP address (numbers separated by
       periods).  Thus the URI <http://fred:fredpassword@xyz.com:8080/> logs into
       a web server on host xyz.com as fred (using fredpassword) using port 8080.
       Avoid including a password in a URI if possible because of the many
       security risks of having a password written down.  If the URL supplies a
       username but no password, and the remote server requests a password, the
       program interpreting the URL should request one from the user.

       Here are some of the most common schemes in use on UNIX-like systems that
       are understood by many tools.  Note that many tools using URIs also have
       internal schemes or specialized schemes; see those tools' documentation for
       information on those schemes.

       http - Web (HTTP) server

       http://ip_server/path
       http://ip_server/path?query

       This is a URL accessing a web (HTTP) server.  The default port is 80.  If
       the path refers to a directory, the web server will choose what to return;
       usually if there is a file named "index.html" or "index.htm" its content is
       returned, otherwise, a list of the files in the current directory (with
       appropriate links) is generated and returned.  An example is
       <http://lwn.net>.

       A query can be given in the archaic "isindex" format, consisting of a word
       or phrase and not including an equal sign (=).  A query can also be in the
       longer "GET" format, which has one or more query entries of the form
       key=value separated by the ampersand character (&).  Note that key can be
       repeated more than once, though it's up to the web server and its
       application programs to determine if there's any meaning to that.  There is
       an unfortunate interaction with HTML/XML/SGML and the GET query format;
       when such URIs with more than one key are embedded in SGML/XML documents
       (including HTML), the ampersand (&) has to be rewritten as &amp;.  Note
       that not all queries use this format; larger forms may be too long to store
       as a URI, so they use a different interaction mechanism (called POST) which
       does not include the data in the URI.  See the Common Gateway Interface
       specification at <http://www.w3.org/CGI> for more information.

       ftp - File Transfer Protocol (FTP)

       ftp://ip_server/path

       This is a URL accessing a file through the file transfer protocol (FTP).
       The default port (for control) is 21.  If no username is included, the
       username "anonymous" is supplied, and in that case many clients provide as
       the password the requestor's Internet email address.  An example is
       <ftp://ftp.is.co.za/rfc/rfc1808.txt>.

       gopher - Gopher server

       gopher://ip_server/gophertype selector
       gopher://ip_server/gophertype selector%09search
       gopher://ip_server/gophertype selector%09search%09gopher+_string

       The default gopher port is 70.  gophertype is a single-character field to
       denote the Gopher type of the resource to which the URL refers.  The entire
       path may also be empty, in which case the delimiting "/" is also optional
       and the gophertype defaults to "1".

       selector is the Gopher selector string.  In the Gopher protocol, Gopher
       selector strings are a sequence of octets which may contain any octets
       except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII char-
       acter LF), and 0D (US-ASCII character CR).

       mailto - Email address

       mailto:email-address

       This is an email address, usually of the form name@hostname.  See
       mailaddr(7) for more information on the correct format of an email address.
       Note that any % character must be rewritten as %25.  An example is
       <mailto:dwheeler@dwheeler.com>.

       news - Newsgroup or News message

       news:newsgroup-name
       news:message-id

       A newsgroup-name is a period-delimited hierarchical name, such as
       "comp.infosystems.www.misc".  If <newsgroup-name> is "*" (as in <news:*>),
       it is used to refer to "all available news groups".  An example is
       <news:comp.lang.ada>.

       A message-id corresponds to the Message-ID of IETF RFC 1036,
       <http://www.ietf.org/rfc/rfc1036.txt> without the enclosing "<" and ">"; it
       takes the form unique@full_domain_name.  A message identifier may be dis-
       tinguished from a news group name by the presence of the "@" character.

       telnet - Telnet login

       telnet://ip_server/

       The Telnet URL scheme is used to designate interactive text services that
       may be accessed by the Telnet protocol.  The final "/" character may be
       omitted.  The default port is 23.  An example is <tel-
       net://melvyl.ucop.edu/>.

       file - Normal file

       file://ip_server/path_segments
       file:path_segments

       This represents a file or directory accessible locally.  As a special case,
       host can be the string "localhost" or the empty string; this is interpreted
       as "the machine from which the URL is being interpreted".  If the path is
       to a directory, the viewer should display the directory's contents with
       links to each containee; not all viewers currently do this.  KDE supports
       generated files through the URL <file:/cgi-bin>.  If the given file isn't
       found, browser writers may want to try to expand the filename via filename
       globbing (see glob(7) and glob(3)).

       The second format (e.g., <file:/etc/passwd>) is a correct format for refer-
       ring to a local file.  However, older standards did not permit this format,
       and some programs don't recognize this as a URI.  A more portable syntax is
       to use an empty string as the server name, for example,
       <file:///etc/passwd>; this form does the same thing and is easily recog-
       nized by pattern matchers and older programs as a URI.  Note that if you
       really mean to say "start from the current location," don't specify the
       scheme at all; use a relative address like <../test.txt>, which has the
       side-effect of being scheme-independent.  An example of this scheme is
       <file:///etc/passwd>.

       man - Man page documentation

       man:command-name
       man:command-name(section)

       This refers to local online manual (man) reference pages.  The command name
       can optionally be followed by a parenthesis and section number; see man(7)
       for more information on the meaning of the section numbers.  This URI
       scheme is unique to UNIX-like systems (such as Linux) and is not currently
       registered by the IETF.  An example is <man:ls(1)>.

       info - Info page documentation

       info:virtual-filename
       info:virtual-filename#nodename
       info:(virtual-filename)
       info:(virtual-filename)nodename

       This scheme refers to online info reference pages (generated from texinfo
       files), a documentation format used by programs such as the GNU tools.
       This URI scheme is unique to UNIX-like systems (such as Linux) and is not
       currently registered by the IETF.  As of this writing, GNOME and KDE differ
       in their URI syntax and do not accept the other's syntax.  The first two
       formats are the GNOME format; in nodenames all spaces are written as under-
       scores.  The second two formats are the KDE format; spaces in nodenames
       must be written as spaces, even though this is forbidden by the URI stan-
       dards.  It's hoped that in the future most tools will understand all of
       these formats and will always accept underscores for spaces in nodenames.
       In both GNOME and KDE, if the form without the nodename is used the node-
       name is assumed to be "Top".  Examples of the GNOME format are <info:gcc>
       and <info:gcc#G++_and_GCC>.  Examples of the KDE format are <info:(gcc)>
       and <info:(gcc)G++ and GCC>.

       whatis - Documentation search

       whatis:string

       This scheme searches the database of short (one-line) descriptions of com-
       mands and returns a list of descriptions containing that string.  Only com-
       plete word matches are returned.  See whatis(1).  This URI scheme is unique
       to UNIX-like systems (such as Linux) and is not currently registered by the
       IETF.

       ghelp - GNOME help documentation

       ghelp:name-of-application

       This loads GNOME help for the given application.  Note that not much docu-
       mentation currently exists in this format.

       ldap - Lightweight Directory Access Protocol

       ldap://hostport
       ldap://hostport/
       ldap://hostport/dn
       ldap://hostport/dn?attributes
       ldap://hostport/dn?attributes?scope
       ldap://hostport/dn?attributes?scope?filter
       ldap://hostport/dn?attributes?scope?filter?extensions

       This scheme supports queries to the Lightweight Directory Access Protocol
       (LDAP), a protocol for querying a set of servers for hierarchically orga-
       nized information (such as people and computing resources).  See RFC 2255
       <http://www.ietf.org/rfc/rfc2255.txt> for more information on the LDAP URL
       scheme.  The components of this URL are:

       hostport    the LDAP server to query, written as a hostname optionally fol-
                   lowed by a colon and the port number.  The default LDAP port is
                   TCP port 389.  If empty, the client determines which the LDAP
                   server to use.

       dn          the LDAP Distinguished Name, which identifies the base object
                   of the LDAP search (see RFC 2253 <http://www.ietf.org/rfc
                   /rfc2253.txt> section 3).

       attributes  a comma-separated list of attributes to be returned; see
                   RFC 2251 section 4.1.5.  If omitted, all attributes should be
                   returned.

       scope       specifies the scope of the search, which can be one of "base"
                   (for a base object search), "one" (for a one-level search), or
                   "sub" (for a subtree search).  If scope is omitted, "base" is
                   assumed.

       filter      specifies the search filter (subset of entries to return).  If
                   omitted, all entries should be returned.  See RFC 2254
                   <http://www.ietf.org/rfc/rfc2254.txt> section 4.

       extensions  a comma-separated list of type=value pairs, where the =value
                   portion may be omitted for options not requiring it.  An exten-
                   sion prefixed with a '!' is critical (must be supported to be
                   valid), otherwise it is noncritical (optional).

       LDAP queries are easiest to explain by example.  Here's a query that asks
       ldap.itd.umich.edu for information about the University of Michigan in the
       U.S.:

       ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US

       To just get its postal address attribute, request:

       ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress

       To ask a host.com at port 6666 for information about the person with common
       name (cn) "Babs Jensen" at University of Michigan, request:

       ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)

       wais - Wide Area Information Servers

       wais://hostport/database
       wais://hostport/database?search
       wais://hostport/database/wtype/wpath

       This scheme designates a WAIS database, search, or document (see IETF
       RFC 1625 <http://www.ietf.org/rfc/rfc1625.txt> for more information on
       WAIS).  Hostport is the hostname, optionally followed by a colon and port
       number (the default port number is 210).

       The first form designates a WAIS database for searching.  The second form
       designates a particular search of the WAIS database database.  The third
       form designates a particular document within a WAIS database to be
       retrieved.  wtype is the WAIS designation of the type of the object and
       wpath is the WAIS document-id.

       other schemes

       There are many other URI schemes.  Most tools that accept URIs support a
       set of internal URIs (e.g., Mozilla has the about: scheme for internal
       information, and the GNOME help browser has the toc: scheme for various
       starting locations).  There are many schemes that have been defined but are
       not as widely used at the current time (e.g., prospero).  The nntp: scheme
       is deprecated in favor of the news: scheme.  URNs are to be supported by
       the urn: scheme, with a hierarchical name space (e.g., urn:ietf:... would
       identify IETF documents); at this time URNs are not widely implemented.
       Not all tools support all schemes.

Character Encoding

       URIs use a limited number of characters so that they can be typed in and
       used in a variety of situations.

       The following characters are reserved, that is, they may appear in a URI
       but their use is limited to their reserved purpose (conflicting data must
       be escaped before forming the URI):

                 ; / ? : @ & = + $ ,

       Unreserved characters may be included in a URI.  Unreserved characters
       include upper and lower case English letters, decimal digits, and the fol-
       lowing limited set of punctuation marks and symbols:

               - _ . ! ~ * ' ( )

       All other characters must be escaped.  An escaped octet is encoded as a
       character triplet, consisting of the percent character "%" followed by the
       two hexadecimal digits representing the octet code (you can use upper or
       lower case letters for the hexadecimal digits).  For example, a blank space
       must be escaped as "%20", a tab character as "%09", and the "&" as "%26".
       Because the percent "%" character always has the reserved purpose of being
       the escape indicator, it must be escaped as "%25".  It is common practice
       to escape space characters as the plus symbol (+) in query text; this prac-
       tice isn't uniformly defined in the relevant RFCs (which recommend %20
       instead) but any tool accepting URIs with query text should be prepared for
       them.  A URI is always shown in its "escaped" form.

       Unreserved characters can be escaped without changing the semantics of the
       URI, but this should not be done unless the URI is being used in a context
       that does not allow the unescaped character to appear.  For example, "%7e"
       is sometimes used instead of "~" in an HTTP URL path, but the two are
       equivalent for an HTTP URL.

       For URIs which must handle characters outside the US ASCII character set,
       the HTML 4.01 specification (section B.2) and IETF RFC 2718 (section 2.2.5)
       recommend the following approach:

       1.  translate the character sequences into UTF-8 (IETF RFC 2279)--see
           utf-8(7)--and then

       2.  use the URI escaping mechanism, that is, use the %HH encoding for
           unsafe octets.

Writing a URI

       When written, URIs should be placed inside double quotes (e.g.,
       "http://www.kernelnotes.org"), enclosed in angle brackets (e.g.,
       <http://lwn.net>), or placed on a line by themselves.  A warning for those
       who use double-quotes: never move extraneous punctuation (such as the
       period ending a sentence or the comma in a list) inside a URI, since this
       will change the value of the URI.  Instead, use angle brackets instead, or
       switch to a quoting system that never includes extraneous characters inside
       quotation marks.  This latter system, called the 'new' or 'logical' quoting
       system by "Hart's Rules" and the "Oxford Dictionary for Writers and Edi-
       tors", is preferred practice in Great Britain and hackers worldwide (see
       the Jargon File's section on Hacker Writing Style, <http://www.fwi.uva.nl
       /~mes/jargon/h/HackerWritingStyle.html>, for more information).  Older doc-
       uments suggested inserting the prefix "URL:" just before the URI, but this
       form has never caught on.

       The URI syntax was designed to be unambiguous.  However, as URIs have
       become commonplace, traditional media (television, radio, newspapers, bill-
       boards, etc.) have increasingly used abbreviated URI references consisting
       of only the authority and path portions of the identified resource (e.g.,
       <www.w3.org/Addressing>).  Such references are primarily intended for human
       interpretation rather than machine, with the assumption that context-based
       heuristics are sufficient to complete the URI (e.g., hostnames beginning
       with "www" are likely to have a URI prefix of "http://" and hostnames
       beginning with "ftp" likely to have a prefix of "ftp://").  Many client
       implementations heuristically resolve these references.  Such heuristics
       may change over time, particularly when new schemes are introduced.  Since
       an abbreviated URI has the same syntax as a relative URL path, abbreviated
       URI references cannot be used where relative URIs are permitted, and can
       only be used when there is no defined base (such as in dialog boxes).
       Don't use abbreviated URIs as hypertext links inside a document; use the
       standard format as described here.

CONFORMING TO top

       (IETF RFC 2396) <http://www.ietf.org/rfc/rfc2396.txt>, (HTML 4.0)
       <http://www.w3.org/TR/REC-html40>.

NOTES top

       Any tool accepting URIs (e.g., a web browser) on a Linux system should be
       able to handle (directly or indirectly) all of the schemes described here,
       including the man: and info: schemes.  Handling them by invoking some other
       program is fine and in fact encouraged.

       Technically the fragment isn't part of the URI.

       For information on how to embed URIs (including URLs) in a data format, see
       documentation on that format.  HTML uses the format <A HREF="uri"> text
       </A>.  Texinfo files use the format @uref{uri}.  Man and mdoc have the
       recently added UR macro, or just include the URI in the text (viewers
       should be able to detect :// as part of a URI).

       The GNOME and KDE desktop environments currently vary in the URIs they
       accept, in particular in their respective help browsers.  To list man
       pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and to list info
       pages, GNOME uses <toc:info> while KDE uses <info:(dir)> (the author of
       this man page prefers the KDE approach here, though a more regular format
       would be even better).  In general, KDE uses <file:/cgi-bin/> as a prefix
       to a set of generated files.  KDE prefers documentation in HTML, accessed
       via the <file:/cgi-bin/helpindex>.  GNOME prefers the ghelp scheme to store
       and find documentation.  Neither browser handles file: references to direc-
       tories at the time of this writing, making it difficult to refer to an
       entire directory with a browsable URI.  As noted above, these environments
       differ in how they handle the info: scheme, probably the most important
       variation.  It is expected that GNOME and KDE will converge to common URI
       formats, and a future version of this man page will describe the converged
       result.  Efforts to aid this convergence are encouraged.

Security

       A URI does not in itself pose a security threat.  There is no general guar-
       antee that a URL, which at one time located a given resource, will continue
       to do so.  Nor is there any guarantee that a URL will not locate a differ-
       ent resource at some later point in time; such a guarantee can only be
       obtained from the person(s) controlling that namespace and the resource in
       question.

       It is sometimes possible to construct a URL such that an attempt to perform
       a seemingly harmless operation, such as the retrieval of an entity associ-
       ated with the resource, will in fact cause a possibly damaging remote oper-
       ation to occur.  The unsafe URL is typically constructed by specifying a
       port number other than that reserved for the network protocol in question.
       The client unwittingly contacts a site that is in fact running a different
       protocol.  The content of the URL contains instructions that, when inter-
       preted according to this other protocol, cause an unexpected operation.  An
       example has been the use of a gopher URL to cause an unintended or imper-
       sonating message to be sent via a SMTP server.

       Caution should be used when using any URL that specifies a port number
       other than the default for the protocol, especially when it is a number
       within the reserved space.

       Care should be taken when a URI contains escaped delimiters for a given
       protocol (for example, CR and LF characters for telnet protocols) that
       these are not unescaped before transmission.  This might violate the proto-
       col, but avoids the potential for such characters to be used to simulate an
       extra operation or parameter in that protocol, which might lead to an unex-
       pected and possibly harmful remote operation to be performed.

       It is clearly unwise to use a URI that contains a password which is
       intended to be secret.  In particular, the use of a password within the
       "userinfo" component of a URI is strongly recommended against except in
       those rare cases where the "password" parameter is intended to be public.

BUGS top

       Documentation may be placed in a variety of locations, so there currently
       isn't a good URI scheme for general online documentation in arbitrary for-
       mats.  References of the form <file:///usr/doc/ZZZ> don't work because dif-
       ferent distributions and local installation requirements may place the
       files in different directories (it may be in /usr/doc, or /usr/local/doc,
       or /usr/share, or somewhere else).  Also, the directory ZZZ usually changes
       when a version changes (though filename globbing could partially overcome
       this).  Finally, using the file: scheme doesn't easily support people who
       dynamically load documentation from the Internet (instead of loading the
       files onto a local file system).  A future URI scheme may be added (e.g.,
       "userdoc:") to permit programs to include cross-references to more detailed
       documentation without having to know the exact location of that documenta-
       tion.  Alternatively, a future version of the file-system specification may
       specify file locations sufficiently so that the file: scheme will be able
       to locate documentation.

       Many programs and file formats don't include a way to incorporate or imple-
       ment links using URIs.

       Many programs can't handle all of these different URI formats; there should
       be a standard mechanism to load an arbitrary URI that automatically detects
       the users' environment (e.g., text or graphics, desktop environment, local
       user preferences, and currently executing tools) and invokes the right tool
       for any URI.

SEE ALSO top

       lynx(1), man2html(1), mailaddr(7), utf-8(7)

       IETF RFC 2255 <http://www.ietf.org/rfc/rfc2255.txt>

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                              URI(7)


uselib(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

USELIB(2)                    Linux Programmer's Manual                   USELIB(2)

NAME top

       uselib - load shared library

SYNOPSIS top

       #include <unistd.h>

       int uselib(const char *library);

DESCRIPTION top

       The system call uselib() serves to load a shared library to be used by the
       calling process.  It is given a pathname.  The address where to load is
       found in the library itself.  The library can have any recognized binary
       format.

RETURN VALUE top

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

ERRORS top

       In addition to all of the error codes returned by open(2) and mmap(2), the
       following may also be returned:

       EACCES The library specified by library does not have read or execute
              permission, or the caller does not have search permission for one of
              the directories in the path prefix.  (See also path_resolution(7).)

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

       ENOEXEC
              The file specified by library is not an executable of known type,
              e.g., does not have the correct magic numbers.

CONFORMING TO top

       uselib() is Linux-specific, and should not be used in programs intended to
       be portable.

NOTES top

       uselib() was used by early libc startup code to load the shared libraries
       with names found in an array of names in the binary.

       Since libc 4.3.2, startup code tries to prefix these names with "/usr/lib",
       "/lib" and "" before giving up.  In libc 4.3.4 and later these names are
       looked for in the directories found in LD_LIBRARY_PATH, and if not found
       there, prefixes "/usr/lib", "/lib" and "/" are tried.

       From libc 4.4.4 on only the library "/lib/ld.so" is loaded, so that this
       dynamic library can load the remaining libraries needed (again using this
       call).  This is also the state of affairs in libc5.

       glibc2 does not use this call.

SEE ALSO top

       ar(1), gcc(1), ld(1), ldd(1), mmap(2), open(2), dlopen(3), capabilities(7),
       ld.so(8)

COLOPHON top

       This page is part of release 3.45 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                               2005-01-09                           USELIB(2)


usleep(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

USLEEP(3)                    Linux Programmer's Manual                   USLEEP(3)

NAME top

       usleep - suspend execution for microsecond intervals

SYNOPSIS top

       #include <unistd.h>

       int usleep(useconds_t usec);

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

       usleep():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

       The usleep() function suspends execution of the calling thread for (at
       least) usec microseconds.  The sleep may be lengthened slightly by any
       system activity or by the time spent processing the call or by the
       granularity of system timers.

RETURN VALUE top

       0 on success, -1 on error.

ERRORS top

       EINTR  Interrupted by a signal; see signal(7).

       EINVAL usec is not smaller than 1000000.  (On systems where that is
              considered an error.)

CONFORMING TO top

       4.3BSD, POSIX.1-2001.  POSIX.1-2001 declares this function obsolete; use
       nanosleep(2) instead.  POSIX.1-2008 removes the specification of usleep().

       On the original BSD implementation, and in glibc before version 2.2.2, the
       return type of this function is void.  The POSIX version returns int, and
       this is also the prototype used since glibc 2.2.2.

       Only the EINVAL error return is documented by SUSv2 and POSIX.1-2001.

NOTES top

       The type useconds_t is an unsigned integer type capable of holding integers
       in the range [0,1000000].  Programs will be more portable if they never
       mention this type explicitly.  Use

           #include <unistd.h>
           ...
               unsigned int usecs;
           ...
               usleep(usecs);

       The interaction of this function with the SIGALRM signal, and with other
       timer functions such as alarm(2), sleep(3), nanosleep(2), setitimer(2),
       timer_create(2), timer_delete(2), timer_getoverrun(2), timer_gettime(2),
       timer_settime(2), ualarm(3) is unspecified.

SEE ALSO top

       alarm(2), getitimer(2), nanosleep(2), select(2), setitimer(2), sleep(3),
       ualarm(3), time(7)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-12-03                           USLEEP(3)


ustat(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

USTAT(2)                     Linux Programmer's Manual                    USTAT(2)

NAME top

       ustat - get file system statistics

SYNOPSIS top

       #include <sys/types.h>
       #include <unistd.h>    /* libc[45] */
       #include <ustat.h>     /* glibc2 */

       int ustat(dev_t dev, struct ustat *ubuf);

DESCRIPTION top

       ustat() returns information about a mounted file system.  dev is a device
       number identifying a device containing a mounted file system.  ubuf is a
       pointer to a ustat structure that contains the following members:

           daddr_t f_tfree;      /* Total free blocks */
           ino_t   f_tinode;     /* Number of free inodes */
           char    f_fname[6];   /* Filsys name */
           char    f_fpack[6];   /* Filsys pack name */

       The last two fields, f_fname and f_fpack, are not implemented and will
       always be filled with null bytes ('\0').

RETURN VALUE top

       On success, zero is returned and the ustat structure pointed to by ubuf
       will be filled in.  On error, -1 is returned, and errno is set
       appropriately.

ERRORS top

       EFAULT ubuf points outside of your accessible address space.

       EINVAL dev does not refer to a device containing a mounted file system.

       ENOSYS The mounted file system referenced by dev does not support this
              operation, or any version of Linux before 1.3.16.

CONFORMING TO top

       SVr4.

NOTES top

       ustat() is deprecated and has only been provided for compatibility.  All
       new programs should use statfs(2) instead.

HP-UX Notes

       The HP-UX version of the ustat structure has an additional field,
       f_blksize, that is unknown elsewhere.  HP-UX warns: For some file systems,
       the number of free inodes does not change.  Such file systems will return
       -1 in the field f_tinode.  For some file systems, inodes are dynamically
       allocated.  Such file systems will return the current number of free
       inodes.

SEE ALSO top

       stat(2), statfs(2)

COLOPHON top

       This page is part of release 3.45 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                               2003-08-04                            USTAT(2)


utf-8(7) - Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

UTF-8(7)                     Linux Programmer's Manual                    UTF-8(7)

NAME top

       UTF-8 - an ASCII compatible multibyte Unicode encoding

DESCRIPTION top

       The Unicode 3.0 character set occupies a 16-bit code space.  The most
       obvious Unicode encoding (known as UCS-2) consists of a sequence of 16-bit
       words.  Such strings can contain as parts of many 16-bit characters bytes
       like '\0' or '/' which have a special meaning in filenames and other C
       library function arguments.  In addition, the majority of UNIX tools
       expects ASCII files and can't read 16-bit words as characters without major
       modifications.  For these reasons, UCS-2 is not a suitable external
       encoding of Unicode in filenames, text files, environment variables, and so
       on.  The ISO 10646 Universal Character Set (UCS), a superset of Unicode,
       occupies even a 31-bit code space and the obvious UCS-4 encoding for it (a
       sequence of 32-bit words) has the same problems.

       The UTF-8 encoding of Unicode and UCS does not have these problems and is
       the common way in which Unicode is used on UNIX-style operating systems.

Properties

       The UTF-8 encoding has the following nice properties:

       * UCS characters 0x00000000 to 0x0000007f (the classic US-ASCII characters)
         are encoded simply as bytes 0x00 to 0x7f (ASCII compatibility).  This
         means that files and strings which contain only 7-bit ASCII characters
         have the same encoding under both ASCII and UTF-8.

       * All UCS characters greater than 0x7f are encoded as a multibyte sequence
         consisting only of bytes in the range 0x80 to 0xfd, so no ASCII byte can
         appear as part of another character and there are no problems with, for
         example,  '\0' or '/'.

       * The lexicographic sorting order of UCS-4 strings is preserved.

       * All possible 2^31 UCS codes can be encoded using UTF-8.

       * The bytes 0xc0, 0xc1, 0xfe and 0xff are never used in the UTF-8 encoding.

       * The first byte of a multibyte sequence which represents a single non-
         ASCII UCS character is always in the range 0xc2 to 0xfd and indicates how
         long this multibyte sequence is.  All further bytes in a multibyte
         sequence are in the range 0x80 to 0xbf.  This allows easy
         resynchronization and makes the encoding stateless and robust against
         missing bytes.

       * UTF-8 encoded UCS characters may be up to six bytes long, however the
         Unicode standard specifies no characters above 0x10ffff, so Unicode
         characters can only be up to four bytes long in UTF-8.

Encoding

       The following byte sequences are used to represent a character.  The
       sequence to be used depends on the UCS code number of the character:

       0x00000000 - 0x0000007F:
           0xxxxxxx

       0x00000080 - 0x000007FF:
           110xxxxx 10xxxxxx

       0x00000800 - 0x0000FFFF:
           1110xxxx 10xxxxxx 10xxxxxx

       0x00010000 - 0x001FFFFF:
           11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

       0x00200000 - 0x03FFFFFF:
           111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

       0x04000000 - 0x7FFFFFFF:
           1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

       The xxx bit positions are filled with the bits of the character code number
       in binary representation.  Only the shortest possible multibyte sequence
       which can represent the code number of the character can be used.

       The UCS code values 0xd800-0xdfff (UTF-16 surrogates) as well as 0xfffe and
       0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams.

Example

       The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded in
       UTF-8 as

              11000010 10101001 = 0xc2 0xa9

       and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is
       encoded as:

              11100010 10001001 10100000 = 0xe2 0x89 0xa0

Application Notes

       Users have to select a UTF-8 locale, for example with

              export LANG=en_GB.UTF-8

       in order to activate the UTF-8 support in applications.

       Application software that has to be aware of the used character encoding
       should always set the locale with for example

              setlocale(LC_CTYPE, "")

       and programmers can then test the expression

              strcmp(nl_langinfo(CODESET), "UTF-8") == 0

       to determine whether a UTF-8 locale has been selected and whether therefore
       all plaintext standard input and output, terminal communication, plaintext
       file content, filenames and environment variables are encoded in UTF-8.

       Programmers accustomed to single-byte encodings such as US-ASCII or ISO
       8859 have to be aware that two assumptions made so far are no longer valid
       in UTF-8 locales.  Firstly, a single byte does not necessarily correspond
       any more to a single character.  Secondly, since modern terminal emulators
       in UTF-8 mode also support Chinese, Japanese, and Korean double-width
       characters as well as nonspacing combining characters, outputting a single
       character does not necessarily advance the cursor by one position as it did
       in ASCII.  Library functions such as mbsrtowcs(3) and wcswidth(3) should be
       used today to count characters and cursor positions.

       The official ESC sequence to switch from an ISO 2022 encoding scheme (as
       used for instance by VT100 terminals) to UTF-8 is ESC % G ("\x1b%G").  The
       corresponding return sequence from UTF-8 to ISO 2022 is ESC % @ ("\x1b%@").
       Other ISO 2022 sequences (such as for switching the G0 and G1 sets) are not
       applicable in UTF-8 mode.

       It can be hoped that in the foreseeable future, UTF-8 will replace ASCII
       and ISO 8859 at all levels as the common character encoding on POSIX
       systems, leading to a significantly richer environment for handling plain
       text.

Security

       The Unicode and UCS standards require that producers of UTF-8 shall use the
       shortest form possible, for example, producing a two-byte sequence with
       first byte 0xc0 is nonconforming.  Unicode 3.1 has added the requirement
       that conforming programs must not accept non-shortest forms in their input.
       This is for security reasons: if user input is checked for possible
       security violations, a program might check only for the ASCII version of
       "/../" or ";" or NUL and overlook that there are many non-ASCII ways to
       represent these things in a non-shortest UTF-8 encoding.

Standards

       ISO/IEC 10646-1:2000, Unicode 3.1, RFC 3629, Plan 9.

SEE ALSO top

       nl_langinfo(3), setlocale(3), charsets(7), unicode(7)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2012-04-30                            UTF-8(7)


utime(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

UTIME(2)                     Linux Programmer's Manual                    UTIME(2)

NAME top

       utime, utimes - change file last access and modification times

SYNOPSIS top

       #include <sys/types.h>
       #include <utime.h>

       int utime(const char *filename, const struct utimbuf *times);

       #include <sys/time.h>

       int utimes(const char *filename, const struct timeval times[2]);

DESCRIPTION top

       The utime() system call changes the access and modification times of the
       inode specified by filename to the actime and modtime fields of times
       respectively.

       If times is NULL, then the access and modification times of the file are
       set to the current time.

       Changing timestamps is permitted when: either the process has appropriate
       privileges, or the effective user ID equals the user ID of the file, or
       times is NULL and the process has write permission for the file.

       The utimbuf structure is:

           struct utimbuf {
               time_t actime;       /* access time */
               time_t modtime;      /* modification time */
           };

       The utime() system call allows specification of timestamps with a
       resolution of 1 second.

       The utimes() system call is similar, but the times argument refers to an
       array rather than a structure.  The elements of this array are timeval
       structures, which allow a precision of 1 microsecond for specifying
       timestamps.  The timeval structure is:

           struct timeval {
               long tv_sec;        /* seconds */
               long tv_usec;       /* microseconds */
           };

       times[0] specifies the new access time, and times[1] specifies the new
       modification time.  If times is NULL, then analogously to utime(), the
       access and modification times of the file are set to the current time.

RETURN VALUE top

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

ERRORS top

       EACCES Search permission is denied for one of the directories in the path
              prefix of path (see also path_resolution(7)).

       EACCES times is NULL, the caller's effective user ID does not match the
              owner of the file, the caller does not have write access to the
              file, and the caller is not privileged (Linux: does not have either
              the CAP_DAC_OVERRIDE or the CAP_FOWNER capability).

       ENOENT filename does not exist.

       EPERM  times is not NULL, the caller's effective UID does not match the
              owner of the file, and the caller is not privileged (Linux: does not
              have the CAP_FOWNER capability).

       EROFS  path resides on a read-only file system.

CONFORMING TO top

       utime(): SVr4, POSIX.1-2001.  POSIX.1-2008 marks utime() as obsolete.
       utimes(): 4.3BSD, POSIX.1-2001.

NOTES top

       Linux does not allow changing the timestamps on an immutable file, or
       setting the timestamps to something other than the current time on an
       append-only file.

       In libc4 and libc5, utimes() is just a wrapper for utime() and hence does
       not allow a subsecond resolution.

SEE ALSO top

       chattr(1), futimesat(2), stat(2), utimensat(2), futimens(3), futimes(3)

COLOPHON top

       This page is part of release 3.45 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                            UTIME(2)


utmp(5) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

UTMP(5)                      Linux Programmer's Manual                     UTMP(5)

NAME top

       utmp, wtmp - login records

SYNOPSIS top

       #include <utmp.h>

DESCRIPTION top

       The utmp file allows one to discover information about who is currently
       using the system.  There may be more users currently using the system,
       because not all programs use utmp logging.

       Warning: utmp must not be writable by the user class "other", because many
       system programs (foolishly) depend on its integrity.  You risk faked system
       logfiles and modifications of system files if you leave utmp writable to
       any user other than the owner and group owner of the file.

       The file is a sequence of utmp structures, declared as follows in <utmp.h>
       (note that this is only one of several definitions around; details depend
       on the version of libc):

           /* Values for ut_type field, below */

           #define EMPTY         0 /* Record does not contain valid info
                                      (formerly known as UT_UNKNOWN on Linux) */
           #define RUN_LVL       1 /* Change in system run-level (see
                                      init(8)) */
           #define BOOT_TIME     2 /* Time of system boot (in ut_tv) */
           #define NEW_TIME      3 /* Time after system clock change
                                      (in ut_tv) */
           #define OLD_TIME      4 /* Time before system clock change
                                      (in ut_tv) */
           #define INIT_PROCESS  5 /* Process spawned by init(8) */
           #define LOGIN_PROCESS 6 /* Session leader process for user login */
           #define USER_PROCESS  7 /* Normal process */
           #define DEAD_PROCESS  8 /* Terminated process */
           #define ACCOUNTING    9 /* Not implemented */

           #define UT_LINESIZE      32
           #define UT_NAMESIZE      32
           #define UT_HOSTSIZE     256

           struct exit_status {              /* Type for ut_exit, below */
               short int e_termination;      /* Process termination status */
               short int e_exit;             /* Process exit status */
           };

           struct utmp {
               short   ut_type;              /* Type of record */
               pid_t   ut_pid;               /* PID of login process */
               char    ut_line[UT_LINESIZE]; /* Device name of tty - "/dev/" */
               char    ut_id[4];             /* Terminal name suffix,
                                                or inittab(5) ID */
               char    ut_user[UT_NAMESIZE]; /* Username */
               char    ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or
                                                kernel version for run-level
                                                messages */
               struct  exit_status ut_exit;  /* Exit status of a process
                                                marked as DEAD_PROCESS; not
                                                used by Linux init(8) */
               /* The ut_session and ut_tv fields must be the same size when
                  compiled 32- and 64-bit.  This allows data files and shared
                  memory to be shared between 32- and 64-bit applications. */
           #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
               int32_t ut_session;           /* Session ID (getsid(2)),
                                                used for windowing */
               struct {
                   int32_t tv_sec;           /* Seconds */
                   int32_t tv_usec;          /* Microseconds */
               } ut_tv;                      /* Time entry was made */
           #else
                long   ut_session;           /* Session ID */
                struct timeval ut_tv;        /* Time entry was made */
           #endif

               int32_t ut_addr_v6[4];        /* Internet address of remote
                                                host; IPv4 address uses
                                                just ut_addr_v6[0] */
               char __unused[20];            /* Reserved for future use */
           };

           /* Backward compatibility hacks */
           #define ut_name ut_user
           #ifndef _NO_UT_TIME
           #define ut_time ut_tv.tv_sec
           #endif
           #define ut_xtime ut_tv.tv_sec
           #define ut_addr ut_addr_v6[0]

       This structure gives the name of the special file associated with the
       user's terminal, the user's login name, and the time of login in the form
       of time(2).  String fields are terminated by a null byte ('\0') if they are
       shorter than the size of the field.

       The first entries ever created result from init(8) processing inittab(5).
       Before an entry is processed, though, init(8) cleans up utmp by setting
       ut_type to DEAD_PROCESS, clearing ut_user, ut_host, and ut_time with null
       bytes for each record which ut_type is not DEAD_PROCESS or RUN_LVL and
       where no process with PID ut_pid exists.  If no empty record with the
       needed ut_id can be found, init(8) creates a new one.  It sets ut_id from
       the inittab, ut_pid and ut_time to the current values, and ut_type to
       INIT_PROCESS.

       mingetty(8) (or agetty(8)) locates the entry by the PID, changes ut_type to
       LOGIN_PROCESS, changes ut_time, sets ut_line, and waits for connection to
       be established.  login(1), after a user has been authenticated, changes
       ut_type to USER_PROCESS, changes ut_time, and sets ut_host and ut_addr.
       Depending on mingetty(8) (or agetty(8)) and login(1), records may be
       located by ut_line instead of the preferable ut_pid.

       When init(8) finds that a process has exited, it locates its utmp entry by
       ut_pid, sets ut_type to DEAD_PROCESS, and clears ut_user, ut_host and
       ut_time with null bytes.

       xterm(1) and other terminal emulators directly create a USER_PROCESS record
       and generate the ut_id by using the string that suffix part of the terminal
       name (the characters following /dev/[pt]ty).  If they find a DEAD_PROCESS
       for this ID, they recycle it, otherwise they create a new entry.  If they
       can, they will mark it as DEAD_PROCESS on exiting and it is advised that
       they null ut_line, ut_time, ut_user, and ut_host as well.

       telnetd(8) sets up a LOGIN_PROCESS entry and leaves the rest to login(1) as
       usual.  After the telnet session ends, telnetd(8) cleans up utmp in the
       described way.

       The wtmp file records all logins and logouts.  Its format is exactly like
       utmp except that a null username indicates a logout on the associated
       terminal.  Furthermore, the terminal name ~ with username shutdown or
       reboot indicates a system shutdown or reboot and the pair of terminal names
       |/} logs the old/new system time when date(1) changes it.  wtmp is
       maintained by login(1), init(8), and some versions of getty(8) (e.g.,
       mingetty(8) or agetty(8)).  None of these programs creates the file, so if
       it is removed, record-keeping is turned off.

FILES top

       /var/run/utmp
       /var/log/wtmp

CONFORMING TO top

       POSIX.1 does not specify a utmp structure, but rather one named utmpx, with
       specifications for the fields ut_type, ut_pid, ut_line, ut_id, ut_user, and
       ut_tv.  POSIX.1 does not specify the lengths of the ut_line and ut_user
       fields.

       Linux defines the utmpx structure to be the same as the utmp structure.

Comparison with Historical Systems

       Linux utmp entries conform neither to v7/BSD nor to System V; they are a
       mix of the two.

       v7/BSD has fewer fields; most importantly it lacks ut_type, which causes
       native v7/BSD-like programs to display (for example) dead or login entries.
       Further, there is no configuration file which allocates slots to sessions.
       BSD does so because it lacks ut_id fields.

       In Linux (as in System V), the ut_id field of a record will never change
       once it has been set, which reserves that slot without needing a
       configuration file.  Clearing ut_id may result in race conditions leading
       to corrupted utmp entries and potential security holes.  Clearing the
       abovementioned fields by filling them with null bytes is not required by
       System V semantics, but makes it possible to run many programs which assume
       BSD semantics and which do not modify utmp.  Linux uses the BSD conventions
       for line contents, as documented above.

       System V has no ut_host or ut_addr_v6 fields.

NOTES top

       Unlike various other systems, where utmp logging can be disabled by
       removing the file, utmp must always exist on Linux.  If you want to disable
       who(1) then do not make utmp world readable.

       The file format is machine-dependent, so it is recommended that it be
       processed only on the machine architecture where it was created.

       Note that on biarch platforms, that is, systems which can run both 32-bit
       and 64-bit applications (x86-64, ppc64, s390x, etc.), ut_tv is the same
       size in 32-bit mode as in 64-bit mode.  The same goes for ut_session and
       ut_time if they are present.  This allows data files and shared memory to
       be shared between 32-bit and 64-bit applications.  This is achieved by
       changing the type of ut_session to int32_t, and that of ut_tv to a struct
       with two int32_t fields tv_sec and tv_usec.  Since ut_tv may not be the
       same as struct timeval, then instead of the call:

           gettimeofday((struct timeval *) &ut.ut_tv, NULL);

       the following method of setting this field is recommended:

           struct utmp ut;
           struct timeval tv;

           gettimeofday(&tv, NULL);
           ut.ut_tv.tv_sec = tv.tv_sec;
           ut.ut_tv.tv_usec = tv.tv_usec;

       Note that the utmp struct from libc5 has changed in libc6.  Because of
       this, binaries using the old libc5 struct will corrupt /var/run/utmp and/or
       /var/log/wtmp.

BUGS top

       This man page is based on the libc5 one, things may work differently now.

SEE ALSO top

       ac(1), date(1), last(1), login(1), who(1), getutent(3), getutmp(3),
       login(3), logout(3), logwtmp(3), updwtmp(3), init(8)

COLOPHON top

       This page is part of release 3.45 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                               2011-09-28                             UTMP(5)


vcs(4) - Linux manual page

NAME | DESCRIPTION | FILES | VERSIONS | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

VCS(4)                       Linux Programmer's Manual                      VCS(4)

NAME top

       vcs, vcsa - virtual console memory

DESCRIPTION top

       /dev/vcs0 is a character device with major number 7 and minor number 0,
       usually of mode 0644 and owner root.tty.  It refers to the memory of the
       currently displayed virtual console terminal.

       /dev/vcs[1-63] are character devices for virtual console terminals, they
       have major number 7 and minor number 1 to 63, usually mode 0644 and owner
       root.tty.  /dev/vcsa[0-63] are the same, but using unsigned shorts (in host
       byte order) that include attributes, and prefixed with four bytes giving
       the screen dimensions and cursor position: lines, columns, x, y.  (x = y =
       0 at the top left corner of the screen.)

       When a 512-character font is loaded, the 9th bit position can be fetched by
       applying the ioctl(2) VT_GETHIFONTMASK operation (available in Linux
       kernels 2.6.18 and above) on /dev/tty[1-63]; the value is returned in the
       unsigned short pointed to by the third ioctl(2) argument.

       These devices replace the screendump ioctl(2) operations of console(4), so
       the system administrator can control access using file system permissions.

       The devices for the first eight virtual consoles may be created by:

           for x in 0 1 2 3 4 5 6 7 8; do
               mknod -m 644 /dev/vcs$x c 7 $x;
               mknod -m 644 /dev/vcsa$x c 7 $[$x+128];
           done
           chown root:tty /dev/vcs*

       No ioctl(2) requests are supported.

FILES top

       /dev/vcs[0-63]
       /dev/vcsa[0-63]

VERSIONS top

       Introduced with version 1.1.92 of the Linux kernel.

EXAMPLE top

       You may do a screendump on vt3 by switching to vt1 and typing cat /dev/vcs3
       >foo.  Note that the output does not contain newline characters, so some
       processing may be required, like in fold -w 81 /dev/vcs3 | lpr or (horrors)
       setterm -dump 3 -file /proc/self/fd/1.

       The /dev/vcsa0 device is used for Braille support.

       This program displays the character and screen attributes under the cursor
       of the second virtual console, then changes the background color there:

       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>
       #include <fcntl.h>
       #include <sys/ioctl.h>
       #include <linux/vt.h>

       int
       main(void)
       {
           int fd;
           char *device = "/dev/vcsa2";
           char *console = "/dev/tty2";
           struct {unsigned char lines, cols, x, y;} scrn;
           unsigned short s;
           unsigned short mask;
           unsigned char ch, attrib;

           fd = open(console, O_RDWR);
           if (fd < 0) {
               perror(console);
               exit(EXIT_FAILURE);
           }
           if (ioctl(fd, VT_GETHIFONTMASK, &mask) < 0) {
               perror("VT_GETHIFONTMASK");
               exit(EXIT_FAILURE);
           }
           (void) close(fd);
           fd = open(device, O_RDWR);
           if (fd < 0) {
               perror(device);
               exit(EXIT_FAILURE);
           }
           (void) read(fd, &scrn, 4);
           (void) lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0);
           (void) read(fd, &s, 2);
           ch = s & 0xff;
           if (attrib & mask)
               ch |= 0x100;
           attrib = ((s & ~mask) >> 8);
           printf("ch='%c' attrib=0x%02x\n", ch, attrib);
           attrib ^= 0x10;
           (void) lseek(fd, -1, 1);
           (void) write(fd, &attrib, 1);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       console(4), tty(4), ttyS(4), gpm(8)

COLOPHON top

       This page is part of release 3.45 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-12-17                              VCS(4)


vfork(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

VFORK(2)                     Linux Programmer's Manual                    VFORK(2)

NAME top

       vfork - create a child process and block parent

SYNOPSIS top

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

       pid_t vfork(void);

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

       vfork():
           Since glibc 2.12:
               _BSD_SOURCE ||
                   (_XOPEN_SOURCE >= 500 ||
                       _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
                   !(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)
           Before glibc 2.12:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
               _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

DESCRIPTION top

Standard Description

       (From POSIX.1) The vfork() function has the same effect as fork(2), except
       that the behavior is undefined if the process created by vfork() either
       modifies any data other than a variable of type pid_t used to store the
       return value from vfork(), or returns from the function in which vfork()
       was called, or calls any other function before successfully calling
       _exit(2) or one of the exec(3) family of functions.

Linux Description

       vfork(), just like fork(2), creates a child process of the calling process.
       For details and return value and errors, see fork(2).

       vfork() is a special case of clone(2).  It is used to create new processes
       without copying the page tables of the parent process.  It may be useful in
       performance-sensitive applications where a child is created which then
       immediately issues an execve(2).

       vfork() differs from fork(2) in that the calling thread is suspended until
       the child terminates (either normally, by calling _exit(2), or abnormally,
       after delivery of a fatal signal), or it makes a call to execve(2).  Until
       that point, the child shares all memory with its parent, including the
       stack.  The child must not return from the current function or call
       exit(3), but may call _exit(2).

       As with fork(2), the child process created by vfork() inherits copies of
       various of the caller's process attributes (e.g., file descriptors, signal
       dispositions, and current working directory); the vfork() call differs only
       in the treatment of the virtual address space, as described above.

       Signals sent to the parent arrive after the child releases the parent's
       memory (i.e., after the child terminates or calls execve(2)).

Historic Description

       Under Linux, fork(2) is implemented using copy-on-write pages, so the only
       penalty incurred by fork(2) is the time and memory required to duplicate
       the parent's page tables, and to create a unique task structure for the
       child.  However, in the bad old days a fork(2) would require making a
       complete copy of the caller's data space, often needlessly, since usually
       immediately afterward an exec(3) is done.  Thus, for greater efficiency,
       BSD introduced the vfork() system call, which did not fully copy the
       address space of the parent process, but borrowed the parent's memory and
       thread of control until a call to execve(2) or an exit occurred.  The
       parent process was suspended while the child was using its resources.  The
       use of vfork() was tricky: for example, not modifying data in the parent
       process depended on knowing which variables were held in a register.

CONFORMING TO          top
       4.3BSD; POSIX.1-2001 (but marked OBSOLETE).  POSIX.1-2008 removes the
       specification of vfork().

       The requirements put on vfork() by the standards are weaker than those put
       on fork(2), so an implementation where the two are synonymous is compliant.
       In particular, the programmer cannot rely on the parent remaining blocked
       until the child either terminates or calls execve(2), and cannot rely on
       any specific behavior with respect to shared memory.

NOTES          top
       Some consider the semantics of vfork() to be an architectural blemish, and
       the 4.2BSD man page stated: "This system call will be eliminated when
       proper system sharing mechanisms are implemented.  Users should not depend
       on the memory sharing semantics of vfork() as it will, in that case, be
       made synonymous to fork(2)."  However, even though modern memory management
       hardware has decreased the performance difference between fork(2) and
       vfork(), there are various reasons why Linux and other systems have
       retained vfork():

       *  Some performance-critical applications require the small performance
          advantage conferred by vfork().

       *  vfork() can be implemented on systems that lack a memory-management unit
          (MMU), but fork(2) can't be implemented on such systems.  (POSIX.1-2008
          removed vfork() from the standard; the POSIX rationale for the
          posix_spawn(3) function notes that that function, which provides
          functionality equivalent to fork(2)+exec(3), is designed to be
          implementable on systems that lack an MMU.)

Linux Notes

       Fork handlers established using pthread_atfork(3) are not called when a
       multithreaded program employing the NPTL threading library calls vfork().
       Fork handlers are called in this case in a program using the LinuxThreads
       threading library.  (See pthreads(7) for a description of Linux threading
       libraries.)

       A call to vfork() is equivalent to calling clone(2) with flags specified
       as:

            CLONE_VM | CLONE_VFORK | SIGCHLD

History

       The vfork() system call appeared in 3.0BSD.  In 4.4BSD it was made
       synonymous to fork(2) but NetBSD introduced it again, cf.
       <http://www.netbsd.org/Documentation/kernel/vfork.html>.  In Linux, it has
       been equivalent to fork(2) until 2.2.0-pre6 or so.  Since 2.2.0-pre9 (on
       i386, somewhat later on other architectures) it is an independent system
       call.  Support was added in glibc 2.0.112.

BUGS          top
       Details of the signal handling are obscure and differ between systems.  The
       BSD man page states: "To avoid a possible deadlock situation, processes
       that are children in the middle of a vfork() are never sent SIGTTOU or
       SIGTTIN signals; rather, output or ioctls are allowed and input attempts
       result in an end-of-file indication."

SEE ALSO          top
       clone(2), execve(2), fork(2), unshare(2), wait(2)

COLOPHON          top
       This page is part of release 3.45 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                               2012-08-05                            VFORK(2)

HTML rendering created 2012-12-20 by Michael Kerrisk,
author of
The Linux Programming Interface,
maintainer of the
Linux man-pages project


vhangup(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

VHANGUP(2)                   Linux Programmer's Manual                  VHANGUP(2)

NAME top

       vhangup - virtually hangup the current tty

SYNOPSIS top

       #include <unistd.h>

       int vhangup(void);

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

       vhangup(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

DESCRIPTION top

       vhangup() simulates a hangup on the current terminal.  This call arranges
       for other users to have a "clean" tty at login time.

RETURN VALUE top

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

ERRORS top

       EPERM  The calling process has insufficient privilege to call vhangup();
              the CAP_SYS_TTY_CONFIG capability is required.

CONFORMING TO top

       This call is Linux-specific, and should not be used in programs intended to
       be portable.

SEE ALSO top

       capabilities(7), init(8)

COLOPHON top

       This page is part of release 3.45 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-26                          VHANGUP(2)


vm86(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | COLOPHON The Linux Programming Interface

VM86(2)                      Linux Programmer's Manual                     VM86(2)

NAME top

       vm86old, vm86 - enter virtual 8086 mode

SYNOPSIS top

       #include <sys/vm86.h>

       int vm86old(struct vm86_struct *info);

       int vm86(unsigned long fn, struct vm86plus_struct *v86);

DESCRIPTION top

       The system call vm86() was introduced in Linux 0.97p2.  In Linux 2.1.15 and
       2.0.28 it was renamed to vm86old(), and a new vm86() was introduced.  The
       definition of struct vm86_struct was changed in 1.1.8 and 1.1.9.

       These calls cause the process to enter VM86 mode (virtual-8086 in Intel
       literature), and are used by dosemu.

       VM86 mode is an emulation of real mode within a protected mode task.

RETURN VALUE top

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

ERRORS top

       EFAULT This return value is specific to i386 and indicates a problem with
              getting user-space data.

       ENOSYS This return value indicates the call is not implemented on the
              present architecture.

       EPERM  Saved kernel stack exists.  (This is a kernel sanity check; the
              saved stack should only exist within vm86 mode itself.)

CONFORMING TO top

       This call is specific to Linux on 32-bit Intel processors, and should not
       be used in programs intended to be portable.

COLOPHON top

       This page is part of release 3.45 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                               2009-02-20                             VM86(2)


vmsplice(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

VMSPLICE(2)                  Linux Programmer's Manual                 VMSPLICE(2)

NAME top

       vmsplice - splice user pages into a pipe

SYNOPSIS top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <fcntl.h>
       #include <sys/uio.h>

       ssize_t vmsplice(int fd, const struct iovec *iov,
                        unsigned long nr_segs, unsigned int flags);

DESCRIPTION top

       The vmsplice() system call maps nr_segs ranges of user memory described by
       iov into a pipe.  The file descriptor fd must refer to a pipe.

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

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

       The flags argument is a bit mask that is composed by ORing together zero or
       more of the following values:

       SPLICE_F_MOVE      Unused for vmsplice(); see splice(2).

       SPLICE_F_NONBLOCK  Do not block on I/O; see splice(2) for further details.

       SPLICE_F_MORE      Currently has no effect for vmsplice(), but may be
                          implemented in the future; see splice(2).

       SPLICE_F_GIFT      The user pages are a gift to the kernel.  The
                          application may not modify this memory ever, or page
                          cache and on-disk data may differ.  Gifting pages to the
                          kernel means that a subsequent splice(2) SPLICE_F_MOVE
                          can successfully move the pages; if this flag is not
                          specified, then a subsequent splice(2) SPLICE_F_MOVE
                          must copy the pages.  Data must also be properly page
                          aligned, both in memory and length.

RETURN VALUE top

       Upon successful completion, vmsplice() returns the number of bytes
       transferred to the pipe.  On error, vmsplice() returns -1 and errno is set
       to indicate the error.

ERRORS top

       EBADF  fd either not valid, or doesn't refer to a pipe.

       EINVAL nr_segs is 0 or greater than IOV_MAX; or memory not aligned if
              SPLICE_F_GIFT set.

       ENOMEM Out of memory.

VERSIONS top

       The vmsplice() system call first appeared in Linux 2.6.17; library support
       was added to glibc in version 2.5.

CONFORMING TO top

       This system call is Linux-specific.

NOTES top

       vmsplice() follows the other vectorized read/write type functions when it
       comes to limitations on number of segments being passed in.  This limit is
       IOV_MAX as defined in <limits.h>.  At the time of this writing, that limit
       is 1024.

SEE ALSO top

       splice(2), tee(2)

COLOPHON top

       This page is part of release 3.45 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                               2012-05-04                         VMSPLICE(2)


wait(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | EXAMPLE | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

WAIT(2)                      Linux Programmer's Manual                     WAIT(2)

NAME top

       wait, waitpid, waitid - wait for process to change state

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/wait.h>

       pid_t wait(int *status);

       pid_t waitpid(pid_t pid, int *status, int options);

       int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);

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

       waitid():
           _SVID_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
           || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

DESCRIPTION top

       All of these system calls are used to wait for state changes in a child of
       the calling process, and obtain information about the child whose state has
       changed.  A state change is considered to be: the child terminated; the
       child was stopped by a signal; or the child was resumed by a signal.  In
       the case of a terminated child, performing a wait allows the system to
       release the resources associated with the child; if a wait is not
       performed, then the terminated child remains in a "zombie" state (see NOTES
       below).

       If a child has already changed state, then these calls return immediately.
       Otherwise they block until either a child changes state or a signal handler
       interrupts the call (assuming that system calls are not automatically
       restarted using the SA_RESTART flag of sigaction(2)).  In the remainder of
       this page, a child whose state has changed and which has not yet been
       waited upon by one of these system calls is termed waitable.

wait() and waitpid()

       The wait() system call suspends execution of the calling process until one
       of its children terminates.  The call wait(&status) is equivalent to:

           waitpid(-1, &status, 0);

       The waitpid() system call suspends execution of the calling process until a
       child specified by pid argument has changed state.  By default, waitpid()
       waits only for terminated children, but this behavior is modifiable via the
       options argument, as described below.

       The value of pid can be:

       < -1   meaning wait for any child process whose process group ID is equal
              to the absolute value of pid.

       -1     meaning wait for any child process.

       0      meaning wait for any child process whose process group ID is equal
              to that of the calling process.

       > 0    meaning wait for the child whose process ID is equal to the value of
              pid.

       The value of options is an OR of zero or more of the following constants:

       WNOHANG     return immediately if no child has exited.

       WUNTRACED   also return if a child has stopped (but not traced via
                   ptrace(2)).  Status for traced children which have stopped is
                   provided even if this option is not specified.

       WCONTINUED (since Linux 2.6.10)
                   also return if a stopped child has been resumed by delivery of
                   SIGCONT.

       (For Linux-only options, see below.)

       If status is not NULL, wait() and waitpid() store status information in the
       int to which it points.  This integer can be inspected with the following
       macros (which take the integer itself as an argument, not a pointer to it,
       as is done in wait() and waitpid()!):

       WIFEXITED(status)
              returns true if the child terminated normally, that is, by calling
              exit(3) or _exit(2), or by returning from main().

       WEXITSTATUS(status)
              returns the exit status of the child.  This consists of the least
              significant 8 bits of the status argument that the child specified
              in a call to exit(3) or _exit(2) or as the argument for a return
              statement in main().  This macro should only be employed if
              WIFEXITED returned true.

       WIFSIGNALED(status)
              returns true if the child process was terminated by a signal.

       WTERMSIG(status)
              returns the number of the signal that caused the child process to
              terminate.  This macro should only be employed if WIFSIGNALED
              returned true.

       WCOREDUMP(status)
              returns true if the child produced a core dump.  This macro should
              only be employed if WIFSIGNALED returned true.  This macro is not
              specified in POSIX.1-2001 and is not available on some UNIX
              implementations (e.g., AIX, SunOS).  Only use this enclosed in
              #ifdef WCOREDUMP ... #endif.

       WIFSTOPPED(status)
              returns true if the child process was stopped by delivery of a
              signal; this is only possible if the call was done using WUNTRACED
              or when the child is being traced (see ptrace(2)).

       WSTOPSIG(status)
              returns the number of the signal which caused the child to stop.
              This macro should only be employed if WIFSTOPPED returned true.

       WIFCONTINUED(status)
              (since Linux 2.6.10) returns true if the child process was resumed
              by delivery of SIGCONT.

waitid()

       The waitid() system call (available since Linux 2.6.9) provides more
       precise control over which child state changes to wait for.

       The idtype and id arguments select the child(ren) to wait for, as follows:

       idtype == P_PID
              Wait for the child whose process ID matches id.

       idtype == P_PGID
              Wait for any child whose process group ID matches id.

       idtype == P_ALL
              Wait for any child; id is ignored.

       The child state changes to wait for are specified by ORing one or more of
       the following flags in options:

       WEXITED     Wait for children that have terminated.

       WSTOPPED    Wait for children that have been stopped by delivery of a
                   signal.

       WCONTINUED  Wait for (previously stopped) children that have been resumed
                   by delivery of SIGCONT.

       The following flags may additionally be ORed in options:

       WNOHANG     As for waitpid().

       WNOWAIT     Leave the child in a waitable state; a later wait call can be
                   used to again retrieve the child status information.

       Upon successful return, waitid() fills in the following fields of the
       siginfo_t structure pointed to by infop:

       si_pid      The process ID of the child.

       si_uid      The real user ID of the child.  (This field is not set on most
                   other implementations.)

       si_signo    Always set to SIGCHLD.

       si_status   Either the exit status of the child, as given to _exit(2) (or
                   exit(3)), or the signal that caused the child to terminate,
                   stop, or continue.  The si_code field can be used to determine
                   how to interpret this field.

       si_code     Set to one of: CLD_EXITED (child called _exit(2)); CLD_KILLED
                   (child killed by signal); CLD_DUMPED (child killed by signal,
                   and dumped core); CLD_STOPPED (child stopped by signal);
                   CLD_TRAPPED (traced child has trapped); or CLD_CONTINUED (child
                   continued by SIGCONT).

       If WNOHANG was specified in options and there were no children in a
       waitable state, then waitid() returns 0 immediately and the state of the
       siginfo_t structure pointed to by infop is unspecified.  To distinguish
       this case from that where a child was in a waitable state, zero out the
       si_pid field before the call and check for a nonzero value in this field
       after the call returns.

RETURN VALUE top

       wait(): on success, returns the process ID of the terminated child; on
       error, -1 is returned.

       waitpid(): on success, returns the process ID of the child whose state has
       changed; if WNOHANG was specified and one or more child(ren) specified by
       pid exist, but have not yet changed state, then 0 is returned.  On error,
       -1 is returned.

       waitid(): returns 0 on success or if WNOHANG was specified and no
       child(ren) specified by id has yet changed state; on error, -1 is returned.
       Each of these calls sets errno to an appropriate value in the case of an
       error.

ERRORS top

       ECHILD (for wait()) The calling process does not have any unwaited-for
              children.

       ECHILD (for waitpid() or waitid()) The process specified by pid (waitpid())
              or idtype and id (waitid()) does not exist or is not a child of the
              calling process.  (This can happen for one's own child if the action
              for SIGCHLD is set to SIG_IGN.  See also the Linux Notes section
              about threads.)

       EINTR  WNOHANG was not set and an unblocked signal or a SIGCHLD was caught;
              see signal(7).

       EINVAL The options argument was invalid.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES top

       A child that terminates, but has not been waited for becomes a "zombie".
       The kernel maintains a minimal set of information about the zombie process
       (PID, termination status, resource usage information) in order to allow the
       parent to later perform a wait to obtain information about the child.  As
       long as a zombie is not removed from the system via a wait, it will consume
       a slot in the kernel process table, and if this table fills, it will not be
       possible to create further processes.  If a parent process terminates, then
       its "zombie" children (if any) are adopted by init(8), which automatically
       performs a wait to remove the zombies.

       POSIX.1-2001 specifies that if the disposition of SIGCHLD is set to SIG_IGN
       or the SA_NOCLDWAIT flag is set for SIGCHLD (see sigaction(2)), then
       children that terminate do not become zombies and a call to wait() or
       waitpid() will block until all children have terminated, and then fail with
       errno set to ECHILD.  (The original POSIX standard left the behavior of
       setting SIGCHLD to SIG_IGN unspecified.  Note that even though the default
       disposition of SIGCHLD is "ignore", explicitly setting the disposition to
       SIG_IGN results in different treatment of zombie process children.)  Linux
       2.6 conforms to this specification.  However, Linux 2.4 (and earlier) does
       not: if a wait() or waitpid() call is made while SIGCHLD is being ignored,
       the call behaves just as though SIGCHLD were not being ignored, that is,
       the call blocks until the next child terminates and then returns the
       process ID and status of that child.

Linux Notes

       In the Linux kernel, a kernel-scheduled thread is not a distinct construct
       from a process.  Instead, a thread is simply a process that is created
       using the Linux-unique clone(2) system call; other routines such as the
       portable pthread_create(3) call are implemented using clone(2).  Before
       Linux 2.4, a thread was just a special case of a process, and as a
       consequence one thread could not wait on the children of another thread,
       even when the latter belongs to the same thread group.  However, POSIX
       prescribes such functionality, and since Linux 2.4 a thread can, and by
       default will, wait on children of other threads in the same thread group.

       The following Linux-specific options are for use with children created
       using clone(2); they cannot be used with waitid():

       __WCLONE
              Wait for "clone" children only.  If omitted then wait for "non-
              clone" children only.  (A "clone" child is one which delivers no
              signal, or a signal other than SIGCHLD to its parent upon
              termination.)  This option is ignored if __WALL is also specified.

       __WALL (since Linux 2.4)
              Wait for all children, regardless of type ("clone" or "non-clone").

       __WNOTHREAD (since Linux 2.4)
              Do not wait for children of other threads in the same thread group.
              This was the default before Linux 2.4.

EXAMPLE top

       The following program demonstrates the use of fork(2) and waitpid().  The
       program creates a child process.  If no command-line argument is supplied
       to the program, then the child suspends its execution using pause(2), to
       allow the user to send signals to the child.  Otherwise, if a command-line
       argument is supplied, then the child exits immediately, using the integer
       supplied on the command line as the exit status.  The parent process
       executes a loop that monitors the child using waitpid(), and uses the W*()
       macros described above to analyze the wait status value.

       The following shell session demonstrates the use of the program:

           $ ./a.out &
           Child PID is 32360
           [1] 32359
           $ kill -STOP 32360
           stopped by signal 19
           $ kill -CONT 32360
           continued
           $ kill -TERM 32360
           killed by signal 15
           [1]+  Done                    ./a.out
           $

Program source

       #include <sys/wait.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           pid_t cpid, w;
           int status;

           cpid = fork();
           if (cpid == -1) {
               perror("fork");
               exit(EXIT_FAILURE);
           }

           if (cpid == 0) {            /* Code executed by child */
               printf("Child PID is %ld\n", (long) getpid());
               if (argc == 1)
                   pause();                    /* Wait for signals */
               _exit(atoi(argv[1]));

           } else {                    /* Code executed by parent */
               do {
                   w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);
                   if (w == -1) {
                       perror("waitpid");
                       exit(EXIT_FAILURE);
                   }

                   if (WIFEXITED(status)) {
                       printf("exited, status=%d\n", WEXITSTATUS(status));
                   } else if (WIFSIGNALED(status)) {
                       printf("killed by signal %d\n", WTERMSIG(status));
                   } else if (WIFSTOPPED(status)) {
                       printf("stopped by signal %d\n", WSTOPSIG(status));
                   } else if (WIFCONTINUED(status)) {
                       printf("continued\n");
                   }
               } while (!WIFEXITED(status) && !WIFSIGNALED(status));
               exit(EXIT_SUCCESS);
           }
       }

BUGS top

       According to POSIX.1-2008, an application calling waitid() must ensure that
       infop points to a siginfo_t structure (i.e., that it is a non-NULL
       pointer).  On Linux, if infop is NULL, waitid() succeeds, and returns the
       process ID of the waited-for child.  Applications should avoid relying on
       this inconsistent, nonstandard, and unnecessary feature.

SEE ALSO top

       _exit(2), clone(2), fork(2), kill(2), ptrace(2), sigaction(2), signal(2),
       wait4(2), pthread_create(3), credentials(7), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-12-21                             WAIT(2)


wait4(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WAIT4(2)                     Linux Programmer's Manual                    WAIT4(2)

NAME top

       wait3, wait4 - wait for process to change state, BSD style

SYNOPSIS top

       #include <sys/types.h>
       #include <sys/time.h>
       #include <sys/resource.h>
       #include <sys/wait.h>

       pid_t wait3(int *status, int options,
                   struct rusage *rusage);

       pid_t wait4(pid_t pid, int *status, int options,
                   struct rusage *rusage);

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

       wait3():
           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
       wait4():
           _BSD_SOURCE

DESCRIPTION top

       These functions are obsolete; use waitpid(2) or waitid(2) in new programs.

       The wait3() and wait4() system calls are similar to waitpid(2), but
       additionally return resource usage information about the child in the
       structure pointed to by rusage.

       Other than the use of the rusage argument, the following wait3() call:

           wait3(status, options, rusage);

       is equivalent to:

           waitpid(-1, status, options);

       Similarly, the following wait4() call:

           wait4(pid, status, options, rusage);

       is equivalent to:

           waitpid(pid, status, options);

       In other words, wait3() waits of any child, while wait4() can be used to
       select a specific child, or children, on which to wait.  See wait(2) for
       further details.

       If rusage is not NULL, the struct rusage to which it points will be filled
       with accounting information about the child.  See getrusage(2) for details.

RETURN VALUE top

       As for waitpid(2).

ERRORS top

       As for waitpid(2).

CONFORMING TO top

       4.3BSD.

       SUSv1 included a specification of wait3(); SUSv2 included wait3(), but
       marked it LEGACY; SUSv3 removed it.

NOTES top

       Including <sys/time.h> is not required these days, but increases
       portability.  (Indeed, <sys/resource.h> defines the rusage structure with
       fields of type struct timeval defined in <sys/time.h>.)

       On Linux, wait3() is a library function implemented on top of the wait4()
       system call.

SEE ALSO top

       fork(2), getrusage(2), sigaction(2), signal(2), wait(2), signal(7)

COLOPHON top

       This page is part of release 3.45 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                               2012-09-23                            WAIT4(2)


wavelan(4) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

WAVELAN(4)                   Linux Programmer's Manual                  WAVELAN(4)

NAME top

       wavelan - AT&T GIS WaveLAN ISA device driver

SYNOPSIS top

       insmod wavelan_cs.o [io=B,B..] [ irq=I,I..] [name=N,N..]

DESCRIPTION top

       wavelan is the low-level device driver for the NCR / AT&T / Lucent WaveLAN
       ISA and Digital (DEC) RoamAbout DS wireless ethernet adapter.  This driver
       is available as a module or might be compiled in the kernel.  This driver
       supports multiple cards in both forms (up to 4) and allocates the next
       available ethernet device (eth0..eth#) for each card found, unless a device
       name is explicitly specified (see below).  This device name will be
       reported in the kernel log file with the MAC address, NWID and frequency
       used by the card.

Parameters

       This section apply to the module form (parameters passed on the insmod(8)
       command line).  If the driver is included in the kernel, use the
       ether=IRQ,IO,NAME syntax on the kernel command line.

       io     Specify the list of base address where to search for wavelan cards
              (setting by dip switch on the card).  If you don't specify any io
              address, the driver will scan 0x390 and 0x3E0 addresses, which might
              conflict with other hardware...

       irq    Set the list of irq that each wavelan card should use (the value is
              saved in permanent storage for future use).

       name   Set the list of name to be used for each wavelan cards device (name
              used by ifconfig(8)).

Wireless Extensions

       Use iwconfig(8) to manipulate wireless extensions.

NWID (or domain)

       Set the network ID [0 to FFFF] or disable it [off].  As the NWID is stored
       in the card Permanent Storage Area, it will be reuse at any further
       invocation of the driver.

Frequency & channels

       For the 2.4GHz 2.00 Hardware, you are able to set the frequency by
       specifying one of the 10 defined channels (2.412, 2.422, 2.425, 2.4305,
       2.432, 2.442, 2.452, 2.460, 2.462 or 2.484) or directly by its value.  The
       frequency is changed immediately and permanently.  Frequency availability
       depends on the regulations...

Statistics spy

       Set a list of MAC addresses in the driver (up to 8) and get the last
       quality of link for each of those (see iwspy(8)).

/proc/net/wireless

       status is the status reported by the modem.  Link quality reports the
       quality of the modulation on the air (direct sequence spread spectrum) [max
       = 16].  Level and Noise refer to the signal level and noise level [max =
       64].  The crypt discarded packet and misc discarded packet counters are not
       implemented.

Private Ioctl

       You may use iwpriv(8) to manipulate private ioctls.

Quality and Level threshold

       Enable you the define the quality and level threshold used by the modem
       (packet below that level are discarded).

Histogram

       This functionality makes it possible to set a number of signal level
       intervals and to count the number of packets received in each of those
       defined intervals.  This distribution might be used to calculate the mean
       value and standard deviation of the signal level.

Specific Notes

       This driver will fail to detect some non-NCR/ATT&T/Lucent Wavelan cards.
       If this happens for you, you must look in the source code on how to add
       your card to the detection routine.

       Some of the mentioned features are optional.  You may enable to disable
       them by changing flags in the driver header and recompile.

SEE ALSO top

       wavelan_cs(4), ifconfig(8), insmod(8), iwconfig(8), iwpriv(8), iwspy(8)

COLOPHON top

       This page is part of release 3.45 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                               1996-10-22                          WAVELAN(4)


wcpcpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCPCPY(3)                    Linux Programmer's Manual                   WCPCPY(3)

NAME top

       wcpcpy - copy a wide-character string, returning a pointer to its end

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcpcpy(wchar_t *dest, const wchar_t *src);

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

       wcpcpy():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcpcpy() function is the wide-character equivalent of the stpcpy(3)
       function.  It copies the wide-character string pointed to by src, including
       the terminating null wide character (L'\0'), to the array pointed to by
       dest.

       The strings may not overlap.

       The programmer must ensure that there is room for at least wcslen(src)+1
       wide characters at dest.

RETURN VALUE top

       wcpcpy() returns a pointer to the end of the wide-character string dest,
       that is, a pointer to the terminating null wide character.

CONFORMING TO top

       POSIX.1-2008.

SEE ALSO top

       strcpy(3), wcscpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-01                           WCPCPY(3)


wcpncpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCPNCPY(3)                   Linux Programmer's Manual                  WCPNCPY(3)

NAME top

       wcpncpy  - copy a fixed-size string of wide characters, returning a pointer
       to its end

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcpncpy(wchar_t *dest, const wchar_t *src, size_t n);

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

       wcpncpy():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcpncpy() function is the wide-character equivalent of the stpncpy(3)
       function.  It copies at most n wide characters from the wide-character
       string pointed to by src, including the terminating null wide (L'\0'), to
       the array pointed to by dest.  Exactly n wide characters are written at
       dest.  If the length wcslen(src) is smaller than n, the remaining wide
       characters in the array pointed to by dest are filled with L'\0'
       characters.  If the length wcslen(src) is greater or equal to n, the string
       pointed to by dest will not be L'\0' terminated.

       The strings may not overlap.

       The programmer must ensure that there is room for at least n wide
       characters at dest.

RETURN VALUE top

       wcpncpy() returns a pointer to the last wide character written, that is,
       dest + n - 1.

CONFORMING TO top

       POSIX.1-2008.

SEE ALSO top

       stpncpy(3), wcsncpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-01                          WCPNCPY(3)


wcrtomb(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCRTOMB(3)                   Linux Programmer's Manual                  WCRTOMB(3)

NAME top

       wcrtomb - convert a wide character to a multibyte sequence

SYNOPSIS top

       #include <wchar.h>

       size_t wcrtomb(char *s, wchar_t wc, mbstate_t *ps);

DESCRIPTION top

       The main case for this function is when s is not NULL and wc is not a null
       wide character (L'\0').  In this case, the wcrtomb() function converts the
       wide character wc to its multibyte representation and stores it at the
       beginning of the character array pointed to by s.  It updates the shift
       state *ps, and returns the length of said multibyte representation, that
       is, the number of bytes written at s.

       A different case is when s is not NULL, but wc is a null wide character
       (L'\0').  In this case the wcrtomb() function stores at the character array
       pointed to by s the shift sequence needed to bring *ps back to the initial
       state, followed by a '\0' byte.  It updates the shift state *ps (i.e.,
       brings it into the initial state), and returns the length of the shift
       sequence plus one, that is, the number of bytes written at s.

       A third case is when s is NULL.  In this case wc is ignored, and the
       function effectively returns

           wcrtomb(buf, L'\0', ps)

       where buf is an internal anonymous buffer.

       In all of the above cases, if ps is a NULL pointer, a static anonymous
       state only known to the wcrtomb() function is used instead.

RETURN VALUE top

       The wcrtomb() function returns the number of bytes that have been or would
       have been written to the byte array at s.  If wc can not be represented as
       a multibyte sequence (according to the current locale), (size_t) -1 is
       returned, and errno set to EILSEQ.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wcrtomb() depends on the LC_CTYPE category of the current
       locale.

       Passing NULL as ps is not multithread safe.

SEE ALSO top

       wcsrtombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          WCRTOMB(3)


wcscasecmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCSCASECMP(3)                Linux Programmer's Manual               WCSCASECMP(3)

NAME top

       wcscasecmp - compare two wide-character strings, ignoring case

SYNOPSIS top

       #include <wchar.h>

       int wcscasecmp(const wchar_t *s1, const wchar_t *s2);

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

       wcscasecmp():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcscasecmp() function is the wide-character equivalent of the
       strcasecmp(3) function.  It compares the wide-character string pointed to
       by s1 and the wide-character string pointed to by s2, ignoring case
       differences (towupper(3), towlower(3)).

RETURN VALUE top

       The wcscasecmp() function returns zero if the wide-character strings at s1
       and s2 are equal except for case distinctions.  It returns a positive
       integer if s1 is greater than s2, ignoring case.  It returns a negative
       integer if s1 is smaller than s2, ignoring case.

VERSIONS top

       The wcscasecmp() function is provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2008.  This function is not specified in POSIX.1-2001, and is not
       widely available on other systems.

NOTES top

       The behavior of wcscasecmp() depends on the LC_CTYPE category of the
       current locale.

SEE ALSO top

       strcasecmp(3), wcscmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-15                       WCSCASECMP(3)


wcscat(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSCAT(3)                    Linux Programmer's Manual                   WCSCAT(3)

NAME top

       wcscat - concatenate two wide-character strings

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcscat(wchar_t *dest, const wchar_t *src);

DESCRIPTION top

       The wcscat() function is the wide-character equivalent of the strcat(3)
       function.  It copies the wide-character string pointed to by src, including
       the terminating null wide character (L'\0'), to the end of the wide-
       character string pointed to by dest.

       The strings may not overlap.

       The programmer must ensure that there is room for at least wcslen(dest) +
       wcslen(src) + 1 wide characters at dest.

RETURN VALUE top

       wcscat() returns dest.

CONFORMING TO top

       C99.

SEE ALSO top

       strcat(3), wcpcpy(3), wcscpy(3), wcsncat(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           WCSCAT(3)


wcschr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSCHR(3)                    Linux Programmer's Manual                   WCSCHR(3)

NAME top

       wcschr - search a wide character in a wide-character string

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcschr(const wchar_t *wcs, wchar_t wc);

DESCRIPTION top

       The wcschr() function is the wide-character equivalent of the strchr(3)
       function.  It searches the first occurrence of wc in the wide-character
       string pointed to by wcs.

RETURN VALUE top

       The wcschr() function returns a pointer to the first occurrence of wc in
       the wide-character string pointed to by wcs, or NULL if wc does not occur
       in the string.

CONFORMING TO top

       C99.

SEE ALSO top

       strchr(3), wcspbrk(3), wcsrchr(3), wcsstr(3), wmemchr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           WCSCHR(3)


wcscmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSCMP(3)                    Linux Programmer's Manual                   WCSCMP(3)

NAME top

       wcscmp - compare two wide-character strings

SYNOPSIS top

       #include <wchar.h>

       int wcscmp(const wchar_t *s1, const wchar_t *s2);

DESCRIPTION top

       The wcscmp() function is the wide-character equivalent of the strcmp(3)
       function.  It compares the wide-character string pointed to by s1 and the
       wide-character string pointed to by s2.

RETURN VALUE top

       The wcscmp() function returns zero if the wide-character strings at s1 and
       s2 are equal.  It returns an integer greater than zero if at the first
       differing position i, the corresponding wide-character s1[i] is greater
       than s2[i].  It returns an integer less than zero if at the first differing
       position i, the corresponding wide-character s1[i] is less than s2[i].

CONFORMING TO top

       C99.

SEE ALSO top

       strcmp(3), wcscasecmp(3), wmemcmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           WCSCMP(3)


wcscpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSCPY(3)                    Linux Programmer's Manual                   WCSCPY(3)

NAME top

       wcscpy - copy a wide-character string

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcscpy(wchar_t *dest, const wchar_t *src);

DESCRIPTION top

       The wcscpy() function is the wide-character equivalent of the strcpy(3)
       function.  It copies the wide-character string pointed to by src, including
       the terminating null wide character (L'\0'), to the array pointed to by
       dest.

       The strings may not overlap.

       The programmer must ensure that there is room for at least wcslen(src)+1
       wide characters at dest.

RETURN VALUE top

       wcscpy() returns dest.

CONFORMING TO top

       C99.

SEE ALSO top

       strcpy(3), wcpcpy(3), wcscat(3), wcsdup(3), wmemcpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           WCSCPY(3)


wcscspn(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSCSPN(3)                   Linux Programmer's Manual                  WCSCSPN(3)

NAME top

       wcscspn  -  search a wide-character string for any of a set of wide charac-
       ters

SYNOPSIS top

       #include <wchar.h>

       size_t wcscspn(const wchar_t *wcs, const wchar_t *reject);

DESCRIPTION top

       The wcscspn() function is the wide-character equivalent of the strcspn(3)
       function.  It determines the length of the longest initial segment of wcs
       which consists entirely of wide-characters not listed in reject.  In other
       words, it searches for the first occurrence in the wide-character string
       wcs of any of the characters in the wide-character string reject.

RETURN VALUE top

       The wcscspn() function returns the number of wide characters in the longest
       initial segment of wcs which consists entirely of wide-characters not
       listed in reject.  In other words, it returns the position of the first
       occurrence in the wide-character string wcs of any of the characters in the
       wide-character string reject, or wcslen(wcs) if there is none.

CONFORMING TO top

       C99.

SEE ALSO top

       strcspn(3), wcspbrk(3), wcsspn(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WCSCSPN(3)


wcsdup(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSDUP(3)                    Linux Programmer's Manual                   WCSDUP(3)

NAME top

       wcsdup - duplicate a wide-character string

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcsdup(const wchar_t *s);

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

       wcsdup():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcsdup() function is the wide-character equivalent of the strdup(3)
       function.  It allocates and returns a new wide-character string whose
       initial contents is a duplicate of the wide-character string pointed to by
       s.

       Memory for the new wide-character string is obtained with malloc(3), and
       should be freed with free(3).

RETURN VALUE top

       The wcsdup() function returns a pointer to the new wide-character string,
       or NULL if sufficient memory was not available.

ERRORS top

       ENOMEM Insufficient memory available to allocate duplicate string.

CONFORMING TO top

       POSIX.1-2008.  This function is not specified in POSIX.1-2001, and is not
       widely available on other systems.

SEE ALSO top

       strdup(3), wcscpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-15                           WCSDUP(3)


wcslen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSLEN(3)                    Linux Programmer's Manual                   WCSLEN(3)

NAME top

       wcslen - determine the length of a wide-character string

SYNOPSIS top

       #include <wchar.h>

       size_t wcslen(const wchar_t *s);

DESCRIPTION top

       The wcslen() function is the wide-character equivalent of the strlen(3)
       function.  It determines the length of the wide-character string pointed to
       by s, excluding the terminating null wide character (L'\0').

RETURN VALUE top

       The wcslen() function returns the number of wide characters in s.

CONFORMING TO top

       C99.

SEE ALSO top

       strlen(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           WCSLEN(3)


wcsncasecmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCSNCASECMP(3)               Linux Programmer's Manual              WCSNCASECMP(3)

NAME top

       wcsncasecmp - compare two fixed-size wide-character strings, ignoring case

SYNOPSIS top

       #include <wchar.h>

       int wcsncasecmp(const wchar_t *s1, const wchar_t *s2, size_t n);

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

       wcsncasecmp():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcsncasecmp() function is the wide-character equivalent of the
       strncasecmp(3) function.  It compares the wide-character string pointed to
       by s1 and the wide-character string pointed to by s2, but at most n wide
       characters from each string, ignoring case differences (towupper(3),
       towlower(3)).

RETURN VALUE top

       The wcsncasecmp() function returns zero if the wide-character strings at s1
       and s2, truncated to at most length n, are equal except for case
       distinctions.  It returns a positive integer if truncated s1 is greater
       than truncated s2, ignoring case.  It returns a negative integer if
       truncated s1 is smaller than truncated s2, ignoring case.

VERSIONS top

       The wcsncasecmp() function is provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2008.  This function is not specified in POSIX.1-2001, and is not
       widely available on other systems.

NOTES top

       The behavior of wcsncasecmp() depends on the LC_CTYPE category of the
       current locale.

SEE ALSO top

       strncasecmp(3), wcsncmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-15                      WCSNCASECMP(3)


wcsncat(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSNCAT(3)                   Linux Programmer's Manual                  WCSNCAT(3)

NAME top

       wcsncat - concatenate two wide-character strings

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcsncat(wchar_t *dest, const wchar_t *src, size_t n);

DESCRIPTION top

       The wcsncat() function is the wide-character equivalent of the strncat(3)
       function.  It copies at most n wide characters from the wide-character
       string pointed to by src to the end of the wide-character string pointed to
       by dest, and adds a terminating null wide character (L'\0').

       The strings may not overlap.

       The programmer must ensure that there is room for at least wcslen(dest) + n
       + 1 wide characters at dest.

RETURN VALUE top

       wcsncat() returns dest.

CONFORMING TO top

       C99.

SEE ALSO top

       strncat(3), wcscat(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          WCSNCAT(3)


wcsncmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSNCMP(3)                   Linux Programmer's Manual                  WCSNCMP(3)

NAME top

       wcsncmp - compare two fixed-size wide-character strings

SYNOPSIS top

       #include <wchar.h>

       int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);

DESCRIPTION top

       The wcsncmp() function is the wide-character equivalent of the strncmp(3)
       function.  It compares the wide-character string pointed to by s1 and the
       wide-character string pointed to by s2, but at most n wide characters from
       each string.  In each string, the comparison extends only up to the first
       occurrence of a null wide character (L'\0'), if any.

RETURN VALUE top

       The wcsncmp() function returns zero if the wide-character strings at s1 and
       s2, truncated to at most length n, are equal.  It returns an integer
       greater than zero if at the first differing position i (i < n), the
       corresponding wide-character s1[i] is greater than s2[i].  It returns an
       integer less than zero if at the first differing position i (i < n), the
       corresponding wide-character s1[i] is less than s2[i].

CONFORMING TO top

       C99.

SEE ALSO top

       strncmp(3), wcsncasecmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          WCSNCMP(3)


wcsncpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSNCPY(3)                   Linux Programmer's Manual                  WCSNCPY(3)

NAME top

       wcsncpy - copy a fixed-size string of wide characters

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcsncpy(wchar_t *dest, const wchar_t *src, size_t n);

DESCRIPTION top

       The wcsncpy() function is the wide-character equivalent of the strncpy(3)
       function.  It copies at most n wide characters from the wide-character
       string pointed to by src, including the terminating null wide character
       (L'\0'), to the array pointed to by dest.  Exactly n wide characters are
       written at dest.  If the length wcslen(src) is smaller than n, the
       remaining wide characters in the array pointed to by dest are filled with
       null wide characters.  If the length wcslen(src) is greater or equal to n,
       the string pointed to by dest will not be terminated by a null wide
       character.

       The strings may not overlap.

       The programmer must ensure that there is room for at least n wide
       characters at dest.

RETURN VALUE top

       wcsncpy() returns dest.

CONFORMING TO top

       C99.

SEE ALSO top

       strncpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          WCSNCPY(3)


wcsnlen(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSNLEN(3)                   Linux Programmer's Manual                  WCSNLEN(3)

NAME top

       wcsnlen - determine the length of a fixed-size wide-character string

SYNOPSIS top

       #include <wchar.h>

       size_t wcsnlen(const wchar_t *s, size_t maxlen);

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

       wcsnlen():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcsnlen() function is the wide-character equivalent of the strnlen(3)
       function.  It returns the number of wide-characters in the string pointed
       to by s, not including the terminating null wide character (L'\0'), but at
       most maxlen wide characters (note: this parameter is not a byte count).  In
       doing this, wcsnlen() looks only at the first maxlen wide characters at s
       and never beyond s+maxlen.

RETURN VALUE top

       The wcsnlen() function returns wcslen(s), if that is less than maxlen, or
       maxlen if there is no null wide character among the first maxlen wide
       characters pointed to by s.

VERSIONS top

       The wcsnlen() function is provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2008.

SEE ALSO top

       strnlen(3), wcslen(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-01                          WCSNLEN(3)


wcsnrtombs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCSNRTOMBS(3)                Linux Programmer's Manual               WCSNRTOMBS(3)

NAME top

       wcsnrtombs - convert a wide-character string to a multibyte string

SYNOPSIS top

       #include <wchar.h>

       size_t wcsnrtombs(char *dest, const wchar_t **src, size_t nwc,
                         size_t len, mbstate_t *ps);

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

       wcsnrtombs():
           Since glibc 2.10:
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _GNU_SOURCE

DESCRIPTION top

       The wcsnrtombs() function is like the wcsrtombs(3) function, except that
       the number of wide characters to be converted, starting at *src, is limited
       to nwc.

       If dest is not a NULL pointer, the wcsnrtombs() function converts at most
       nwc wide characters from the wide-character string *src to a multibyte
       string starting at dest.  At most len bytes are written to dest.  The shift
       state *ps is updated.  The conversion is effectively performed by
       repeatedly calling wcrtomb(dest, *src, ps), as long as this call succeeds,
       and then incrementing dest by the number of bytes written and *src by one.
       The conversion can stop for three reasons:

       1. A wide character has been encountered that can not be represented as a
       multibyte sequence (according to the current locale).  In this case *src is
       left pointing to the invalid wide character, (size_t) -1 is returned, and
       errno is set to EILSEQ.

       2. nwc wide characters have been converted without encountering a null wide
       character (L'\0'), or the length limit forces a stop.  In this case *src is
       left pointing to the next wide character to be converted, and the number of
       bytes written to dest is returned.

       3. The wide-character string has been completely converted, including the
       terminating null wide character (which has the side effect of bringing back
       *ps to the initial state).  In this case *src is set to NULL, and the
       number of bytes written to dest, excluding the terminating null byte
       ('\0'), is returned.

       If dest is NULL, len is ignored, and the conversion proceeds as above,
       except that the converted bytes are not written out to memory, and that no
       destination length limit exists.

       In both of the above cases, if ps is a NULL pointer, a static anonymous
       state only known to the wcsnrtombs function is used instead.

       The programmer must ensure that there is room for at least len bytes at
       dest.

RETURN VALUE top

       The wcsnrtombs() function returns the number of bytes that make up the
       converted part of multibyte sequence, not including the terminating null
       byte.  If a wide character was encountered which could not be converted,
       (size_t) -1 is returned, and errno set to EILSEQ.

CONFORMING TO top

       POSIX.1-2008.

NOTES top

       The behavior of wcsnrtombs() depends on the LC_CTYPE category of the
       current locale.

       Passing NULL as ps is not multithread safe.

SEE ALSO top

       iconv(3), wcsrtombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-16                       WCSNRTOMBS(3)


wcspbrk(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSPBRK(3)                   Linux Programmer's Manual                  WCSPBRK(3)

NAME top

       wcspbrk  -  search a wide-character string for any of a set of wide charac-
       ters

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcspbrk(const wchar_t *wcs, const wchar_t *accept);

DESCRIPTION top

       The wcspbrk() function is the wide-character equivalent of the strpbrk(3)
       function.  It searches for the first occurrence in the wide-character
       string pointed to by wcs of any of the characters in the wide-character
       string pointed to by accept.

RETURN VALUE top

       The wcspbrk() function returns a pointer to the first occurrence in wcs of
       any of the characters listed in accept.  If wcs contains none of these
       characters, NULL is returned.

CONFORMING TO top

       C99.

SEE ALSO top

       strpbrk(3), wcschr(3), wcscspn(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WCSPBRK(3)


wcsrchr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSRCHR(3)                   Linux Programmer's Manual                  WCSRCHR(3)

NAME top

       wcsrchr - search a wide character in a wide-character string

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcsrchr(const wchar_t *wcs, wchar_t wc);

DESCRIPTION top

       The wcsrchr() function is the wide-character equivalent of the strrchr(3)
       function.  It searches the last occurrence of wc in the wide-character
       string pointed to by wcs.

RETURN VALUE top

       The wcsrchr() function returns a pointer to the last occurrence of wc in
       the wide-character string pointed to by wcs, or NULL if wc does not occur
       in the string.

CONFORMING TO top

       C99.

SEE ALSO top

       strrchr(3), wcschr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WCSRCHR(3)


wcsrtombs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCSRTOMBS(3)                 Linux Programmer's Manual                WCSRTOMBS(3)

NAME top

       wcsrtombs - convert a wide-character string to a multibyte string

SYNOPSIS top

       #include <wchar.h>

       size_t wcsrtombs(char *dest, const wchar_t **src,
                        size_t len, mbstate_t *ps);

DESCRIPTION top

       If dest is not a NULL pointer, the wcsrtombs() function converts the wide-
       character string *src to a multibyte string starting at dest.  At most len
       bytes are written to dest.  The shift state *ps is updated.  The conversion
       is effectively performed by repeatedly calling wcrtomb(dest, *src, ps), as
       long as this call succeeds, and then incrementing dest by the number of
       bytes written and *src by one.  The conversion can stop for three reasons:

       1. A wide character has been encountered that can not be represented as a
       multibyte sequence (according to the current locale).  In this case *src is
       left pointing to the invalid wide character, (size_t) -1 is returned, and
       errno is set to EILSEQ.

       2. The length limit forces a stop.  In this case *src is left pointing to
       the next wide character to be converted, and the number of bytes written to
       dest is returned.

       3. The wide-character string has been completely converted, including the
       terminating null wide character (L'\0'), which has the side effect of
       bringing back *ps to the initial state.  In this case *src is set to NULL,
       and the number of bytes written to dest, excluding the terminating null
       byte ('\0'), is returned.

       If dest is NULL, len is ignored, and the conversion proceeds as above,
       except that the converted bytes are not written out to memory, and that no
       length limit exists.

       In both of the above cases, if ps is a NULL pointer, a static anonymous
       state only known to the wcsrtombs function is used instead.

       The programmer must ensure that there is room for at least len bytes at
       dest.

RETURN VALUE top

       The wcsrtombs() function returns the number of bytes that make up the
       converted part of multibyte sequence, not including the terminating null
       byte.  If a wide character was encountered which could not be converted,
       (size_t) -1 is returned, and errno set to EILSEQ.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wcsrtombs() depends on the LC_CTYPE category of the current
       locale.

       Passing NULL as ps is not multithread safe.

SEE ALSO top

       iconv(3), wcsnrtombs(3), wcstombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-16                        WCSRTOMBS(3)


wcsspn(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSSPN(3)                    Linux Programmer's Manual                   WCSSPN(3)

NAME top

       wcsspn  - advance in a wide-character string, skipping any of a set of wide
       characters

SYNOPSIS top

       #include <wchar.h>

       size_t wcsspn(const wchar_t *wcs, const wchar_t *accept);

DESCRIPTION top

       The wcsspn() function is the wide-character equivalent of the strspn(3)
       function.  It determines the length of the longest initial segment of wcs
       which consists entirely of wide-characters listed in accept.  In other
       words, it searches for the first occurrence in the wide-character string
       wcs of a wide-character not contained in the wide-character string accept.

RETURN VALUE top

       The wcsspn() function returns the number of wide characters in the longest
       initial segment of wcs which consists entirely of wide-characters listed in
       accept.  In other words, it returns the position of the first occurrence in
       the wide-character string wcs of a wide-character not contained in the
       wide-character string accept, or wcslen(wcs) if there is none.

CONFORMING TO top

       C99.

SEE ALSO top

       strspn(3), wcscspn(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           WCSSPN(3)


wcsstr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSSTR(3)                    Linux Programmer's Manual                   WCSSTR(3)

NAME top

       wcsstr - locate a substring in a wide-character string

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcsstr(const wchar_t *haystack, const wchar_t *needle);

DESCRIPTION top

       The wcsstr() function is the wide-character equivalent of the strstr(3)
       function.  It searches for the first occurrence of the wide-character
       string needle (without its terminating null wide character (L'\0')) as a
       substring in the wide-character string haystack.

RETURN VALUE top

       The wcsstr() function returns a pointer to the first occurrence of needle
       in haystack.  It returns NULL if needle does not occur as a substring in
       haystack.

       Note the special case: If needle is the empty wide-character string, the
       return value is always haystack itself.

CONFORMING TO top

       C99.

SEE ALSO top

       strstr(3), wcschr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           WCSSTR(3)


wcstoimax(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WCSTOIMAX(3)                 Linux Programmer's Manual                WCSTOIMAX(3)

NAME top

       wcstoimax, wcstoumax - convert wide-character string to integer

SYNOPSIS top

       #include <stddef.h>
       #include <inttypes.h>

       intmax_t wcstoimax(const wchar_t *nptr, wchar_t **endptr, int base);
       uintmax_t wcstoumax(const wchar_t *nptr, wchar_t **endptr, int base);

DESCRIPTION top

       These functions are just like wcstol(3) and wcstoul(3), except that they
       return a value of type intmax_t and uintmax_t, respectively.

CONFORMING TO top

       C99.

SEE ALSO top

       imaxabs(3), imaxdiv(3), strtoimax(3), strtoumax(3), wcstol(3), wcstoul(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2003-11-01                        WCSTOIMAX(3)


wcstok(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

WCSTOK(3)                    Linux Programmer's Manual                   WCSTOK(3)

NAME top

       wcstok - split wide-character string into tokens

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wcstok(wchar_t *wcs, const wchar_t *delim, wchar_t **ptr);

DESCRIPTION top

       The wcstok() function is the wide-character equivalent of the strtok(3)
       function, with an added argument to make it multithread-safe.  It can be
       used to split a wide-character string wcs into tokens, where a token is
       defined as a substring not containing any wide-characters from delim.

       The search starts at wcs, if wcs is not NULL, or at *ptr, if wcs is NULL.
       First, any delimiter wide-characters are skipped, that is, the pointer is
       advanced beyond any wide-characters which occur in delim.  If the end of
       the wide-character string is now reached, wcstok() returns NULL, to
       indicate that no tokens were found, and stores an appropriate value in
       *ptr, so that subsequent calls to wcstok() will continue to return NULL.
       Otherwise, the wcstok() function recognizes the beginning of a token and
       returns a pointer to it, but before doing that, it zero-terminates the
       token by replacing the next wide-character which occurs in delim with a
       null wide character (L'\0'), and it updates *ptr so that subsequent calls
       will continue searching after the end of recognized token.

RETURN VALUE top

       The wcstok() function returns a pointer to the next token, or NULL if no
       further token was found.

CONFORMING TO top

       C99.

NOTES top

       The original wcs wide-character string is destructively modified during the
       operation.

EXAMPLE top

       The following code loops over the tokens contained in a wide-character
       string.

       wchar_t *wcs = ...;
       wchar_t *token;
       wchar_t *state;
       for (token = wcstok(wcs, " \t\n", &state);
           token != NULL;
           token = wcstok(NULL, " \t\n", &state)) {
           ...
       }

SEE ALSO top

       strtok(3), wcschr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                           WCSTOK(3)


wcstombs(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCSTOMBS(3)                  Linux Programmer's Manual                 WCSTOMBS(3)

NAME top

       wcstombs - convert a wide-character string to a multibyte string

SYNOPSIS top

       #include <stdlib.h>

       size_t wcstombs(char *dest, const wchar_t *src, size_t n);

DESCRIPTION top

       If dest is not a NULL pointer, the wcstombs() function converts the wide-
       character string src to a multibyte string starting at dest.  At most n
       bytes are written to dest.  The conversion starts in the initial state.
       The conversion can stop for three reasons:

       1. A wide character has been encountered that can not be represented as a
       multibyte sequence (according to the current locale).  In this case
       (size_t) -1 is returned.

       2. The length limit forces a stop.  In this case the number of bytes
       written to dest is returned, but the shift state at this point is lost.

       3. The wide-character string has been completely converted, including the
       terminating null wide character (L'\0').  In this case the conversion ends
       in the initial state.  The number of bytes written to dest, excluding the
       terminating null byte ('\0'), is returned.

       The programmer must ensure that there is room for at least n bytes at dest.

       If dest is NULL, n is ignored, and the conversion proceeds as above, except
       that the converted bytes are not written out to memory, and that no length
       limit exists.

       In order to avoid the case 2 above, the programmer should make sure n is
       greater or equal to wcstombs(NULL,src,0)+1.

RETURN VALUE top

       The wcstombs() function returns the number of bytes that make up the
       converted part of multibyte sequence, not including the terminating null
       byte.  If a wide character was encountered which could not be converted,
       (size_t) -1 is returned.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wcstombs() depends on the LC_CTYPE category of the current
       locale.

       The function wcsrtombs(3) provides a thread safe interface to the same
       functionality.

SEE ALSO top

       mbstowcs(3), wcsrtombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-10-16                         WCSTOMBS(3)


wcswidth(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCSWIDTH(3)                  Linux Programmer's Manual                 WCSWIDTH(3)

NAME top

       wcswidth - determine columns needed for a fixed-size wide-character string

SYNOPSIS top

       #define _XOPEN_SOURCE             /* See feature_test_macros(7) */
       #include <wchar.h>

       int wcswidth(const wchar_t *s, size_t n);

DESCRIPTION top

       The wcswidth() function returns the number of columns needed to represent
       the wide-character string pointed to by s, but at most n wide characters.
       If a nonprintable wide character occurs among these characters, -1 is
       returned.

RETURN VALUE top

       The wcswidth() function returns the number of column positions for the
       wide-character string s, truncated to at most length n.

CONFORMING TO top

       POSIX.1-2001.

NOTES top

       The behavior of wcswidth() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       iswprint(3), wcwidth(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2010-09-10                         WCSWIDTH(3)


wctob(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCTOB(3)                     Linux Programmer's Manual                    WCTOB(3)

NAME top

       wctob - try to represent a wide character as a single byte

SYNOPSIS top

       #include <wchar.h>

       int wctob(wint_t c);

DESCRIPTION top

       The wctob() function tests whether the multibyte representation of the wide
       character c, starting in the initial state, consists of a single byte.  If
       so, it is returned as an unsigned char.

       Never use this function.  It cannot help you in writing internationalized
       programs.  Internationalized programs must never distinguish single-byte
       and multibyte characters.

RETURN VALUE top

       The wctob() function returns the single-byte representation of c, if it
       exists, of EOF otherwise.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wctob() depends on the LC_CTYPE category of the current
       locale.

       This function should never be used.  Internationalized programs must never
       distinguish single-byte and multibyte characters.  Use either wctomb(3) or
       the thread-safe wcrtomb(3) instead.

SEE ALSO top

       btowc(3), wcrtomb(3), wctomb(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-22                            WCTOB(3)


wctomb(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCTOMB(3)                    Linux Programmer's Manual                   WCTOMB(3)

NAME top

       wctomb - convert a wide character to a multibyte sequence

SYNOPSIS top

       #include <stdlib.h>

       int wctomb(char *s, wchar_t wc);

DESCRIPTION top

       If s is not NULL, the wctomb() function converts the wide character wc to
       its multibyte representation and stores it at the beginning of the
       character array pointed to by s.  It updates the shift state, which is
       stored in a static anonymous variable only known to the wctomb function,
       and returns the length of said multibyte representation, that is, the
       number of bytes written at s.

       The programmer must ensure that there is room for at least MB_CUR_MAX bytes
       at s.

       If s is NULL, the wctomb() function resets the shift state, only known to
       this function, to the initial state, and returns nonzero if the encoding
       has nontrivial shift state, or zero if the encoding is stateless.

RETURN VALUE top

       If s is not NULL, the wctomb() function returns the number of bytes that
       have been written to the byte array at s.  If wc can not be represented as
       a multibyte sequence (according to the current locale), -1 is returned.

       If s is NULL, the wctomb() function returns nonzero if the encoding has
       nontrivial shift state, or zero if the encoding is stateless.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wctomb() depends on the LC_CTYPE category of the current
       locale.

       This function is not multithread safe.  The function wcrtomb(3) provides a
       better interface to the same functionality.

SEE ALSO top

       MB_CUR_MAX(3), wcrtomb(3), wcstombs(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           WCTOMB(3)


wctrans(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCTRANS(3)                   Linux Programmer's Manual                  WCTRANS(3)

NAME top

       wctrans - wide-character translation mapping

SYNOPSIS top

       #include <wctype.h>

       wctrans_t wctrans(const char *name);

DESCRIPTION top

       The wctrans_t type represents a mapping which can map a wide character to
       another wide character.  Its nature is implementation-dependent, but the
       special value (wctrans_t) 0 denotes an invalid mapping.  Nonzero wctrans_t
       values can be passed to the towctrans(3) function to actually perform the
       wide-character mapping.

       The wctrans() function returns a mapping, given by its name.  The set of
       valid names depends on the LC_CTYPE category of the current locale, but the
       following names are valid in all locales.
         "tolower" - realizes the tolower(3) mapping
         "toupper" - realizes the toupper(3) mapping

RETURN VALUE top

       The wctrans() function returns a mapping descriptor if the name is valid.
       Otherwise it returns (wctrans_t) 0.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wctrans() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       towctrans(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WCTRANS(3)


wctype(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCTYPE(3)                    Linux Programmer's Manual                   WCTYPE(3)

NAME top

       wctype - wide-character classification

SYNOPSIS top

       #include <wctype.h>

       wctype_t wctype(const char *name);

DESCRIPTION top

       The wctype_t type represents a property which a wide character may or may
       not have.  In other words, it represents a class of wide characters.  This
       type's nature is implementation-dependent, but the special value (wctype_t)
       0 denotes an invalid property.  Nonzero wctype_t values can be passed to
       the iswctype(3) function to actually test whether a given wide character
       has the property.

       The wctype() function returns a property, given by its name.  The set of
       valid names depends on the LC_CTYPE category of the current locale, but the
       following names are valid in all locales.
         "alnum" - realizes the isalnum(3) classification function
         "alpha" - realizes the isalpha(3) classification function
         "blank" - realizes the isblank(3) classification function
         "cntrl" - realizes the iscntrl(3) classification function
         "digit" - realizes the isdigit(3) classification function
         "graph" - realizes the isgraph(3) classification function
         "lower" - realizes the islower(3) classification function
         "print" - realizes the isprint(3) classification function
         "punct" - realizes the ispunct(3) classification function
         "space" - realizes the isspace(3) classification function
         "upper" - realizes the isupper(3) classification function
         "xdigit" - realizes the isxdigit(3) classification function

RETURN VALUE top

       The wctype() function returns a property descriptor if the name is valid.
       Otherwise it returns (wctype_t) 0.

CONFORMING TO top

       C99.

NOTES top

       The behavior of wctype() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       iswctype(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                           WCTYPE(3)


wcwidth(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WCWIDTH(3)                   Linux Programmer's Manual                  WCWIDTH(3)

NAME top

       wcwidth - determine columns needed for a wide character

SYNOPSIS top

       #define _XOPEN_SOURCE       /* See feature_test_macros(7) */
       #include <wchar.h>

       int wcwidth(wchar_t c);

DESCRIPTION top

       The wcwidth() function returns the number of columns needed to represent
       the wide character c.  If c is a printable wide character, the value is at
       least 0.  If c is null wide character (L'\0'), the value is 0.  Otherwise
       -1 is returned.

RETURN VALUE top

       The wcwidth() function returns the number of column positions for c.

CONFORMING TO top

       POSIX.1-2001.

       Note that glibc before 2.2.5 used the prototype
       int wcwidth(wint_t c);

NOTES top

       The behavior of wcwidth() depends on the LC_CTYPE category of the current
       locale.

SEE ALSO top

       iswprint(3), wcswidth(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 2011-09-28                          WCWIDTH(3)


wmemchr(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WMEMCHR(3)                   Linux Programmer's Manual                  WMEMCHR(3)

NAME top

       wmemchr - search a wide character in a wide-character array

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);

DESCRIPTION top

       The wmemchr() function is the wide-character equivalent of the memchr(3)
       function.  It searches the n wide characters starting at s for the first
       occurrence of the wide character c.

RETURN VALUE top

       The wmemchr() function returns a pointer to the first occurrence of c among
       the n wide characters starting at s, or NULL if c does not occur among
       these.

CONFORMING TO top

       C99.

SEE ALSO top

       memchr(3), wcschr(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WMEMCHR(3)


wmemcmp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WMEMCMP(3)                   Linux Programmer's Manual                  WMEMCMP(3)

NAME top

       wmemcmp - compare two arrays of wide-characters

SYNOPSIS top

       #include <wchar.h>

       int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);

DESCRIPTION top

       The wmemcmp() function is the wide-character equivalent of the memcmp(3)
       function.  It compares the n wide-characters starting at s1 and the n wide-
       characters starting at s2.

RETURN VALUE top

       The wmemcmp() function returns zero if the wide-character arrays of size n
       at s1 and s2 are equal.  It returns an integer greater than zero if at the
       first differing position i (i < n), the corresponding wide-character s1[i]
       is greater than s2[i].  It returns an integer less than zero if at the
       first differing position i (i < n), the corresponding wide-character s1[i]
       is less than s2[i].

CONFORMING TO top

       C99.

SEE ALSO top

       memcmp(3), wcscmp(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WMEMCMP(3)


wmemcpy(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WMEMCPY(3)                   Linux Programmer's Manual                  WMEMCPY(3)

NAME top

       wmemcpy - copy an array of wide-characters

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wmemcpy(wchar_t *dest, const wchar_t *src, size_t n);

DESCRIPTION top

       The wmemcpy() function is the wide-character equivalent of the memcpy(3)
       function.  It copies n wide characters from the array starting at src to
       the array starting at dest.

       The arrays may not overlap; use wmemmove(3) to copy between overlapping
       arrays.

       The programmer must ensure that there is room for at least n wide
       characters at dest.

RETURN VALUE top

       wmemcpy() returns dest.

CONFORMING TO top

       C99.

SEE ALSO top

       memcpy(3), wcscpy(3), wmemmove(3), wmempcpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WMEMCPY(3)


wmemmove(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WMEMMOVE(3)                  Linux Programmer's Manual                 WMEMMOVE(3)

NAME top

       wmemmove - copy an array of wide-characters

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wmemmove(wchar_t *dest, const wchar_t *src, size_t n);

DESCRIPTION top

       The wmemmove() function is the wide-character equivalent of the memmove(3)
       function.  It copies n wide characters from the array starting at src to
       the array starting at dest.  The arrays may overlap.

       The programmer must ensure that there is room for at least n wide
       characters at dest.

RETURN VALUE top

       wmemmove() returns dest.

CONFORMING TO top

       C99.

SEE ALSO top

       memmove(3), wmemcpy(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                         WMEMMOVE(3)


wmemset(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON The Linux Programming Interface

WMEMSET(3)                   Linux Programmer's Manual                  WMEMSET(3)

NAME top

       wmemset - fill an array of wide-characters with a constant wide character

SYNOPSIS top

       #include <wchar.h>

       wchar_t *wmemset(wchar_t *wcs, wchar_t wc, size_t n);

DESCRIPTION top

       The wmemset() function is the wide-character equivalent of the memset(3)
       function.  It fills the array of n wide-characters starting at wcs with n
       copies of the wide character wc.

RETURN VALUE top

       wmemset() returns wcs.

CONFORMING TO top

       C99.

SEE ALSO top

       memset(3)

COLOPHON top

       This page is part of release 3.45 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/.

GNU                                 1999-07-25                          WMEMSET(3)


wordexp(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

WORDEXP(3)                   Linux Programmer's Manual                  WORDEXP(3)

NAME top

       wordexp, wordfree - perform word expansion like a posix-shell

SYNOPSIS top

       #include <wordexp.h>

       int wordexp(const char *s, wordexp_t *p, int flags);

       void wordfree(wordexp_t *p);

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

       wordexp(), wordfree(): _XOPEN_SOURCE

DESCRIPTION top

       The function wordexp() performs a shell-like expansion of the string s and
       returns the result in the structure pointed to by p.  The data type
       wordexp_t is a structure that at least has the fields we_wordc, we_wordv,
       and we_offs.  The field we_wordc is a size_t that gives the number of words
       in the expansion of s.  The field we_wordv is a char ** that points to the
       array of words found.  The field we_offs of type size_t is sometimes
       (depending on flags, see below) used to indicate the number of initial
       elements in the we_wordv array that should be filled with NULLs.

       The function wordfree() frees the allocated memory again.  More precisely,
       it does not free its argument, but it frees the array we_wordv and the
       strings that points to.

The string argument

       Since the expansion is the same as the expansion by the shell (see sh(1))
       of the parameters to a command, the string s must not contain characters
       that would be illegal in shell command parameters.  In particular, there
       must not be any unescaped newline or |, &, ;, <, >, (, ), {, } characters
       outside a command substitution or parameter substitution context.

       If the argument s contains a word that starts with an unquoted comment
       character #, then it is unspecified whether that word and all following
       words are ignored, or the # is treated as a non-comment character.

The expansion

       The expansion done consists of the following stages: tilde expansion
       (replacing ~user by user's home directory), variable substitution
       (replacing $FOO by the value of the environment variable FOO), command
       substitution (replacing $(command) or `command` by the output of command),
       arithmetic expansion, field splitting, wildcard expansion, quote removal.

       The result of expansion of special parameters ($@, $*, $#, $?, $-, $$, $!,
       $0) is unspecified.

       Field splitting is done using the environment variable $IFS.  If it is not
       set, the field separators are space, tab and newline.

The output array

       The array we_wordv contains the words found, followed by a NULL.

The flags argument

       The flag argument is a bitwise inclusive OR of the following values:

       WRDE_APPEND
              Append the words found to the array resulting from a previous call.

       WRDE_DOOFFS
              Insert we_offs initial NULLs in the array we_wordv.  (These are not
              counted in the returned we_wordc.)

       WRDE_NOCMD
              Don't do command substitution.

       WRDE_REUSE
              The argument p resulted from a previous call to wordexp(), and
              wordfree() was not called.  Reuse the allocated storage.

       WRDE_SHOWERR
              Normally during command substitution stderr is redirected to
              /dev/null.  This flag specifies that stderr is not to be redirected.

       WRDE_UNDEF
              Consider it an error if an undefined shell variable is expanded.

RETURN VALUE top

       In case of success 0 is returned.  In case of error one of the following
       five values is returned.

       WRDE_BADCHAR
              Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.

       WRDE_BADVAL
              An undefined shell variable was referenced, and the WRDE_UNDEF flag
              told us to consider this an error.

       WRDE_CMDSUB
              Command substitution occurred, and the WRDE_NOCMD flag told us to
              consider this an error.

       WRDE_NOSPACE
              Out of memory.

       WRDE_SYNTAX
              Shell syntax error, such as unbalanced parentheses or unmatched
              quotes.

VERSIONS top

       wordexp() and wordfree() are provided in glibc since version 2.1.

CONFORMING TO top

       POSIX.1-2001.

EXAMPLE top

       The output of the following example program is approximately that of "ls
       [a-c]*.c".

       #include <stdio.h>
       #include <stdlib.h>
       #include <wordexp.h>

       int
       main(int argc, char **argv)
       {
           wordexp_t p;
           char **w;
           int i;

           wordexp("[a-c]*.c", &p, 0);
           w = p.we_wordv;
           for (i = 0; i < p.we_wordc; i++)
               printf("%s\n", w[i]);
           wordfree(&p);
           exit(EXIT_SUCCESS);
       }

SEE ALSO top

       fnmatch(3), glob(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-07-14                          WORDEXP(3)


write(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

WRITE(2)                     Linux Programmer's Manual                    WRITE(2)

NAME top

       write - write to a file descriptor

SYNOPSIS top

       #include <unistd.h>

       ssize_t write(int fd, const void *buf, size_t count);

DESCRIPTION top

       write() writes up to count bytes from the buffer pointed buf to the file
       referred to by the file descriptor fd.

       The number of bytes written may be less than count if, for example, there
       is insufficient space on the underlying physical medium, or the
       RLIMIT_FSIZE resource limit is encountered (see setrlimit(2)), or the call
       was interrupted by a signal handler after having written less than count
       bytes.  (See also pipe(7).)

       For a seekable file (i.e., one to which lseek(2) may be applied, for
       example, a regular file) writing takes place at the current file offset,
       and the file offset is incremented by the number of bytes actually written.
       If the file was open(2)ed with O_APPEND, the file offset is first set to
       the end of the file before writing.  The adjustment of the file offset and
       the write operation are performed as an atomic step.

       POSIX requires that a read(2) which can be proved to occur after a write()
       has returned returns the new data.  Note that not all file systems are
       POSIX conforming.

RETURN VALUE top

       On success, the number of bytes written is returned (zero indicates nothing
       was written).  On error, -1 is returned, and errno is set appropriately.

       If count is zero and fd refers to a regular file, then write() may return a
       failure status if one of the errors below is detected.  If no errors are
       detected, 0 will be returned without causing any other effect.  If count is
       zero and fd refers to a file other than a regular file, the results are not
       specified.

ERRORS top

       EAGAIN The file descriptor fd refers to a file other than a socket and has
              been marked nonblocking (O_NONBLOCK), and the write would block.

       EAGAIN or EWOULDBLOCK
              The file descriptor fd refers to a socket and has been marked
              nonblocking (O_NONBLOCK), and the write would block.  POSIX.1-2001
              allows either error to be returned for this case, and does not
              require these constants to have the same value, so a portable
              application should check for both possibilities.

       EBADF  fd is not a valid file descriptor or is not open for writing.

       EDESTADDRREQ
              fd refers to a datagram socket for which a peer address has not been
              set using connect(2).

       EFAULT buf is outside your accessible address space.

       EFBIG  An attempt was made to write a file that exceeds the implementation-
              defined maximum file size or the process's file size limit, or to
              write at a position past the maximum allowed offset.

       EINTR  The call was interrupted by a signal before any data was written;
              see signal(7).

       EINVAL fd is attached to an object which is unsuitable for writing; or the
              file was opened with the O_DIRECT flag, and either the address
              specified in buf, the value specified in count, or the current file
              offset is not suitably aligned.

       EIO    A low-level I/O error occurred while modifying the inode.

       ENOSPC The device containing the file referred to by fd has no room for the
              data.

       EPIPE  fd is connected to a pipe or socket whose reading end is closed.
              When this happens the writing process will also receive a SIGPIPE
              signal.  (Thus, the write return value is seen only if the program
              catches, blocks or ignores this signal.)

       Other errors may occur, depending on the object connected to fd.

CONFORMING TO top

       SVr4, 4.3BSD, POSIX.1-2001.

       Under SVr4 a write may be interrupted and return EINTR at any point, not
       just before any data is written.

NOTES top

       A successful return from write() does not make any guarantee that data has
       been committed to disk.  In fact, on some buggy implementations, it does
       not even guarantee that space has successfully been reserved for the data.
       The only way to be sure is to call fsync(2) after you are done writing all
       your data.

       If a write() is interrupted by a signal handler before any bytes are
       written, then the call fails with the error EINTR; if it is interrupted
       after at least one byte has been written, the call succeeds, and returns
       the number of bytes written.

SEE ALSO top

       close(2), fcntl(2), fsync(2), ioctl(2), lseek(2), open(2), pwrite(2),
       read(2), select(2), writev(2), fwrite(3)

COLOPHON top

       This page is part of release 3.45 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                               2010-08-29                            WRITE(2)


x25(7) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | VERSIONS | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

X25(7)                       Linux Programmer's Manual                      X25(7)

NAME top

       x25 - ITU-T X.25 / ISO-8208 protocol interface.

SYNOPSIS top

       #include <sys/socket.h>
       #include <linux/x25.h>

       x25_socket = socket(AF_X25, SOCK_SEQPACKET, 0);

DESCRIPTION top

       X25 sockets provide an interface to the X.25 packet layer protocol.  This
       allows applications to communicate over a public X.25 data network as
       standardized by International Telecommunication Union's recommendation X.25
       (X.25 DTE-DCE mode).  X25 sockets can also be used for communication
       without an intermediate X.25 network (X.25 DTE-DTE mode) as described in
       ISO-8208.

       Message boundaries are preserved -- a read(2) from a socket will retrieve
       the same chunk of data as output with the corresponding write(2) to the
       peer socket.  When necessary, the kernel takes care of segmenting and
       reassembling long messages by means of the X.25 M-bit.  There is no hard-
       coded upper limit for the message size.  However, reassembling of a long
       message might fail if there is a temporary lack of system resources or when
       other constraints (such as socket memory or buffer size limits) become
       effective.  If that occurs, the X.25 connection will be reset.

Socket Addresses

       The AF_X25 socket address family uses the struct sockaddr_x25 for
       representing network addresses as defined in ITU-T recommendation X.121.

           struct sockaddr_x25 {
               sa_family_t sx25_family;    /* must be AF_X25 */
               x25_address sx25_addr;      /* X.121 Address */
           };

       sx25_addr contains a char array x25_addr[] to be interpreted as a null-
       terminated string.  sx25_addr.x25_addr[] consists of up to 15 (not counting
       the terminating 0) ASCII characters forming the X.121 address.  Only the
       decimal digit characters from '0' to '9' are allowed.

Socket Options

       The following X.25-specific socket options can be set by using
       setsockopt(2) and read with getsockopt(2) with the level argument set to
       SOL_X25.

       X25_QBITINCL
              Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible
              by the user.  It expects an integer argument.  If set to 0
              (default), the Q-bit is never set for outgoing packets and the Q-bit
              of incoming packets is ignored.  If set to 1, an additional first
              byte is prepended to each message read from or written to the
              socket.  For data read from the socket, a 0 first byte indicates
              that the Q-bits of the corresponding incoming data packets were not
              set.  A first byte with value 1 indicates that the Q-bit of the
              corresponding incoming data packets was set.  If the first byte of
              the data written to the socket is 1 the Q-bit of the corresponding
              outgoing data packets will be set.  If the first byte is 0 the Q-bit
              will not be set.

VERSIONS top

       The AF_X25 protocol family is a new feature of Linux 2.2.

BUGS top

       Plenty, as the X.25 PLP implementation is CONFIG_EXPERIMENTAL.

       This man page is incomplete.

       There is no dedicated application programmer's header file yet; you need to
       include the kernel header file <linux/x25.h>.  CONFIG_EXPERIMENTAL might
       also imply that future versions of the interface are not binary compatible.

       X.25 N-Reset events are not propagated to the user process yet.  Thus, if a
       reset occurred, data might be lost without notice.

SEE ALSO top

       socket(2), socket(7)

       Jonathan Simon Naylor: "The Re-Analysis and Re-Implementation of X.25."
       The URL is <ftp://ftp.pspt.fi/pub/ham/linux/ax25/x25doc.tgz>.

COLOPHON top

       This page is part of release 3.45 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                               2012-08-05                              X25(7)


xdr(3) - Linux manual page

NAME | SYNOPSIS AND DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

XDR(3)                       Linux Programmer's Manual                      XDR(3)

NAME top

       xdr - library routines for external data representation

SYNOPSIS AND DESCRIPTION top

       These routines allow C programmers to describe arbitrary data structures in
       a machine-independent fashion.  Data for remote procedure calls are
       transmitted using these routines.

       The prototypes below are declared in <rpc/xdr.h> and make use of the
       following types:

           typedef int bool_t;

           typedef bool_t (*xdrproc_t) (XDR *, void *,...);

       For the declaration of the XDR type, see <rpc/xdr.h>.

       bool_t xdr_array(XDR *xdrs, char **arrp, unsigned int *sizep,
                        unsigned int maxsize, unsigned int elsize,
                        xdrproc_t elproc);

              A filter primitive that translates between variable-length arrays
              and their corresponding external representations.  The argument arrp
              is the address of the pointer to the array, while sizep is the
              address of the element count of the array; this element count cannot
              exceed maxsize.  The argument elsize is the sizeof each of the
              array's elements, and elproc is an XDR filter that translates
              between the array elements' C form, and their external
              representation.  This routine returns one if it succeeds, zero
              otherwise.

       bool_t xdr_bool(XDR *xdrs, bool_t *bp);

              A filter primitive that translates between booleans (C integers) and
              their external representations.  When encoding data, this filter
              produces values of either one or zero.  This routine returns one if
              it succeeds, zero otherwise.

       bool_t xdr_bytes(XDR *xdrs, char **sp, unsigned int *sizep,
                        unsigned int maxsize);

              A filter primitive that translates between counted byte strings and
              their external representations.  The argument sp is the address of
              the string pointer.  The length of the string is located at address
              sizep; strings cannot be longer than maxsize.  This routine returns
              one if it succeeds, zero otherwise.

       bool_t xdr_char(XDR *xdrs, char *cp);

              A filter primitive that translates between C characters and their
              external representations.  This routine returns one if it succeeds,
              zero otherwise.  Note: encoded characters are not packed, and occupy
              4 bytes each.  For arrays of characters, it is worthwhile to
              consider xdr_bytes(), xdr_opaque() or xdr_string().

       void xdr_destroy(XDR *xdrs);

              A macro that invokes the destroy routine associated with the XDR
              stream, xdrs.  Destruction usually involves freeing private data
              structures associated with the stream.  Using xdrs after invoking
              xdr_destroy() is undefined.

       bool_t xdr_double(XDR *xdrs, double *dp);

              A filter primitive that translates between C double precision
              numbers and their external representations.  This routine returns
              one if it succeeds, zero otherwise.

       bool_t xdr_enum(XDR *xdrs, enum_t *ep);

              A filter primitive that translates between C enums (actually
              integers) and their external representations.  This routine returns
              one if it succeeds, zero otherwise.

       bool_t xdr_float(XDR *xdrs, float *fp);

              A filter primitive that translates between C floats and their
              external representations.  This routine returns one if it succeeds,
              zero otherwise.

       void xdr_free(xdrproc_t proc, char *objp);

              Generic freeing routine.  The first argument is the XDR routine for
              the object being freed.  The second argument is a pointer to the
              object itself.  Note: the pointer passed to this routine is not
              freed, but what it points to is freed (recursively).

       unsigned int xdr_getpos(XDR *xdrs);

              A macro that invokes the get-position routine associated with the
              XDR stream, xdrs.  The routine returns an unsigned integer, which
              indicates the position of the XDR byte stream.  A desirable feature
              of XDR streams is that simple arithmetic works with this number,
              although the XDR stream instances need not guarantee this.

       long *xdr_inline(XDR *xdrs, int len);

              A macro that invokes the inline routine associated with the XDR
              stream, xdrs.  The routine returns a pointer to a contiguous piece
              of the stream's buffer; len is the byte length of the desired
              buffer.  Note: pointer is cast to long *.

              Warning: xdr_inline() may return NULL (0) if it cannot allocate a
              contiguous piece of a buffer.  Therefore the behavior may vary among
              stream instances; it exists for the sake of efficiency.

       bool_t xdr_int(XDR *xdrs, int *ip);

              A filter primitive that translates between C integers and their
              external representations.  This routine returns one if it succeeds,
              zero otherwise.

       bool_t xdr_long(XDR *xdrs, long *lp);

              A filter primitive that translates between C long integers and their
              external representations.  This routine returns one if it succeeds,
              zero otherwise.

       void xdrmem_create(XDR *xdrs, char *addr, unsigned int size,
                          enum xdr_op op);

              This routine initializes the XDR stream object pointed to by xdrs.
              The stream's data is written to, or read from, a chunk of memory at
              location addr whose length is no more than size bytes long.  The op
              determines the direction of the XDR stream (either XDR_ENCODE,
              XDR_DECODE, or XDR_FREE).

       bool_t xdr_opaque(XDR *xdrs, char *cp, unsigned int cnt);

              A filter primitive that translates between fixed size opaque data
              and its external representation.  The argument cp is the address of
              the opaque object, and cnt is its size in bytes.  This routine
              returns one if it succeeds, zero otherwise.

       bool_t xdr_pointer(XDR *xdrs, char **objpp,
                          unsigned int objsize, xdrproc_t xdrobj);

              Like xdr_reference() except that it serializes NULL pointers,
              whereas xdr_reference() does not.  Thus, xdr_pointer() can represent
              recursive data structures, such as binary trees or linked lists.

       void xdrrec_create(XDR *xdrs, unsigned int sendsize,
                          unsigned int recvsize, char *handle,
                          int (*readit) (char *, char *, int),
                          int (*writeit) (char *, char *, int));

              This routine initializes the XDR stream object pointed to by xdrs.
              The stream's data is written to a buffer of size sendsize; a value
              of zero indicates the system should use a suitable default.  The
              stream's data is read from a buffer of size recvsize; it too can be
              set to a suitable default by passing a zero value.  When a stream's
              output buffer is full, writeit is called.  Similarly, when a
              stream's input buffer is empty, readit is called.  The behavior of
              these two routines is similar to the system calls read(2) and
              write(2), except that handle is passed to the former routines as the
              first argument.  Note: the XDR stream's op field must be set by the
              caller.

              Warning: this XDR stream implements an intermediate record stream.
              Therefore there are additional bytes in the stream to provide record
              boundary information.

       bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);

              This routine can be invoked only on streams created by
              xdrrec_create().  The data in the output buffer is marked as a
              completed record, and the output buffer is optionally written out if
              sendnow is nonzero.  This routine returns one if it succeeds, zero
              otherwise.

       bool_t xdrrec_eof(XDR *xdrs);

              This routine can be invoked only on streams created by
              xdrrec_create().  After consuming the rest of the current record in
              the stream, this routine returns one if the stream has no more
              input, zero otherwise.

       bool_t xdrrec_skiprecord(XDR *xdrs);

              This routine can be invoked only on streams created by
              xdrrec_create().  It tells the XDR implementation that the rest of
              the current record in the stream's input buffer should be discarded.
              This routine returns one if it succeeds, zero otherwise.

       bool_t xdr_reference(XDR *xdrs, char **pp, unsigned int size,
                            xdrproc_t proc);

              A primitive that provides pointer chasing within structures.  The
              argument pp is the address of the pointer; size is the sizeof the
              structure that *pp points to; and proc is an XDR procedure that
              filters the structure between its C form and its external
              representation.  This routine returns one if it succeeds, zero
              otherwise.

              Warning: this routine does not understand NULL pointers.  Use
              xdr_pointer() instead.

       xdr_setpos(XDR *xdrs, unsigned int pos);

              A macro that invokes the set position routine associated with the
              XDR stream xdrs.  The argument pos is a position value obtained from
              xdr_getpos().  This routine returns one if the XDR stream could be
              repositioned, and zero otherwise.

              Warning: it is difficult to reposition some types of XDR streams, so
              this routine may fail with one type of stream and succeed with
              another.

       bool_t xdr_short(XDR *xdrs, short *sp);

              A filter primitive that translates between C short integers and
              their external representations.  This routine returns one if it
              succeeds, zero otherwise.

       void xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op);

              This routine initializes the XDR stream object pointed to by xdrs.
              The XDR stream data is written to, or read from, the stdio stream
              file.  The argument op determines the direction of the XDR stream
              (either XDR_ENCODE, XDR_DECODE, or XDR_FREE).

              Warning: the destroy routine associated with such XDR streams calls
              fflush(3) on the file stream, but never fclose(3).

       bool_t xdr_string(XDR *xdrs, char **sp, unsigned int maxsize);

              A filter primitive that translates between C strings and their
              corresponding external representations.  Strings cannot be longer
              than maxsize.  Note: sp is the address of the string's pointer.
              This routine returns one if it succeeds, zero otherwise.

       bool_t xdr_u_char(XDR *xdrs, unsigned char *ucp);

              A filter primitive that translates between unsigned C characters and
              their external representations.  This routine returns one if it
              succeeds, zero otherwise.

       bool_t xdr_u_int(XDR *xdrs, unsigned *up);

              A filter primitive that translates between C unsigned integers and
              their external representations.  This routine returns one if it
              succeeds, zero otherwise.

       bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);

              A filter primitive that translates between C unsigned long integers
              and their external representations.  This routine returns one if it
              succeeds, zero otherwise.

       bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);

              A filter primitive that translates between C unsigned short integers
              and their external representations.  This routine returns one if it
              succeeds, zero otherwise.

       bool_t xdr_union(XDR *xdrs, int *dscmp, char *unp,
                        struct xdr_discrim *choices,
                        xdrproc_t defaultarm);     /* may equal NULL */

              A filter primitive that translates between a discriminated C union
              and its corresponding external representation.  It first translates
              the discriminant of the union located at dscmp.  This discriminant
              is always an enum_t.  Next the union located at unp is translated.
              The argument choices is a pointer to an array of xdr_discrim()
              structures.  Each structure contains an ordered pair of
              [value,proc].  If the union's discriminant is equal to the
              associated value, then the proc is called to translate the union.
              The end of the xdr_discrim() structure array is denoted by a routine
              of value NULL.  If the discriminant is not found in the choices
              array, then the defaultarm procedure is called (if it is not NULL).
              Returns one if it succeeds, zero otherwise.

       bool_t xdr_vector(XDR *xdrs, char *arrp, unsigned int size,
                         unsigned int elsize, xdrproc_t elproc);

              A filter primitive that translates between fixed-length arrays and
              their corresponding external representations.  The argument arrp is
              the address of the pointer to the array, while size is the element
              count of the array.  The argument elsize is the sizeof each of the
              array's elements, and elproc is an XDR filter that translates
              between the array elements' C form, and their external
              representation.  This routine returns one if it succeeds, zero
              otherwise.

       bool_t xdr_void(void);

              This routine always returns one.  It may be passed to RPC routines
              that require a function argument, where nothing is to be done.

       bool_t xdr_wrapstring(XDR *xdrs, char **sp);

              A primitive that calls xdr_string(xdrs, sp,MAXUN.UNSIGNED ); where
              MAXUN.UNSIGNED is the maximum value of an unsigned integer.
              xdr_wrapstring() is handy because the RPC package passes a maximum
              of two XDR routines as arguments, and xdr_string(), one of the most
              frequently used primitives, requires three.  Returns one if it
              succeeds, zero otherwise.

SEE ALSO top

       rpc(3)

       The following manuals:
              eXternal Data Representation Standard: Protocol Specification
              eXternal Data Representation: Sun Technical Notes
              XDR: External Data Representation Standard, RFC 1014, Sun
              Microsystems, Inc., USC-ISI.

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-12-30                              XDR(3)


y0(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON The Linux Programming Interface

Y0(3)                        Linux Programmer's Manual                       Y0(3)

NAME top

       y0,  y0f,  y0l, y1, y1f, y1l, yn, ynf, ynl - Bessel functions of the second
       kind

SYNOPSIS top

       #include <math.h>

       double y0(double x);
       double y1(double x);
       double yn(int n, double x);

       float y0f(float x);
       float y1f(float x);
       float ynf(int n, float x);

       long double y0l(long double x);
       long double y1l(long double x);
       long double ynl(int n, long double x);

       Link with -lm.

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

       y0(), y1(), yn():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE
       y0f(), y0l(), y1f(), y1l(), ynf(), ynl():
           _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE >= 600

DESCRIPTION top

       The y0() and y1() functions return Bessel functions of x of the second kind
       of orders 0 and 1, respectively.  The yn() function returns the Bessel
       function of x of the second kind of order n.

       The value of x must be positive.

       The y0f() etc. and y0l() etc. functions are versions that take and return
       float and long double values, respectively.

RETURN VALUE top

       On success, these functions return the appropriate Bessel value of the
       second kind for x.

       If x is a NaN, a NaN is returned.

       If x is negative, a domain error occurs, and the functions return
       -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL, respectively.  (POSIX.1-2001 also
       allows a NaN return for this case.)

       If x is 0.0, a pole error occurs, and the functions return -HUGE_VAL,
       -HUGE_VALF, or -HUGE_VALL, respectively.

       If the result underflows, a range error occurs, and the functions return
       0.0

       If the result overflows, a range error occurs, and the functions return
       -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL, respectively.  (POSIX.1-2001 also
       allows a 0.0 return for this case.)

ERRORS top

       See math_error(7) for information on how to determine whether an error has
       occurred when calling these functions.

       The following errors can occur:

       Domain error: x is negative
              errno is set to EDOM.  An invalid floating-point exception
              (FE_INVALID) is raised.

       Pole error: x is 0.0
              errno is set to ERANGE (but see BUGS).  No FE_DIVBYZERO exception is
              returned by fetestexcept(3) for this case.

       Range error: result underflow
              errno is set to ERANGE.  No FE_UNDERFLOW exception is returned by
              fetestexcept(3) for this case.

       Range error: result overflow
              errno is not set for this case.  An overflow floating-point
              exception (FE_OVERFLOW) is raised.

CONFORMING TO top

       The functions returning double conform to SVr4, 4.3BSD, POSIX.1-2001.  The
       others are nonstandard functions that also exist on the BSDs.

BUGS top

       On a pole error, these functions set errno to EDOM, instead of ERANGE as
       POSIX.1-2004 requires.

       In glibc version 2.3.2 and earlier, these functions do not raise an invalid
       floating-point exception (FE_INVALID) when a domain error occurs.

SEE ALSO top

       j0(3)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2008-08-10                               Y0(3)


zdump(8) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON The Linux Programming Interface

ZDUMP(8)                    Linux System Administration                   ZDUMP(8)

NAME top

       zdump - timezone dumper

SYNOPSIS top

       zdump [ -v ] [ -c cutoffyear ] [ zonename ... ]

DESCRIPTION top

       Zdump prints the current time in each zonename named on the command line.

       These options are available:

       -v     For each zonename on the command line, print the time at the lowest
              possible time value, the time one day after the lowest possible time
              value, the times both one second before and exactly at each detected
              time discontinuity, the time at one day less than the highest
              possible time value, and the time at the highest possible time
              value.  Each line ends with isdst=1 if the given time is Daylight
              Saving Time or isdst=0 otherwise.

       -c [22mcutoffyear[0m
              Cut off the verbose output near the start of the given year.

SEE ALSO top

       tzfile(5), zic(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2007-05-18                            ZDUMP(8)


zic(8) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | NOTES | SEE ALSO | COLOPHON The Linux Programming Interface

ZIC(8)                      Linux System Administration                     ZIC(8)

NAME top

       zic - timezone compiler

SYNOPSIS top

       zic  [  -v  ]  [  -d  directory  ]  [ -l localtime ] [ -p posixrules ] [ -L
       leapsecondfilename ] [ -s ] [ -y command ] [ filename ... ]

DESCRIPTION top

       Zic reads text from the file(s) named on the command line and creates the
       time conversion information files specified in this input.  If a filename
       is -, the standard input is read.

       These options are available:

       -d [22mdirectory[0m
              Create time conversion information files in the named directory
              rather than in the standard directory named below.

       -l [22mtimezone[0m
              Use the given timezone as local time.  Zic will act as if the input
              contained a link line of the form

                   Link timezone       localtime

       -p [22mtimezone[0m
              Use the given timezone's rules when handling POSIX-format timezone
              environment variables.  Zic will act as if the input contained a
              link line of the form

                   Link timezone       posixrules

       -L [22mleapsecondfilename[0m
              Read leap second information from the file with the given name.  If
              this option is not used, no leap second information appears in
              output files.

       -v     Complain if a year that appears in a data file is outside the range
              of years representable by time(2) values.

       -s     Limit time values stored in output files to values that are the same
              whether they're taken to be signed or unsigned.  You can use this
              option to generate SVVS-compatible files.

       -y [22mcommand[0m
              Use the given command rather than yearistype when checking year
              types (see below).

       Input lines are made up of fields.  Fields are separated from one another
       by any number of white space characters.  Leading and trailing white space
       on input lines is ignored.  An unquoted sharp character (#) in the input
       introduces a comment which extends to the end of the line the sharp
       character appears on.  White space characters and sharp characters may be
       enclosed in double quotes (") if they're to be used as part of a field.
       Any line that is blank (after comment stripping) is ignored.  Nonblank
       lines are expected to be of one of three types: rule lines, zone lines, and
       link lines.

       A rule line has the form

            Rule  NAME  FROM  TO    TYPE  IN   ON       AT    SAVE  LETTER/S

       For example:

            Rule  US    1967  1973  -     Apr  lastSun  2:00  1:00  D

       The fields that make up a rule line are:

       NAME    Gives the (arbitrary) name of the set of rules this rule is part
               of.

       FROM    Gives the first year in which the rule applies.  Any integer year
               can be supplied; the Gregorian calendar is assumed.  The word
               minimum (or an abbreviation) means the minimum year representable
               as an integer.  The word maximum (or an abbreviation) means the
               maximum year representable as an integer.  Rules can describe times
               that are not representable as time values, with the unrepresentable
               times ignored; this allows rules to be portable among hosts with
               differing time value types.

       TO      Gives the final year in which the rule applies.  In addition to
               minimum and maximum (as above), the word only (or an abbreviation)
               may be used to repeat the value of the FROM field.

       TYPE    Gives the type of year in which the rule applies.  If TYPE is -
               then the rule applies in all years between FROM and TO inclusive.
               If TYPE is something else, then zic executes the command
                    yearistype year type
               to check the type of a year: an exit status of zero is taken to
               mean that the year is of the given type; an exit status of one is
               taken to mean that the year is not of the given type.

       IN      Names the month in which the rule takes effect.  Month names may be
               abbreviated.

       ON      Gives the day on which the rule takes effect.  Recognized forms
               include:

                    5        the fifth of the month
                    lastSun  the last Sunday in the month
                    lastMon  the last Monday in the month
                    Sun>=8   first Sunday on or after the eighth
                    Sun<=25  last Sunday on or before the 25th

               Names of days of the week may be abbreviated or spelled out in
               full.  Note that there must be no spaces within the ON field.

       AT      Gives the time of day at which the rule takes effect.  Recognized
               forms include:

                    2        time in hours
                    2:00     time in hours and minutes
                    15:00    24-hour format time (for times after noon)
                    1:28:14  time in hours, minutes, and seconds
                    -        equivalent to 0

               where hour 0 is midnight at the start of the day, and hour 24 is
               midnight at the end of the day.  Any of these forms may be followed
               by the letter w if the given time is local "wall clock" time, s if
               the given time is local "standard" time, or u (or g or z) if the
               given time is universal time; in the absence of an indicator, wall
               clock time is assumed.

       SAVE    Gives the amount of time to be added to local standard time when
               the rule is in effect.  This field has the same format as the AT
               field (although, of course, the w and s suffixes are not used).

       LETTER/S
               Gives the "variable part" (for example, the "S" or "D" in "EST" or
               "EDT") of timezone abbreviations to be used when this rule is in
               effect.  If this field is -, the variable part is null.

       A zone line has the form

            Zone  NAME                UTCOFF  RULES/SAVE  FORMAT  [UNTIL]

       For example:

            Zone  Australia/Adelaide  9:30    Aus         CST     1971 Oct 31 2:00

       The fields that make up a zone line are:

       NAME  The name of the timezone.  This is the name used in creating the time
             conversion information file for the zone.

       UTCOFF
             The amount of time to add to UTC to get standard time in this zone.
             This field has the same format as the AT and SAVE fields of rule
             lines; begin the field with a minus sign if time must be subtracted
             from UTC.

       RULES/SAVE
             The name of the rule(s) that apply in the timezone or, alternately,
             an amount of time to add to local standard time.  If this field is -
             then standard time always applies in the timezone.

       FORMAT
             The format for timezone abbreviations in this timezone.  The pair of
             characters %s is used to show where the "variable part" of the
             timezone abbreviation goes.  Alternately, a slash (/) separates
             standard and daylight abbreviations.

       UNTIL The time at which the UTC offset or the rule(s) change for a
             location.  It is specified as a year, a month, a day, and a time of
             day.  If this is specified, the timezone information is generated
             from the given UTC offset and rule change until the time specified.
             The month, day, and time of day have the same format as the IN, ON,
             and AT columns of a rule; trailing columns can be omitted, and
             default to the earliest possible value for the missing columns.

             The next line must be a "continuation" line; this has the same form
             as a zone line except that the string "Zone" and the name are
             omitted, as the continuation line will place information starting at
             the time specified as the UNTIL field in the previous line in the
             file used by the previous line.  Continuation lines may contain an
             UNTIL field, just as zone lines do, indicating that the next line is
             a further continuation.

       A link line has the form

            Link  LINK-FROM        LINK-TO

       For example:

            Link  Europe/Istanbul  Asia/Istanbul

       The LINK-FROM field should appear as the NAME field in some zone line; the
       LINK-TO field is used as an alternate name for that zone.

       Except for continuation lines, lines may appear in any order in the input.

       Lines in the file that describes leap seconds have the following form:

            Leap  YEAR  MONTH  DAY  HH:MM:SS  CORR  R/S

       For example:

            Leap  1974  Dec    31   23:59:60  +     S

       The YEAR, MONTH, DAY, and HH:MM:SS fields tell when the leap second
       happened.  The CORR field should be "+" if a second was added or "-" if a
       second was skipped.  The R/S field should be (an abbreviation of)
       "Stationary" if the leap second time given by the other fields should be
       interpreted as UTC or (an abbreviation of) "Rolling" if the leap second
       time given by the other fields should be interpreted as local wall clock
       time.

FILES top

       /usr/local/etc/zoneinfo standard directory used for created files

NOTES top

       For areas with more than two types of local time, you may need to use local
       standard time in the AT field of the earliest transition time's rule to
       ensure that the earliest transition time recorded in the compiled file is
       correct.

SEE ALSO top

       tzfile(5), zdump(8)

COLOPHON top

       This page is part of release 3.45 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/.

                                    2010-02-25                              ZIC(8)


_syscall(2) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FILES | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

_SYSCALL(2)                  Linux Programmer's Manual                 _SYSCALL(2)

NAME top

       _syscall - invoking a system call without library support (OBSOLETE)

SYNOPSIS top

       #include <linux/unistd.h>

       A _syscall macro

       desired system call

DESCRIPTION top

       The important thing to know about a system call is its prototype.  You need
       to know how many arguments, their types, and the function return type.
       There are seven macros that make the actual call into the system easier.
       They have the form:

              _syscallX(type,name,type1,arg1,type2,arg2,...)

       where

              X is 0-6, which are the number of arguments taken by the system call

              type is the return type of the system call

              name is the name of the system call

              typeN is the Nth argument's type

              argN is the name of the Nth argument

       These macros create a function called name with the arguments you specify.
       Once you include the _syscall() in your source file, you call the system
       call by name.

FILES top

       /usr/include/linux/unistd.h

CONFORMING TO top

       The use of these macros is Linux-specific, and deprecated.

NOTES top

       Starting around kernel 2.6.18, the _syscall macros were removed from header
       files supplied to user space.  Use syscall(2) instead.  (Some
       architectures, notably ia64, never provided the _syscall macros; on those
       architectures, syscall(2) was always required.)

       The _syscall() macros do not produce a prototype.  You may have to create
       one, especially for C++ users.

       System calls are not required to return only positive or negative error
       codes.  You need to read the source to be sure how it will return errors.
       Usually, it is the negative of a standard error code, for example, -EPERM.
       The _syscall() macros will return the result r of the system call when r is
       nonnegative, but will return -1 and set the variable errno to -r when r is
       negative.  For the error codes, see errno(3).

       When defining a system call, the argument types must be passed by-value or
       by-pointer (for aggregates like structs).

EXAMPLE top

       #include <stdio.h>
       #include <stdlib.h>
       #include <errno.h>
       #include <linux/unistd.h>       /* for _syscallX macros/related stuff */
       #include <linux/kernel.h>       /* for struct sysinfo */

       _syscall1(int, sysinfo, struct sysinfo *, info);

       /* Note: if you copy directly from the nroff source, remember to
       REMOVE the extra backslashes in the printf statement. */

       int
       main(void)
       {
           struct sysinfo s_info;
           int error;

           error = sysinfo(&s_info);
           printf("code error = %d\n", error);
           printf("Uptime = %lds\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\n"
                  "RAM: total %lu / free %lu / shared %lu\n"
                  "Memory in buffers = %lu\nSwap: total %lu / free %lu\n"
                  "Number of processes = %d\n",
                  s_info.uptime, s_info.loads[0],
                  s_info.loads[1], s_info.loads[2],
                  s_info.totalram, s_info.freeram,
                  s_info.sharedram, s_info.bufferram,
                  s_info.totalswap, s_info.freeswap,
                  s_info.procs);
           exit(EXIT_SUCCESS);
       }

Sample Output

       code error = 0
       uptime = 502034s
       Load: 1 min 13376 / 5 min 5504 / 15 min 1152
       RAM: total 15343616 / free 827392 / shared 8237056
       Memory in buffers = 5066752
       Swap: total 27881472 / free 24698880
       Number of processes = 40

SEE ALSO top

       intro(2), syscall(2), errno(3)

COLOPHON top

       This page is part of release 3.45 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-12-19                         _SYSCALL(2)


__setfpucw(3) - Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON The Linux Programming Interface

__SETFPUCW(3)                Linux Programmer's Manual               __SETFPUCW(3)

NAME top

       __setfpucw - set FPU control word on i386 architecture (obsolete)

SYNOPSIS top

       #include <i386/fpu_control.h>

       void __setfpucw(unsigned short control_word);

DESCRIPTION top

       __setfpucw() transfers control_word to the registers of the FPU (floating-
       point unit) on the i386 architecture.  This was used to control floating-
       point precision, rounding and floating-point exceptions.

CONFORMING TO top

       This function was a nonstandard GNU extension.

NOTES top

       As of glibc 2.1 this function does not exist anymore.  There are new
       functions from C99, with prototypes in <fenv.h>, to control FPU rounding
       modes, like fegetround, fesetround, and the floating-point environment,
       like fegetenv, feholdexcept, fesetenv, feupdateenv and FPU exception
       handling, like feclearexcept, fegetexceptflag, feraiseexcept,
       fesetexceptflag, fetestexcept.

       If direct access to the FPU control word is still needed, the _FPU_GETCW
       and _FPU_SETCW macros from <fpu_control.h> can be used.

EXAMPLE top

       __setfpucw(0x1372)

       Set FPU control word on the i386 architecture to
            - extended precision
            - rounding to nearest
            - exceptions on overflow, zero divide and NaN

SEE ALSO top

       feclearexcept(3)
       <fpu_control.h>

COLOPHON top

       This page is part of release 3.45 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                               1997-03-08                       __SETFPUCW(3)